@teamvibe/poller 0.8.7-rc.1 → 0.8.8

package/dist/subscription-selection.d.ts

@@ -10,6 +10,13 @@ export declare const PROBE_USAGE_TTL_MS = 60000;
 export declare const POOL_RECHECK_MS: number;
 /** Safety hold from the rejection observation when the provider gives no reset. */
 export declare const REJECTED_BLOCK_MS: number;
+export declare const VERIFICATION_MAX_BACKOFF_MS: number;
+export interface VerificationEvidence {
+    observedAt: number;
+    source: 'passive' | 'probe';
+    status: 'allowed' | 'allowed_warning';
+    percent: number;
+}
 export interface AccountIdentity {
     workspaceId: string;
     accountId: string;
@@ -47,6 +54,11 @@ export interface UsageWindow {
     source?: 'passive' | 'probe';
     percent?: number;
     resetAt?: number;
+    /** Missing on legacy rejections means the first consecutive rejection. */
+    rejectionCount?: number;
+    lastVerificationAttemptAt?: number;
+    /** A genuine same-window measurement; never inferred from an omitted meter. */
+    verificationEvidence?: VerificationEvidence;
 }
 export interface UsageObservation {
     pollerVersion?: string;
@@ -67,11 +79,11 @@ export declare function projectLegacyFableUsage<T extends UsageObservation | und
  * Deduplicate uncertain windows before splitting measurements from rejections.
  */
 export declare function supersedeLegacyFableProjections(observations: readonly (UsageObservation | undefined)[], now: number): (UsageObservation | undefined)[];
-/** Latest measurements plus durable genuine rejections; omission or success never clears a genuine hold. */
+/** Latest measurements plus durable rejections; only a claimed real spawn can clear a hold. */
 export declare function mergeUsageObservations(observations: readonly (UsageObservation | undefined)[], now: number): UsageObservation | undefined;
 /** Preserve last-known meters, projecting legacy identity before its global companion is replaced. */
 export declare function mergePersistedUsageObservations(previous: UsageObservation | undefined, incoming: UsageObservation | undefined, now: number): UsageObservation | undefined;
-export interface ReactiveExhaustion {
+export interface ReactiveExhaustion extends Pick<UsageWindow, 'rejectionCount' | 'lastVerificationAttemptAt' | 'verificationEvidence'> {
     observedAt: number;
     quota: ClaudeQuotaFailure;
 }
@@ -106,6 +118,13 @@ export declare function record(value: unknown): Record<string, unknown>;
 export declare function normalizePassiveUsage(value: unknown, observedAt: number): UsageObservation;
 export declare function normalizeProbeUsage(value: unknown, observedAt: number): UsageObservation;
 export declare function family(model: string | undefined): 'sonnet' | 'opus' | 'haiku' | 'fable' | undefined;
+export declare function rejectionResetAt(window: UsageWindow, observedAt: number): number;
+export declare function verificationEligibleAt(window: UsageWindow, observedAt: number): number;
+export declare function rejectionEvidence(usage: UsageObservation | undefined, window: UsageWindow, now: number): VerificationEvidence | undefined;
+export declare function rejectionEligibleAt(usage: UsageObservation | undefined, window: UsageWindow, account: AccountIdentity, now: number): number;
+export declare function reactiveUsageWindow(reactive: ReactiveExhaustion): UsageWindow;
+/** Due windows are claimed durably at the real spawn boundary, never by pure selection. */
+export declare function verificationWindows(account: AccountIdentity, state: AccountUsageState, model: string | undefined, now: number): UsageWindow[];
 export declare function reactiveEligibleAt(reactive: ReactiveExhaustion): number;
 /** Pure policy. Unknown is eligible after every known/reactive blocker is ruled out. */
 export declare function selectSubscriptionAccount<A extends AccountIdentity>(input: {

package/dist/subscription-selection.js

@@ -8,6 +8,7 @@ export const PROBE_USAGE_TTL_MS = 60_000;
 export const POOL_RECHECK_MS = 15 * 60_000;
 /** Safety hold from the rejection observation when the provider gives no reset. */
 export const REJECTED_BLOCK_MS = 15 * 60_000;
+export const VERIFICATION_MAX_BACKOFF_MS = 8 * 60 * 60_000;
 /** Passive and probe percentages remain lower bounds until each window resets. */
 export function usageWindowExpiresAt(usage, window) {
     const ttlExpiry = (window.observedAt ?? usage.observedAt) + ((window.source ?? usage.source) === 'passive' ? PASSIVE_USAGE_TTL_MS : PROBE_USAGE_TTL_MS);
@@ -116,7 +117,7 @@ export function supersedeLegacyFableProjections(observations, now) {
         }),
     }));
 }
-/** Latest measurements plus durable genuine rejections; omission or success never clears a genuine hold. */
+/** Latest measurements plus durable rejections; only a claimed real spawn can clear a hold. */
 export function mergeUsageObservations(observations, now) {
     let latest;
     const rejected = new Map();
@@ -139,13 +140,24 @@ export function mergeUsageObservations(observations, now) {
             if (w.status !== 'rejected')
                 continue;
             const previous = rejected.get(key);
-            if (!previous || observedAt >= previous.observedAt)
-                rejected.set(key, { ...w, observedAt, source: w.source ?? usage.source });
+            if (!previous || observedAt >= previous.observedAt) {
+                const consecutive = previous && observedAt > previous.observedAt && observedAt < rejectionResetAt(previous, previous.observedAt);
+                rejected.set(key, {
+                    ...(previous?.observedAt === observedAt ? previous : {}),
+                    ...w, observedAt, source: w.source ?? usage.source,
+                    ...(consecutive && w.resetAt === undefined && previous.resetAt !== undefined ? { resetAt: previous.resetAt } : {}),
+                    ...(consecutive || w.rejectionCount !== undefined || previous?.observedAt === observedAt && previous.rejectionCount !== undefined
+                        ? { rejectionCount: Math.max(w.rejectionCount ?? 1, consecutive ? (previous.rejectionCount ?? 1) + 1 : previous?.rejectionCount ?? 1) } : {}),
+                });
+            }
         }
     }
     if (!latest)
         return undefined;
-    const active = [...rejected.values()].filter(w => now < (w.resetAt ?? w.observedAt + REJECTED_BLOCK_MS));
+    const active = [...rejected.values()].filter(w => now < rejectionResetAt(w, w.observedAt)).map(w => {
+        const evidence = latestVerificationEvidence(observations, w, w.observedAt, now);
+        return evidence ? { ...w, verificationEvidence: evidence } : w;
+    });
     const retained = [...scopedExhausted.values()].filter(w => isScopedExhaustion(w) &&
         !latest.windows.some(other => other.window === w.window && other.scope === w.scope) &&
         !active.some(other => other.window === w.window && other.scope === w.scope) &&
@@ -281,7 +293,9 @@ export function normalizeProbeUsage(value, observedAt) {
         if (raw == null)
             continue;
         const item = record(raw);
-        windows.push({ window, scope, percent: percent(item['utilization'], 100), resetAt: date(item['resets_at']) });
+        windows.push({ window, scope, percent: percent(item['utilization'], 100), resetAt: date(item['resets_at']),
+            ...(percent(item['utilization'], 100) !== undefined ? { status: 'allowed' } : {}),
+        });
     }
     // The optional endpoint is undocumented. Accept only the explicit window /
     // model form below; arbitrary internal codenames never map to a family.
@@ -295,7 +309,9 @@ export function normalizeProbeUsage(value, observedAt) {
             }
             const model = item['model'];
             const scope = model === 'global' ? 'global' : typeof model === 'string' ? family(model) ?? 'uncertain' : 'uncertain';
-            windows.push({ window, scope, percent: percent(item['utilization'], 100), resetAt: date(item['resets_at']) });
+            windows.push({ window, scope, percent: percent(item['utilization'], 100), resetAt: date(item['resets_at']),
+                ...(percent(item['utilization'], 100) !== undefined ? { status: 'allowed' } : {}),
+            });
         }
         if (info['limits'].length > 128)
             windows.push({ window: 'seven_day', scope: 'uncertain' });
@@ -308,6 +324,63 @@ export function family(model) {
 function applicable(scope, model) {
     return scope === 'global' || scope === 'uncertain' || family(model) === undefined || scope === family(model);
 }
+export function rejectionResetAt(window, observedAt) {
+    return window.resetAt ?? observedAt + REJECTED_BLOCK_MS;
+}
+export function verificationEligibleAt(window, observedAt) {
+    return Math.min(rejectionResetAt(window, observedAt), observedAt +
+        Math.min(VERIFICATION_MAX_BACKOFF_MS, REJECTED_BLOCK_MS * 2 ** Math.min(5, Math.max(0, (window.rejectionCount ?? 1) - 1))));
+}
+function latestVerificationEvidence(observations, rejected, rejectedAt, now) {
+    let evidence = rejected.verificationEvidence;
+    if (evidence && (evidence.observedAt <= rejectedAt || evidence.observedAt > now))
+        evidence = undefined;
+    // Uncertain/projected identity cannot prove that the provider's exact quota recovered.
+    if (rejected.scope === 'uncertain' || rejected.kind === 'legacy-uncertain-seven-day')
+        return undefined;
+    for (const usage of observations) {
+        if (!usage || usage.observedAt > now)
+            continue;
+        for (const w of usage.windows) {
+            const observedAt = w.observedAt ?? usage.observedAt;
+            if (w.window !== rejected.window || w.scope !== rejected.scope || w.kind === 'legacy-uncertain-seven-day' ||
+                observedAt <= rejectedAt || observedAt > now || w.percent === undefined ||
+                (w.status !== 'allowed' && w.status !== 'allowed_warning'))
+                continue;
+            if (!evidence || observedAt > evidence.observedAt || observedAt === evidence.observedAt && w.percent > evidence.percent)
+                evidence = { observedAt, source: w.source ?? usage.source, status: w.status, percent: w.percent };
+        }
+    }
+    return evidence;
+}
+export function rejectionEvidence(usage, window, now) {
+    return latestVerificationEvidence([usage], window, window.observedAt ?? usage?.observedAt ?? now, now);
+}
+export function rejectionEligibleAt(usage, window, account, now) {
+    const observedAt = window.observedAt ?? usage?.observedAt ?? now;
+    const resetAt = rejectionResetAt(window, observedAt);
+    const evidence = rejectionEvidence(usage, window, now);
+    return evidence && evidence.percent < (account.useFullQuota ? 100 : USAGE_THRESHOLD_PERCENT) &&
+        !(window.lastVerificationAttemptAt !== undefined && window.lastVerificationAttemptAt >= observedAt)
+        ? verificationEligibleAt(window, observedAt) : resetAt;
+}
+export function reactiveUsageWindow(reactive) {
+    return {
+        window: reactive.quota.window ?? 'seven_day',
+        scope: reactive.quota.modelScope ? family(reactive.quota.modelScope) ?? 'uncertain' : 'global',
+        status: 'rejected', observedAt: reactive.observedAt, resetAt: reactiveEligibleAt(reactive),
+        rejectionCount: reactive.rejectionCount, lastVerificationAttemptAt: reactive.lastVerificationAttemptAt,
+        verificationEvidence: reactive.verificationEvidence,
+    };
+}
+/** Due windows are claimed durably at the real spawn boundary, never by pure selection. */
+export function verificationWindows(account, state, model, now) {
+    return [...(state.usage?.windows ?? []), ...(state.reactive ?? []).filter(r => r.quota.window !== undefined).map(reactiveUsageWindow)].filter(w => {
+        const observedAt = w.observedAt ?? state.usage?.observedAt ?? now;
+        return w.status === 'rejected' && observedAt <= now && applicable(w.scope, model) &&
+            now < rejectionResetAt(w, observedAt) && now >= rejectionEligibleAt(state.usage, w, account, now);
+    });
+}
 export function reactiveEligibleAt(reactive) {
     const parsed = reactive.quota.resetAt ? Date.parse(reactive.quota.resetAt) : NaN;
     return Number.isFinite(parsed) && parsed > reactive.observedAt ? parsed : reactive.observedAt + POOL_RECHECK_MS;
@@ -342,6 +415,7 @@ export function selectSubscriptionAccount(input) {
             continue;
         const state = input.states[account.accountId];
         const blockers = [];
+        const usage = supersedeLegacyFableProjections([state?.usage], input.now)[0];
         for (const reactive of state?.reactive ?? []) {
             // Like durable pause createdAt, future observations expire on clock rollback.
             if (input.now < reactive.observedAt)
@@ -349,12 +423,11 @@ export function selectSubscriptionAccount(input) {
             const scope = reactive.quota.modelScope;
             if (scope && family(scope) && family(input.model) && family(scope) !== family(input.model))
                 continue;
-            const until = reactiveEligibleAt(reactive);
+            const until = reactive.quota.window ? rejectionEligibleAt(usage, reactiveUsageWindow(reactive), account, input.now) : reactiveEligibleAt(reactive);
             if (input.now < until)
                 blockers.push(until);
         }
-        const usage = supersedeLegacyFableProjections([state?.usage], input.now)[0];
-        // A provider rejection outlives snapshot freshness. Never score it as headroom.
+        // A contradicted rejection permits one claimed verification after backoff.
         if (usage && usage.observedAt <= input.now) {
             for (const w of usage.windows) {
                 if (w.status !== 'rejected' || !applicable(w.scope, input.model))
@@ -362,7 +435,7 @@ export function selectSubscriptionAccount(input) {
                 const observedAt = w.observedAt ?? usage.observedAt;
                 if (observedAt > input.now)
                     continue;
-                const until = w.resetAt ?? observedAt + REJECTED_BLOCK_MS;
+                const until = rejectionEligibleAt(usage, w, account, input.now);
                 if (input.now < until)
                     blockers.push(until);
             }
@@ -414,14 +487,18 @@ export function blockingUsageWindows(account, state, model, now) {
     const usage = supersedeLegacyFableProjections([state?.usage], now)[0];
     const windows = [];
     for (const window of usage?.windows ?? []) {
-        const result = selectSubscriptionAccount({ pool, states: { [account.accountId]: { usage: { ...usage, windows: [window] } } }, model, now });
+        const evidence = window.status === 'rejected' ? rejectionEvidence(usage, window, now) : undefined;
+        const result = selectSubscriptionAccount({ pool, states: { [account.accountId]: { usage: { ...usage, windows: [{ ...window, ...(evidence ? { verificationEvidence: evidence } : {}) }] } } }, model, now });
         if (result.kind === 'deferred')
             windows.push({ ...window, eligibleAt: result.eligibleAt });
     }
     for (const reactive of state?.reactive ?? []) {
-        const result = selectSubscriptionAccount({ pool, states: { [account.accountId]: { reactive: [reactive] } }, model, now });
-        if (result.kind === 'deferred')
-            windows.push({ observedAt: reactive.observedAt, window: reactive.quota.window ?? 'seven_day', scope: reactive.quota.modelScope ? family(reactive.quota.modelScope) ?? 'uncertain' : 'global', status: 'rejected', resetAt: reactive.quota.resetAt ? Date.parse(reactive.quota.resetAt) : undefined, eligibleAt: result.eligibleAt });
+        const window = reactiveUsageWindow(reactive);
+        if (applicable(window.scope, model) && reactive.observedAt <= now) {
+            const eligibleAt = reactive.quota.window ? rejectionEligibleAt(usage, window, account, now) : reactiveEligibleAt(reactive);
+            if (now < eligibleAt)
+                windows.push({ ...window, resetAt: reactive.quota.resetAt ? Date.parse(reactive.quota.resetAt) : undefined, eligibleAt });
+        }
     }
     return windows;
 }

package/dist/subscription-usage-store.d.ts

@@ -1,6 +1,6 @@
 import { type ClaudeRateLimitInfo } from './claude-rate-limit.js';
 import type { ClaudeQuotaFailure } from './claude-quota.js';
-import { type AccountIdentity, type AccountUsageState, type ReactiveExhaustion, type UsageObservation } from './subscription-selection.js';
+import { type AccountIdentity, type AccountUsageState, type ReactiveExhaustion, type UsageObservation, type UsageWindow } from './subscription-selection.js';
 export type UsageKey = Pick<AccountIdentity, 'workspaceId' | 'accountId' | 'credentialVersion'>;
 export type ProbeStatus = 'attempted' | 'ok' | 'unsupported' | 'unauthorized' | 'unavailable' | 'cancelled';
 export interface ProbeObservation {
@@ -34,6 +34,9 @@ export interface SubscriptionUsageStore {
     claimLocalProbe(key: UsageKey, observedAt: number, minIntervalMs: number): Promise<boolean>;
     claimProbeRequest(requestId: string, expiresAt: number): Promise<boolean>;
     finishProbe(key: UsageKey, observation: ProbeObservation): Promise<void>;
+    /** Atomic revalidation and one durable claim immediately before a real spawn. */
+    beginVerification(key: AccountIdentity, model: string | undefined, observedAt: number): Promise<UsageWindow[] | undefined>;
+    completeVerification(key: UsageKey, attemptAt: number, observedAt: number): Promise<void>;
 }
 export declare function usageStateForSelection(state: StoredAccountUsage, now: number): AccountUsageState;
 export declare class SubscriptionUsageStoreError extends Error {
@@ -54,4 +57,6 @@ export declare class FileSubscriptionUsageStore implements SubscriptionUsageStor
     /** Request claims live in the local data directory, alongside usage, never in a brain. */
     claimProbeRequest(requestId: string, expiresAt: number): Promise<boolean>;
     finishProbe(key: UsageKey, observation: ProbeObservation): Promise<void>;
+    beginVerification(key: AccountIdentity, model: string | undefined, observedAt: number): Promise<UsageWindow[] | undefined>;
+    completeVerification(key: UsageKey, attemptAt: number, observedAt: number): Promise<void>;
 }

package/dist/subscription-usage-store.js

@@ -1,9 +1,10 @@
 import { redactStartupText } from './redact-text.js';
+import { logger } from './logger.js';
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { parseClaudeRateLimitInfo } from './claude-rate-limit.js';
-import { normalizePassiveUsage, mergePersistedUsageObservations, mergeUsageObservations, record, reactiveEligibleAt, family } from './subscription-selection.js';
+import { normalizePassiveUsage, mergePersistedUsageObservations, mergeUsageObservations, record, reactiveEligibleAt, reactiveUsageWindow, rejectionEvidence, rejectionResetAt, verificationEligibleAt, verificationWindows, selectSubscriptionAccount, family, USAGE_THRESHOLD_PERCENT } from './subscription-selection.js';
 export function usageStateForSelection(state, now) {
     return {
         usage: mergeUsageObservations([
@@ -80,12 +81,31 @@ function safeUsage(value, source) {
         if (observedAt !== undefined)
             validTime(observedAt);
         const source = w['source'] === 'passive' || w['source'] === 'probe' ? w['source'] : undefined;
-        return { window, scope, ...((w['kind'] === 'seven_day_overage_included' || w['kind'] === 'legacy-uncertain-seven-day') ? { kind: w['kind'] } : {}), percent, resetAt, ...(status ? { status } : {}), ...(observedAt ? { observedAt } : {}), ...(source ? { source } : {}) };
+        return { window, scope, ...((w['kind'] === 'seven_day_overage_included' || w['kind'] === 'legacy-uncertain-seven-day') ? { kind: w['kind'] } : {}), percent, resetAt, ...(status ? { status } : {}), ...(observedAt ? { observedAt } : {}), ...(source ? { source } : {}), ...safeVerificationFields(w) };
     });
     if (usage['windows'].length > 133)
         windows.push({ window: 'seven_day', scope: 'uncertain' });
     return { source, observedAt: usage['observedAt'], windows };
 }
+function safeVerificationFields(value) {
+    const result = {};
+    const count = value['rejectionCount'];
+    if (typeof count === 'number' && Number.isSafeInteger(count) && count >= 1)
+        result.rejectionCount = count;
+    const attemptAt = value['lastVerificationAttemptAt'];
+    if (typeof attemptAt === 'number') {
+        validTime(attemptAt);
+        result.lastVerificationAttemptAt = attemptAt;
+    }
+    const evidence = record(value['verificationEvidence']);
+    if (typeof evidence['observedAt'] === 'number' && (evidence['source'] === 'probe' || evidence['source'] === 'passive') &&
+        (evidence['status'] === 'allowed' || evidence['status'] === 'allowed_warning') &&
+        typeof evidence['percent'] === 'number' && Number.isFinite(evidence['percent']) && evidence['percent'] >= 0 && evidence['percent'] <= 100) {
+        validTime(evidence['observedAt']);
+        result.verificationEvidence = { observedAt: evidence['observedAt'], source: evidence['source'], status: evidence['status'], percent: evidence['percent'] };
+    }
+    return result;
+}
 function safeProbe(value) {
     const obj = record(value);
     const status = obj['status'];
@@ -126,7 +146,7 @@ function safeReactive(value) {
         if (typeof obj['observedAt'] !== 'number' || !obj['quota'] || typeof obj['quota'] !== 'object')
             throw new SubscriptionUsageStoreError();
         validTime(obj['observedAt']);
-        return { observedAt: obj['observedAt'], quota: safeQuota(obj['quota']) };
+        return { observedAt: obj['observedAt'], quota: safeQuota(obj['quota']), ...safeVerificationFields(obj) };
     });
 }
 /** One file per version + one reactive file per workspace/account. No credentials or raw provider bodies. */
@@ -139,6 +159,84 @@ export class FileSubscriptionUsageStore {
             throw new SubscriptionUsageStoreError();
         return join(this.#directory, `${createHash('sha256').update(JSON.stringify(parts)).digest('hex')}.json`);
     }
+    #claimPath(key, window, fallbackAt) {
+        // The epoch identifies the backoff step, so processes with different wall
+        // clocks still compete for the same exclusive marker.
+        const epoch = verificationEligibleAt(window, window.observedAt ?? fallbackAt);
+        return join(this.#directory, 'claims', `${encodeURIComponent(key.accountId)}.${window.scope}.${window.window}.${epoch}.claim`);
+    }
+    async #claimMarkers(key) {
+        const directory = join(this.#directory, 'claims');
+        const claims = new Map();
+        try {
+            const names = await readdir(directory);
+            const now = Date.now();
+            for (const name of names) {
+                if (!name.startsWith(`${encodeURIComponent(key.accountId)}.`) || !name.endsWith('.claim'))
+                    continue;
+                const path = join(directory, name);
+                try {
+                    const raw = await readFile(path, 'utf8');
+                    let marker;
+                    try {
+                        marker = JSON.parse(raw);
+                    }
+                    catch {
+                        // Exclusive creation already owns the step, including the interval
+                        // before metadata is written or a crash during that write.
+                        if (now - (await stat(path)).mtimeMs > 24 * 3600_000) {
+                            await rm(path, { force: true });
+                            continue;
+                        }
+                        const epoch = Number(name.split('.').at(-2));
+                        validTime(epoch);
+                        claims.set(path, epoch);
+                        continue;
+                    }
+                    validTime(marker.attemptAt);
+                    validTime(marker.resetAt);
+                    if (now - marker.attemptAt > 24 * 3600_000 || marker.resetAt <= now) {
+                        await rm(path, { force: true });
+                        continue;
+                    }
+                    claims.set(path, marker.attemptAt);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+            }
+            return claims;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return claims;
+            throw new SubscriptionUsageStoreError();
+        }
+    }
+    async #claimVerification(key, windows, observedAt) {
+        try {
+            await mkdir(join(this.#directory, 'claims'), { recursive: true, mode: 0o700 });
+            const markers = new Map(windows.map(w => [this.#claimPath(key, w, observedAt), w]));
+            for (const [path, window] of [...markers].sort(([a], [b]) => a.localeCompare(b))) {
+                const file = await open(path, 'wx', 0o600);
+                try {
+                    await file.writeFile(JSON.stringify({ attemptAt: observedAt, resetAt: rejectionResetAt(window, window.observedAt ?? observedAt) }));
+                }
+                finally {
+                    await file.close();
+                }
+            }
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            // A marker remains spent even if the JSON write fails. Readers consult
+            // markers as well, so restarting cannot launch the same verification.
+            throw new SubscriptionUsageStoreError();
+        }
+    }
     async #load(path, fallback) {
         try {
             const raw = await readFile(path, 'utf8');
@@ -169,6 +267,49 @@ export class FileSubscriptionUsageStore {
             await rm(temporary, { force: true }).catch(() => { });
         }
     }
+    #log(message) { logger.info(`[Pool] ${message}`); }
+    #logEvidence(previous, window, usage, now, threshold) {
+        const evidence = rejectionEvidence(usage, window, now);
+        if (evidence && evidence.percent < threshold && evidence.observedAt !== previous?.verificationEvidence?.observedAt &&
+            !(window.lastVerificationAttemptAt !== undefined && window.lastVerificationAttemptAt >= (window.observedAt ?? now))) {
+            this.#log(`rejection marked verifiable window=${window.window}/${window.scope} count=${window.rejectionCount ?? 1} evidence=${evidence.source}:${evidence.status}:${evidence.percent}% observedAt=${new Date(evidence.observedAt).toISOString()} eligibleAt=${new Date(verificationEligibleAt(window, window.observedAt ?? now)).toISOString()}`);
+        }
+    }
+    async #mergeUsage(key, state, previous, incoming, now) {
+        const path = this.#path(key, false);
+        const account = await this.#load(path, { reactive: [] });
+        account.reactive = safeReactive(account.reactive);
+        if (incoming)
+            incoming = { ...incoming, windows: incoming.windows.map(w => {
+                    if (w.status !== 'rejected')
+                        return w;
+                    const at = w.observedAt ?? incoming.observedAt;
+                    const prior = account.reactive.map(reactiveUsageWindow).find(r => r.window === w.window && r.scope === w.scope && r.observedAt <= at && r.resetAt > at);
+                    return prior ? { ...w, rejectionCount: Math.max(w.rejectionCount ?? 1, (prior.rejectionCount ?? 1) + Number(prior.observedAt < at)) } : w;
+                }) };
+        state.usage = mergePersistedUsageObservations(previous, incoming, now);
+        const threshold = key.useFullQuota ? 100 : USAGE_THRESHOLD_PERCENT;
+        if (state.usage)
+            state.usage = { ...state.usage, windows: state.usage.windows.map(w => w.status === 'rejected' ? { ...w, rejectionCount: w.rejectionCount ?? 1 } : w) };
+        for (const window of state.usage?.windows ?? []) {
+            if (window.status !== 'rejected')
+                continue;
+            const old = previous?.windows.find(w => w.status === 'rejected' && w.window === window.window && w.scope === window.scope);
+            this.#logEvidence(old, window, state.usage, now, threshold);
+            if (old?.lastVerificationAttemptAt !== undefined && window.observedAt > old.observedAt)
+                this.#log(`verification re-rejected window=${window.window}/${window.scope} count=${window.rejectionCount ?? 1} eligibleAt=${new Date(verificationEligibleAt(window, window.observedAt)).toISOString()}`);
+        }
+        const reactive = safeReactive(account.reactive).map(r => {
+            if (!r.quota.window)
+                return r;
+            const window = reactiveUsageWindow(r);
+            const verificationEvidence = rejectionEvidence(state.usage, window, now);
+            this.#logEvidence(window, { ...window, verificationEvidence }, state.usage, now, threshold);
+            return { ...r, verificationEvidence };
+        });
+        if (JSON.stringify(reactive) !== JSON.stringify(account.reactive))
+            await this.#save(path, { reactive });
+    }
     async read(key) {
         const [version, account] = await Promise.all([
             this.#load(this.#path(key, true), {}),
@@ -177,19 +318,32 @@ export class FileSubscriptionUsageStore {
         // Corrupt reactive data must never silently resurrect an exhausted account.
         if (!Array.isArray(account.reactive) || account.reactive.some(r => !r || !Number.isFinite(r.observedAt) || !r.quota))
             throw new SubscriptionUsageStoreError();
-        return { ...safeVersion(version), reactive: safeReactive(account.reactive) };
+        const state = { ...safeVersion(version), reactive: safeReactive(account.reactive) };
+        const claims = await this.#claimMarkers(key);
+        const claimedWindow = (w, fallbackAt) => {
+            const attemptAt = claims.get(this.#claimPath(key, w, fallbackAt));
+            return w.status === 'rejected' && attemptAt !== undefined ? { ...w, lastVerificationAttemptAt: Math.max(w.lastVerificationAttemptAt ?? 0, attemptAt) } : w;
+        };
+        if (state.usage)
+            state.usage = { ...state.usage, windows: state.usage.windows.map(w => claimedWindow(w, state.usage.observedAt)) };
+        state.reactive = state.reactive.map(r => ({ ...r, lastVerificationAttemptAt: claimedWindow(reactiveUsageWindow(r), r.observedAt).lastVerificationAttemptAt }));
+        return state;
     }
     async recordPassive(key, rateLimitInfo, observedAt, options) {
         validTime(observedAt);
         const path = this.#path(key, true);
-        await serial(path, async () => {
+        await serial(this.#path(key, false), async () => {
             const state = safeVersion(await this.#load(path, {}));
             if (state.passive && state.passive.observedAt > observedAt && !options?.expireFutureObservations)
                 return;
             // Retain Fable observation clocks even when the latest report omits its meter.
             const previous = state.usage ?? usageStateForSelection({ ...state, reactive: [] }, observedAt).usage;
             state.passive = { rateLimitInfo: safeRateLimitInfo(rateLimitInfo), observedAt };
-            state.usage = mergePersistedUsageObservations(previous, normalizePassiveUsage(state.passive.rateLimitInfo, observedAt), observedAt);
+            const incoming = normalizePassiveUsage(state.passive.rateLimitInfo, observedAt);
+            const status = state.passive.rateLimitInfo.status;
+            if (status === 'allowed' || status === 'allowed_warning')
+                incoming.windows = incoming.windows.map(w => ({ ...w, status: w.status ?? status }));
+            await this.#mergeUsage(key, state, previous, incoming, observedAt);
             await this.#save(path, state);
         });
     }
@@ -199,24 +353,41 @@ export class FileSubscriptionUsageStore {
         await serial(path, async () => {
             const state = await this.#load(path, { reactive: [] });
             state.reactive = safeReactive(state.reactive).filter(r => !options?.expireFutureObservations || r.observedAt <= observedAt);
-            const next = { observedAt, quota: safeQuota(quota) };
+            const next = { observedAt, quota: safeQuota(quota), rejectionCount: 1 };
             const until = reactiveEligibleAt;
             const sameScope = (r) => r.quota.modelScope === next.quota.modelScope && r.quota.window === next.quota.window;
             const previous = state.reactive.find(sameScope);
+            const version = safeVersion(await this.#load(this.#path(key, true), {}));
+            const window = reactiveUsageWindow(next);
+            const passive = version.usage?.windows.find(w => w.status === 'rejected' && w.window === window.window && w.scope === window.scope &&
+                (w.observedAt ?? version.usage.observedAt) <= observedAt && rejectionResetAt(w, w.observedAt ?? version.usage.observedAt) > observedAt);
             const reactive = state.reactive.filter(r => !sameScope(r) && until(r) > observedAt);
             const hasExplicitReset = (r) => r.quota.resetAt !== undefined && Date.parse(r.quota.resetAt) > r.observedAt;
             // A recheck is not a reset. New matching quota evidence can replace that
             // provisional deadline with its explicit reset, without clearing a known
             // active reset or accepting an older observation as revalidation.
             const revalidated = previous && next.observedAt >= previous.observedAt && !hasExplicitReset(previous) && hasExplicitReset(next);
-            reactive.push(previous && !revalidated && until(previous) > until(next) ? previous : next);
+            if (previous && next.observedAt < previous.observedAt)
+                reactive.push(previous);
+            else if (previous && next.observedAt === previous.observedAt && !revalidated)
+                reactive.push(previous);
+            else {
+                next.rejectionCount = Math.max(previous && until(previous) > observedAt ? (previous.rejectionCount ?? 1) + Number(previous.observedAt < observedAt) : 1, passive ? (passive.rejectionCount ?? 1) + Number((passive.observedAt ?? version.usage.observedAt) < observedAt) : 1);
+                if (previous && !next.quota.resetAt && until(previous) > until(next))
+                    next.quota.resetAt = previous.quota.resetAt;
+                if (!next.quota.resetAt && passive?.resetAt)
+                    next.quota.resetAt = new Date(passive.resetAt).toISOString();
+                reactive.push(next);
+                if (previous?.lastVerificationAttemptAt !== undefined || passive?.lastVerificationAttemptAt !== undefined)
+                    this.#log(`verification re-rejected window=${next.quota.window ?? 'seven_day'}/${next.quota.modelScope ?? 'global'} count=${next.rejectionCount} eligibleAt=${new Date(verificationEligibleAt(reactiveUsageWindow(next), observedAt)).toISOString()}`);
+            }
             await this.#save(path, { reactive });
         });
     }
     async beginProbe(key, observedAt) {
         validTime(observedAt);
         const path = this.#path(key, true);
-        return serial(path, async () => {
+        return serial(this.#path(key, false), async () => {
             const state = safeVersion(await this.#load(path, {}));
             if (state.probe)
                 return false;
@@ -229,7 +400,7 @@ export class FileSubscriptionUsageStore {
     async claimLocalProbe(key, observedAt, minIntervalMs) {
         validTime(observedAt);
         const path = this.#path(key, true);
-        return serial(path, async () => {
+        return serial(this.#path(key, false), async () => {
             const state = safeVersion(await this.#load(path, {}));
             if (state.localProbeClaimedAt !== undefined && observedAt >= state.localProbeClaimedAt &&
                 observedAt - state.localProbeClaimedAt < minIntervalMs)
@@ -259,15 +430,77 @@ export class FileSubscriptionUsageStore {
     async finishProbe(key, observation) {
         validTime(observation.observedAt);
         const path = this.#path(key, true);
-        await serial(path, async () => {
+        await serial(this.#path(key, false), async () => {
             const state = safeVersion(await this.#load(path, {}));
             // Network completion order must not discard a newer stored snapshot.
             const mergeAt = Math.max(observation.observedAt, state.usage?.observedAt ?? 0, state.passive?.observedAt ?? 0);
             // Retain Fable observation clocks even when the latest report omits its meter.
             const previous = state.usage ?? usageStateForSelection({ ...state, reactive: [] }, mergeAt).usage;
             state.probe = safeProbe(observation);
-            state.usage = mergePersistedUsageObservations(previous, state.probe.usage, mergeAt);
+            await this.#mergeUsage(key, state, previous, state.probe.usage, mergeAt);
             await this.#save(path, state);
         });
     }
+    async beginVerification(key, model, observedAt) {
+        validTime(observedAt);
+        return serial(this.#path(key, false), async () => {
+            const stored = await this.read(key);
+            const state = usageStateForSelection(stored, observedAt);
+            const selected = selectSubscriptionAccount({ pool: { kind: 'ready', accounts: [key] }, states: { [key.accountId]: state }, model, now: observedAt });
+            if (selected.kind !== 'selected')
+                return undefined;
+            const windows = verificationWindows(key, state, model, observedAt);
+            if (!windows.length)
+                return [];
+            if (!await this.#claimVerification(key, windows, observedAt))
+                return undefined;
+            const matches = (w) => windows.some(v => v.window === w.window && v.scope === w.scope && v.observedAt === (w.observedAt ?? stored.usage?.observedAt ?? state.usage?.observedAt));
+            const version = safeVersion(await this.#load(this.#path(key, true), {}));
+            version.usage ??= state.usage;
+            if (version.usage)
+                version.usage = { ...version.usage, windows: version.usage.windows.map(w => matches(w) ? { ...w, lastVerificationAttemptAt: observedAt } : w) };
+            const reactive = stored.reactive.map(r => matches(reactiveUsageWindow(r)) ? { ...r, lastVerificationAttemptAt: observedAt } : r);
+            await this.#save(this.#path(key, true), version);
+            await this.#save(this.#path(key, false), { reactive });
+            for (const w of windows)
+                this.#log(`verification attempt started window=${w.window}/${w.scope} count=${w.rejectionCount ?? 1} attemptAt=${new Date(observedAt).toISOString()}`);
+            return windows;
+        });
+    }
+    async completeVerification(key, attemptAt, observedAt) {
+        validTime(attemptAt);
+        validTime(observedAt);
+        await serial(this.#path(key, false), async () => {
+            const stored = await this.read(key);
+            const cleared = [];
+            const canClear = (w) => w.status === 'rejected' && w.lastVerificationAttemptAt === attemptAt &&
+                (w.observedAt ?? stored.usage?.observedAt ?? observedAt) <= attemptAt && attemptAt <= observedAt;
+            const version = safeVersion(await this.#load(this.#path(key, true), {}));
+            const windows = version.usage?.windows.filter(w => { if (!canClear(w))
+                return true; cleared.push({ ...w, observedAt: w.observedAt ?? version.usage.observedAt }); return false; });
+            if (version.usage && windows)
+                version.usage = { ...version.usage, windows };
+            const reactive = stored.reactive.filter(r => { const w = reactiveUsageWindow(r); if (!canClear(w))
+                return true; cleared.push(w); return false; });
+            // Raw snapshots are also selection inputs; remove the cleared rejection there.
+            const matches = (w, fallback) => cleared.some(c => c.window === w.window && c.scope === w.scope && (w.observedAt ?? fallback) === c.observedAt);
+            if (version.passive && normalizePassiveUsage(version.passive.rateLimitInfo, version.passive.observedAt).windows.some(w => w.status === 'rejected' && matches(w, version.passive.observedAt))) {
+                // The rejected percentage is not a successful measurement. Keeping it
+                // as status-less usage could immediately re-block the cleared account.
+                delete version.passive;
+            }
+            if (version.probe?.usage)
+                version.probe.usage = { ...version.probe.usage, windows: version.probe.usage.windows.filter(w => w.status !== 'rejected' || !matches(w, version.probe.usage.observedAt)) };
+            await this.#save(this.#path(key, true), version);
+            await this.#save(this.#path(key, false), { reactive });
+            const markers = await this.#claimMarkers(key);
+            await Promise.all([...markers.keys()].filter(path => cleared.some(w => {
+                const prefix = join(this.#directory, 'claims', `${encodeURIComponent(key.accountId)}.${w.scope}.${w.window}.`);
+                const epoch = Number(path.slice(prefix.length, -'.claim'.length));
+                return path.startsWith(prefix) && epoch <= verificationEligibleAt(w, w.observedAt ?? observedAt);
+            })).map(path => rm(path, { force: true })));
+            for (const w of cleared)
+                this.#log(`verification cleared rejection window=${w.window}/${w.scope} count=${w.rejectionCount ?? 1}`);
+        });
+    }
 }

package/dist/types.d.ts

@@ -56,6 +56,8 @@ export interface TeamVibeQueueMessage {
         values?: Record<string, string>;
     };
     teamvibe: {
+        /** Workspace/channel IANA timezone, when supplied by message routing. */
+        timeZone?: string;
         workspaceId: string;
         botId: string;
         botToken: string;