@byokit/usage 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.4.0 (2026-10-01)
+
+
+
+- SECURITY: Claude subscription usage may read credentials only from app-managed folders under the passed stateDir, without refresh or credential writes; default logins and folder escapes are refused, tokens stay in one request and never enter output, errors, logs or stored readings.
+- Share the bounded Codex app-server client between identity and subscription usage reads.
+- Apply shared poll health, scoped quota and hard-limit semantics to managed Claude usage, including cancellable host pacing.
+
+## 0.3.0 (2026-10-01)
+
+
+
+- FIX: Subscription hard-limit flags now override positive percentage room, including blocks without quota windows; cached reset times never clear them.
+- FIX: Claude subscription normalized and scoped quota rows now take precedence over legacy aggregates; missing usage remains unknown.
+- Expose observation age and poll outcomes separately; retain last-good figures through failed polls without changing account health.
+- Add cancellable host origin pacing and account-scoped retry policies for rate limits, refresh failures and transient outcomes.
+- Document reset-time units when passing normalized subscription readings to account selection.
+
 ## 0.2.0 (2026-09-30)
 
 

package/README.md

@@ -6,10 +6,10 @@ left, estimates no cost and never rotates an account.
 
 ```ts
 import { usage, roomOf } from '@byokit/usage';
-// Supplied by the host's signed-in account.
+const reader = usage({ stateDir: '/app/state/usage' });
+// Pass the token and account id from your app-owned sign-in store.
 declare const token: string;
 declare const account: { id: string };
-const reader = usage({ stateDir: '/app/state/usage' });
 const source = { provider: 'codex' as const, access: token, accountId: account.id };
 const reading = await reader.read(source);
 const room = roomOf(reading, Date.now());
@@ -27,14 +27,30 @@ Sources:
 - `{ provider: 'codex', bin, home, env? }` retains the explicit local app-server source.
 - `{ provider: 'claude', credentialsFile, configFile?, statuslineFile? }` is a
   read-only adapter for files the app explicitly supplies. It reads `claudeAiOauth`
-  and optionally `oauthAccount.accountUuid`. A valid statusline snapshot younger
-  than five minutes precedes the endpoint. An expired token is never sent.
-- `{ provider: 'claude', accountUuid, read, connected? }` delegates to the app's
-  reader. `read({ nowMs, signal })` returns `{ raw?, code?, retryAfterMs? }` using
-  the same Claude payload dialect. It has a ten-second deadline, with the signal
+  and optionally `oauthAccount.accountUuid`. A statusline snapshot uses its body `fetched_at` (epoch milliseconds or ISO date),
+  never file mtime. Known snapshots younger than five minutes precede the endpoint;
+  undated/future snapshots remain visible with unknown/future age. An expired token is never sent.
+- `{ provider: 'claude', accountUuid, read, origin?, connected? }` delegates to the app's
+  reader. `read({ nowMs, signal })` returns `{ raw?, code?, retryAfterMs?, at?, limited? }` using
+  the same Claude payload dialect. The host supplies the actual observation `at`;
+  omitted means unknown age, including engine-cached figures. `limited: true` can
+  report an authoritative block without fabricating a window. `origin` is the
+  host reader's optional HTTP origin for pacing. It has a ten-second deadline, with the signal
   aborted at expiry. The optional synchronous `connected()` hook controls whether
   last-good readings remain visible; exceptions count as disconnected.
 
+`read(source, { nowMs?, signal? })` returns `{ provider, windows, at?, limited?, poll?, code? }`.
+`at` is source observation time; it is absent when unavailable. `poll` contains
+last attempt time, `outcome` (`ok` or a safe failure code) and optional `retryAt`.
+All timestamps are epoch milliseconds. A failed poll keeps the figures and their
+original observation time. Poll 429 (`rate-limited`), host renewal failure
+(`refresh-failed`) and credential refusals are distinct; usage never changes
+account health or renews credentials.
+
+The managed-folder source is `{ provider: 'claude', folder, headers: { 'anthropic-beta', 'User-Agent' } }`. Paths must be absolute; removed or empty keys mean disconnected. Claude headers are app-passed. The Claude folder must resolve inside the reader's `stateDir` as `<stateDir>/claude/<hex>`, matching managed CLI account folders. Default `.claude` roots, paths outside the root, and symlinked folders or credential files are refused. Use the managed plans root as the usage reader's stateDir; its quota store coexists with the account roster. The default login's usage adapter remains with the host.
+
+Approved exception: the `./cli` entry reads and runs only app-managed per-account folders under `stateDir` and the absolute CLI binaries the app passes; it never touches the person's default login; tokens never leave the device and are never logged. Under the same managed-folder boundary, usage may read `.credentials.json` only for a single Claude subscription usage request. It does not refresh, write, rename or copy credentials; expired or malformed credentials return `expired` or `not-connected`, requiring sign-in again. The token is held in memory only for that request and never enters readings, stored quotas, errors or logs. Folder and credential metadata supply the cache fingerprint without loading a token, and credential changes invalidate the cached account reading.
+
 `read(source, { nowMs? })` returns `{ provider, windows, at, code? }`; `at` and all
 `resetsAt` fields are **epoch milliseconds** in 0.2.0. This changes 0.1.0's seconds
 reset convention. Windows include kind, used percent, optional duration in minutes,
@@ -43,12 +59,33 @@ reset time, limit label and limited flag. Parsers are exported for host integrat
 `zaiWindows`, `copilotWindows`, `grokWindows`, `minimaxWindows`, `geminiWindows`,
 `kimiWindows(raw, nowMs)`.
 
-`roomOf(reading, nowMs)` returns `{ left, span, resetsAt?, at }` using the tightest
-window. Span maps session/week/month and maps rolling/custom to `tightest`. Missing
-windows, readings older than 24 hours, future readings, or disconnected/expired/auth/
-no-plan readings give `{ left: 'unknown', at }`. A temporary rate limit or failed
-update can still show the last-good room and its original timestamp. Auto selection
-belongs to the accounts kit; usage only reports room.
+Windows include kind, optional reported `usedPercent`, duration, reset, limit,
+`limited` and `scope: { model?, surface? }`. Missing usage is unknown, never zero.
+Claude `limits[]` session/weekly-all rows override corresponding legacy aggregates,
+even if incomplete; dynamic weekly-scoped rows retain model and surface. Legacy
+`five_hour`/`seven_day` are fallback for absent aggregate kinds. These are synthetic
+contract fixtures; fresh live provider payload qualification has not been run.
+
+Parsers are exported: `claudeWindows`, `codexWindows` (app-server),
+`codexTokenWindows(raw, nowMs?)`, `codexHardLimit`, `goWindows`, `zaiWindows`,
+`copilotWindows`, `grokWindows`, `minimaxWindows`, `geminiWindows`, `kimiWindows`.
+Codex absolute reset takes precedence; relative seconds require a captured clock.
+Hard flags do not replace the reported percentage or invent an absent window.
+Hosts using exported Codex parsers must carry `codexHardLimit(raw)` into the reading
+as `limited` to represent windowless blocks.
+
+`roomOf(reading, nowMs)` returns `left`, observation `at?`, `ageMs?`, `freshness`
+(`fresh`, `stale`, `future`, `unknown`), `poll?`, and the tightest row's `scope?`.
+Numeric results include `span` and optional reset. Authoritative hard blocks give
+zero eligibility room even without a percentage/window, with `limited: true`;
+a predicted reset never clears a block. Otherwise undated/future/older-than-24h
+readings and disconnected/expired/auth/no-plan readings give unknown room.
+Incomplete windows cannot establish positive room; known exhaustion still stands.
+Scope is conservative across all windows until hosts implement model demand for
+every model/surface a run can use, including subagents and fallbacks.
+Temporary poll failures may retain eligible last-good room and its age; a poll
+failure itself never exhausts or moves an account. Auto's shared input contract is
+`fixtures/conformance/usage-typescript.json` and runtime spec section 13.
 
 `connected(source)` and `account(source)` are synchronous. `account` returns a salted
 fingerprint of a non-secret host id, credential account UUID, token subject, or explicit
@@ -59,34 +96,45 @@ disk store is used. Tokens never become persisted fingerprint inputs.
 
 Good reads have no code. Bad sources throw `UsageError` (`code: 'bad-source'`); other
 failures resolve codes without bodies or secrets. `lastKnown(source, { nowMs? })`
-returns a connected account's last-good reading for up to 24 hours. Reads have a
-60-second floor and concurrent deduplication per provider/account. The default 429
-backoff honors Retry-After with a five-minute minimum. `UsageOptions.now` supplies
+returns a connected account's last-good figures and most recent poll outcome.
+Ordinary dated readings expire after 24 hours; authoritative blocks stay until a
+new successful read replaces them. Undated figures remain available for display
+with unknown room. Reads have a
+60-second floor and concurrent deduplication per provider/account. Default 429
+backoff honors Retry-After with a five-minute minimum. Unknown/transient and
+refresh failures back off exponentially from one minute to one hour; these are
+kit defaults, not universal provider policy. Failure counters are separate by
+outcome and account, cleared by a successful quota poll. `UsageOptions.now` supplies
 the default clock; a per-call clock overrides it. An injected `fetch` wins; otherwise
 global fetch is resolved on each read.
 
 The host may supply public synchronous persistence and backoff hooks:
 
 ```ts
-import { usage, type UsageStore, type BackoffPolicy } from '@byokit/usage';
-declare const appStore: UsageStore;
-declare const appBackoff: BackoffPolicy;
+import { usage, type UsageStore, type BackoffState } from '@byokit/usage';
+// Replace these maps with your app's durable store to retain state across restart.
+const appStore: UsageStore = {
+  get(provider, fingerprint) { return saved.get(`${provider}/${fingerprint}`); },
+  put(provider, fingerprint, reading) { saved.set(`${provider}/${fingerprint}`, reading); },
+};
+const saved = new Map<string, import('@byokit/usage').StoredReading>();
+const appBackoff = new Map<string, BackoffState | number>();
 const reader = usage({
   store: {
     get(provider, fingerprint) { return appStore.get(provider, fingerprint); },
     put(provider, fingerprint, reading) { appStore.put(provider, fingerprint, reading); },
   },
   backoff: {
-    get(provider, fingerprint) { return appBackoff.get(provider, fingerprint); },
-    set(provider, fingerprint, untilMs) { appBackoff.set(provider, fingerprint, untilMs); },
-    delayMs(retryAfterMs) { return Math.max(300_000, retryAfterMs ?? 0); },
+    get(provider, fingerprint) { return appBackoff.get(`${provider}/${fingerprint}`); },
+    set(provider, fingerprint, untilMs, state) { appBackoff.set(`${provider}/${fingerprint}`, state ?? untilMs); },
+    delayMs(retryAfterMs, { outcome, failures }) { return Math.max(300_000, retryAfterMs ?? 0); },
   },
 });
 ```
 
-`UsageStore` holds only `{ at, windows }`; only whitelisted normalized fields cross
+`UsageStore` holds `{ at?, windows, limited?, poll? }`; only whitelisted normalized fields cross
 this boundary. Exceptions from host hooks do not expose data or fail a provider read.
-Internal 429 backoff remains effective if a host backoff hook fails. The 60-second
+Internal backoff remains effective if a host backoff hook fails. The 60-second
 minimum retry interval applies even if a policy selects a shorter delay. By default,
 `stateDir` selects an atomic disk store (0700 directory, 0600 file, 256 KB cap), or
 without `stateDir` an in-memory store is used. `memoryUsageStore()` is exported.
@@ -126,7 +174,7 @@ they are never loaded automatically.
 
 `fileUsageStore(absoluteStateDir)` exposes the same bounded atomic disk store as
 `stateDir`; invalid directory paths throw `UsageError`. Its keys must be 64-character
-hex fingerprints, and it persists only `{ at, windows }` with normalized fields.
+hex fingerprints, and it persists normalized observations, hard blocks and poll metadata.
 `fingerprint(salt)` returns `(provider, nonSecretIdentity) => string`; use the same
 salt as the reader and never supply a token as the identity.
 `memoryBackoffPolicy()` supplies shared per-provider/account rests, keeps the later
@@ -136,6 +184,23 @@ past dates clamp to zero), and `backoffDelayMs(retryAfterMs)` to apply the defau
 five-minute minimum. These helpers also support an app-owned Claude `read` hook
 without duplicating fingerprint, persistence or retry logic.
 
+`BackoffPolicy.set(provider, fingerprint, untilMs, state?)` receives a normalized
+`state` with `{ untilMs, at, outcome, failures }` on a retryable failure, and zero
+eligibility time without state after success. Persist and return that state from
+`get` to preserve outcome and retry eligibility across restart. Legacy numeric
+`get` values still work; their reason is unavailable when no stored poll supplies it.
+`delayMs(retryAfterMs, { outcome, failures })` chooses host policy; a valid server
+Retry-After is always a lower bound, alongside the existing one-minute floor.
+
+`UsageOptions.pace({ provider, account, origin, signal })` is an optional async host
+hook before each HTTP usage request (including provider discovery/fallback reads).
+The host can share an origin-keyed queue across reader instances. Distinct origins
+are independent; the kit adds no global queue or fixed origin spacing. Account is
+a fingerprint, never a token. Host Claude readers opt in with `source.origin`.
+The hook shares the request deadline and can be cancelled by `ReadOptions.signal`;
+no request is sent when pacing fails or is cancelled. In-flight duplicate callers
+share the first caller's operation/signal. There is no polling timer or inference ping.
+
 Isolation: there is no home/path discovery or environment read. Only absolute files
 and the Codex binary explicitly supplied by the app are opened/run. Credential files
 are bounded regular files, with final symlinks rejected. The spawn uses argv and an
@@ -143,7 +208,9 @@ environment built from the host's explicit `env` plus `CODEX_HOME=home`; pass PA
 and HOME explicitly when needed. No tokens in logs, errors, readings or public hooks;
 no credential write-back, telemetry, automatic refresh or reset-credit spend.
 
-Built-in requests send `User-Agent: byokit/usage/0.2.0`, never another app's identity.
+Built-in requests send `User-Agent: byokit/usage/0.3.0`, never another app's identity.
+
+Token and explicit-file sources send `User-Agent: byokit/usage/0.2.0`, never another app's identity.
 A refusal returns a code; with no last-good quota, room is unknown. Fixed endpoints
 are Anthropic `api/oauth/usage`, ChatGPT `backend-api/wham/usage`, GitHub
 `copilot_internal/user`, Grok `v1/billing` (weekly credits then monthly when needed),
@@ -210,3 +277,13 @@ calls with unknown total counts, member/day/week results expose `unknownCalls`,
 `tokens` is the known subtotal, and week `remaining` is omitted. Cap and price
 policy remain the host's. All times, durations and quota reset timestamps are
 milliseconds. There is no transport, credential discovery or automatic rotation.
+
+When passing normalized windows to `@byokit/accounts`' structural helper, use
+`roomOf(reading.windows, reading.at, 'milliseconds')`. Its two-argument form is for
+legacy reset seconds; normalized usage windows in 0.2.0+ already use milliseconds.
+Alternatively, this package's `roomOf(reading, nowMs)` returns a structural `Room`
+that the accounts chooser accepts directly. Preserve the original measurement time.
+
+`identity(codexSource)` shares the app-server transport, calls `account/read` with a 15-second deadline, never opens a credential file, and returns only `{signedIn,email?,plan?}`. Managed-folder HTTP usage carries only the app-passed headers plus Bearer authorization and JSON accept; it uses the same bounded HTTP transport.
+
+Managed-folder Claude usage uses the shared poll-health and normalized quota pipeline, including scoped hard blocks, unknown usage, last-good observation times, account retry policies and cancellable host origin pacing.

package/dist/claude.d.ts

@@ -0,0 +1,12 @@
+import { providerHttp, type Answer } from './providers.ts';
+import type { Source } from './types.ts';
+type ClaudeSource = Extract<Source, {
+    folder: string;
+}>;
+/** No ambient HOME discovery. Both the lexical and real folder must be managed by this root. */
+export declare function managedClaudeFolder(folder: string, stateDir: string): boolean;
+/** Metadata only, so account/cache probes never load a token. */
+export declare function claudeCredential(folder: string): import("fs").Stats | undefined;
+/** The credential is held only for this request; no refresh, writes or recovery sidecars. */
+export declare function claudeUsage(source: ClaudeSource, fetcher: typeof fetch, nowMs: number, pacing?: Parameters<typeof providerHttp>[5]): Promise<Answer>;
+export {};

package/dist/claude.js

@@ -0,0 +1,47 @@
+import { lstatSync, realpathSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { readJson } from "./store.js";
+import { record } from "./windows.js";
+import { providerHttp } from "./providers.js";
+/** No ambient HOME discovery. Both the lexical and real folder must be managed by this root. */
+export function managedClaudeFolder(folder, stateDir) {
+    const root = resolve(stateDir);
+    const candidate = resolve(folder);
+    if (root.split(sep).some((part) => ['.claude', '.codex', '.pi'].includes(part)))
+        return false;
+    const parent = join(root, 'claude');
+    if (!candidate.startsWith(parent + sep) || !/^[a-f0-9]+$/.test(candidate.slice(parent.length + 1)))
+        return false;
+    try {
+        if (![root, parent, candidate].every((path) => { const s = lstatSync(path); return s.isDirectory() && !s.isSymbolicLink(); }))
+            return false;
+        const realRoot = realpathSync(root);
+        if (realRoot.split(sep).some((part) => ['.claude', '.codex', '.pi'].includes(part)))
+            return false;
+        const realFolder = realpathSync(candidate);
+        return realFolder.startsWith(join(realRoot, 'claude') + sep);
+    }
+    catch {
+        return false;
+    }
+}
+/** Metadata only, so account/cache probes never load a token. */
+export function claudeCredential(folder) {
+    try {
+        const stat = lstatSync(join(folder, '.credentials.json'));
+        return stat.isFile() && !stat.isSymbolicLink() && stat.size <= 64 * 1024 ? stat : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The credential is held only for this request; no refresh, writes or recovery sidecars. */
+export async function claudeUsage(source, fetcher, nowMs, pacing) {
+    const raw = readJson(join(source.folder, '.credentials.json'), 64 * 1024);
+    const oauth = record(raw) && record(raw.claudeAiOauth) ? raw.claudeAiOauth : undefined;
+    if (!oauth || typeof oauth.accessToken !== 'string' || !oauth.accessToken.trim() || oauth.accessToken.length > 16384 || /[\x00-\x20\x7f]/.test(oauth.accessToken))
+        return { code: 'not-connected' };
+    if (typeof oauth.expiresAt !== 'number' || !Number.isFinite(oauth.expiresAt) || oauth.expiresAt <= nowMs)
+        return { code: 'expired' };
+    return providerHttp('https://api.anthropic.com/api/oauth/usage', oauth.accessToken, fetcher, nowMs, { headers: { 'anthropic-beta': source.headers['anthropic-beta'], 'User-Agent': source.headers['User-Agent'] } }, pacing);
+}

package/dist/identity.d.ts

@@ -0,0 +1,11 @@
+import type { Source } from './types.ts';
+export type Identity = {
+    signedIn: boolean;
+    email?: string;
+    plan?: string;
+};
+/** Explicit identity fields only: never walk arbitrary token-bearing objects. */
+export declare function publicIdentity(raw: unknown, signedIn: boolean): Identity;
+export declare function codexIdentity(source: Extract<Source, {
+    bin: string;
+}>): Promise<Identity>;

package/dist/identity.js

@@ -0,0 +1,16 @@
+import { codexRequest } from "./providers.js";
+import { record } from "./windows.js";
+/** Explicit identity fields only: never walk arbitrary token-bearing objects. */
+export function publicIdentity(raw, signedIn) {
+    if (!signedIn || !record(raw))
+        return { signedIn: false };
+    const short = (value) => typeof value === 'string' && value.length > 0 && value.length <= 320 && !/[\x00-\x1f\x7f]/.test(value);
+    const email = short(raw.email) && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(raw.email) ? raw.email : undefined;
+    const plan = [raw.planType, raw.subscriptionType, raw.plan, raw.tier, raw.planName].find((value) => short(value) && /^[a-zA-Z][a-zA-Z0-9 _+-]{0,63}$/.test(value));
+    return { signedIn: true, ...(email === undefined ? {} : { email }), ...(typeof plan === 'string' ? { plan } : {}) };
+}
+export async function codexIdentity(source) {
+    const answer = await codexRequest(source, 'account/read');
+    const account = record(answer.raw) ? answer.raw.account : undefined;
+    return publicIdentity(account, record(account));
+}

package/dist/index.d.ts

@@ -1,12 +1,18 @@
-import { type Usage, type UsageOptions } from './types.ts';
+import { type Source, type Usage, type UsageOptions } from './types.ts';
+import { type Identity } from './identity.ts';
 export * from './types.ts';
+export type { Identity } from './identity.ts';
+/** Identity runs only the named binary, never opens a credential file. */
+export declare function identity(source: Extract<Source, {
+    bin: string;
+}>): Promise<Identity>;
 export { callLedger, normalizeTokens, priceCall, type CallLedger, type CallInput, type CallRecord, type CallQuery, type NormalizedTokens, type ModelPrice, type PriceTable, type CallCost } from './calls.ts';
 export { tokenLedger, memoryTokenLedgerStore, TokenLedgerError, type TokenLedger, type TokenLedgerStore, type TokenLedgerOptions, type TokenEntry, type TokenQuery } from './ledger.ts';
 export { roomOf } from './room.ts';
 export { fingerprint, store as fileUsageStore, memoryUsageStore } from './store.ts';
 export { retryAfterMs, backoffDelayMs, memoryBackoffPolicy } from './backoff.ts';
 export { claudeWindows, codexWindows, goWindows, zaiWindows, type CodexRateLimitResult } from './windows.ts';
-export { codexTokenWindows, copilotWindows, grokWindows, minimaxWindows, geminiWindows, kimiWindows } from './quota.ts';
+export { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimaxWindows, geminiWindows, kimiWindows } from './quota.ts';
 export { WORDS, words, usageWords, type WordKey } from './words.ts';
 /** One reader owns per-account backoff and concurrent-read deduplication. */
 export declare function usage(options: UsageOptions): Usage;

package/dist/index.js

@@ -1,27 +1,41 @@
-import { backoffDelayMs } from "./backoff.js";
 import { accessSync, constants, statSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { isAbsolute, join } from 'node:path';
 import { claudeAuth, claudeUsage, codexUsage, customClaude, providerGet } from "./providers.js";
-import { fingerprint, readJson, store, memoryUsageStore, safeWindows } from "./store.js";
+import { fingerprint, readJson, store, memoryUsageStore, safeWindows, safePoll } from "./store.js";
 import { claudeWindows, codexWindows, goWindows, record, zaiWindows } from "./windows.js";
-import { codexTokenWindows, copilotWindows, grokWindows, minimaxWindows, geminiWindows, kimiWindows } from "./quota.js";
+import { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimaxWindows, geminiWindows, kimiWindows } from "./quota.js";
 import { UsageError } from "./types.js";
+import { codexIdentity } from "./identity.js";
+import { claudeUsage as managedClaudeUsage, claudeCredential, managedClaudeFolder } from "./claude.js";
 export * from "./types.js";
+/** Identity runs only the named binary, never opens a credential file. */
+export async function identity(source) {
+    if (!record(source) || !('bin' in source) || 'folder' in source || 'credentialsFile' in source || 'read' in source)
+        throw new UsageError();
+    validate(source);
+    return codexIdentity(source);
+}
 export { callLedger, normalizeTokens, priceCall } from "./calls.js";
 export { tokenLedger, memoryTokenLedgerStore, TokenLedgerError } from "./ledger.js";
 export { roomOf } from "./room.js";
 export { fingerprint, store as fileUsageStore, memoryUsageStore } from "./store.js";
 export { retryAfterMs, backoffDelayMs, memoryBackoffPolicy } from "./backoff.js";
 export { claudeWindows, codexWindows, goWindows, zaiWindows } from "./windows.js";
-export { codexTokenWindows, copilotWindows, grokWindows, minimaxWindows, geminiWindows, kimiWindows } from "./quota.js";
+export { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimaxWindows, geminiWindows, kimiWindows } from "./quota.js";
 export { WORDS, words, usageWords } from "./words.js";
 const providers = ['claude', 'codex', 'opencode', 'zai', 'copilot', 'grok', 'minimax', 'gemini', 'kimi'];
 const validText = (v) => typeof v === 'string' && !v.includes('\0') && !/[\r\n]/.test(v) && v.length <= 16384;
-function validate(source) {
+function validate(source, stateDir) {
     if (!record(source) || !providers.includes(source.provider))
         throw new UsageError();
-    if ('credentialsFile' in source) {
+    if ('folder' in source) {
+        if (source.provider !== 'claude' || !validText(source.folder) || !isAbsolute(source.folder) || !stateDir || !managedClaudeFolder(source.folder, stateDir))
+            throw new UsageError();
+        if (!record(source.headers) || !['anthropic-beta', 'User-Agent'].every((key) => validText(source.headers[key]) && source.headers[key].length <= 1024))
+            throw new UsageError();
+    }
+    else if ('credentialsFile' in source) {
         if (source.provider !== 'claude' || ![source.credentialsFile, ...[source.configFile, source.statuslineFile].filter((v) => v !== undefined)].every((v) => validText(v) && isAbsolute(v)))
             throw new UsageError();
     }
@@ -44,6 +58,16 @@ function validate(source) {
         if ('access' in source && source.provider === 'codex' && (!validText(source.accountId) || !source.accountId))
             throw new UsageError();
     }
+    if ('origin' in source && source.origin !== undefined) {
+        try {
+            const url = new URL(source.origin);
+            if (!['https:', 'http:'].includes(url.protocol) || url.origin !== source.origin)
+                throw new Error();
+        }
+        catch {
+            throw new UsageError();
+        }
+    }
     const fields = source;
     for (const field of ['accountId', 'accountUuid', 'project'])
         if (fields[field] !== undefined && (!validText(fields[field]) || !fields[field]))
@@ -72,9 +96,12 @@ export function usage(options) {
     const backoffs = new Map();
     const inFlight = new Map();
     const attempts = new Map();
+    const failures = new Map();
     const now = (opts) => opts?.nowMs ?? (options.now ?? Date.now)();
     function connected(source) {
-        validate(source);
+        validate(source, options.stateDir);
+        if ('folder' in source)
+            return claudeCredential(source.folder) !== undefined;
         if ('credentialsFile' in source)
             return claudeAuth(source) !== undefined;
         if ('read' in source) {
@@ -97,9 +124,13 @@ export function usage(options) {
         return ('access' in source ? source.access : source.key).trim() !== '';
     }
     function account(source) {
-        validate(source);
+        validate(source, options.stateDir);
         let id;
-        if ('credentialsFile' in source)
+        if ('folder' in source) {
+            const stat = claudeCredential(source.folder);
+            id = stat ? `${source.folder}\0${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}` : undefined;
+        }
+        else if ('credentialsFile' in source)
             id = claudeAuth(source)?.account;
         else if ('read' in source)
             id = source.accountUuid;
@@ -123,7 +154,7 @@ export function usage(options) {
     function windows(source, raw, clock) {
         switch (source.provider) {
             case 'claude': return claudeWindows(raw);
-            case 'codex': return 'bin' in source ? codexWindows(raw) : codexTokenWindows(raw);
+            case 'codex': return 'bin' in source ? codexWindows(raw) : codexTokenWindows(raw, clock);
             case 'opencode': return goWindows(record(raw) ? raw.usage : undefined);
             case 'zai': return zaiWindows(record(raw) && record(raw.data) ? raw.data.limits : undefined);
             case 'copilot': return copilotWindows(raw);
@@ -140,76 +171,121 @@ export function usage(options) {
         const clock = now(opts);
         try {
             const stored = (id.stable ? disk : transient).get(source.provider, id.key);
-            if (!stored || !Number.isFinite(stored.at) || clock < stored.at || clock - stored.at > 86_400_000)
+            if (!stored)
+                return undefined;
+            if (!stored.limited && !stored.windows.some((w) => w.limited) && stored.at !== undefined && (clock < stored.at || clock - stored.at > 86_400_000))
                 return undefined;
             const rows = safeWindows(source.provider, stored.windows);
-            return rows.length ? { provider: source.provider, windows: rows, at: stored.at } : undefined;
+            const poll = attempts.get(`${source.provider}\0${id.key}`) ?? safePoll(stored.poll);
+            return rows.length || stored.limited ? { provider: source.provider, windows: rows, ...(stored.at !== undefined ? { at: stored.at } : {}),
+                ...(stored.limited ? { limited: true } : {}), ...(poll ? { poll, ...(poll.outcome !== 'ok' ? { code: poll.outcome } : {}) } : {}) } : undefined;
         }
         catch {
             return undefined;
         }
     }
     async function read(source, opts) {
-        validate(source);
+        validate(source, options.stateDir);
         const clock = now(opts);
-        const empty = (code) => ({ provider: source.provider, windows: [], at: clock, code });
+        const empty = (code) => ({ provider: source.provider, windows: [], code, poll: { at: clock, outcome: code ?? 'unavailable' } });
         if (!connected(source))
             return empty('not-connected');
         const id = identity(source);
         const key = `${source.provider}\0${id.key}`;
         const previous = lastKnown(source, { nowMs: clock });
-        if (previous && clock - previous.at < 60_000)
+        if (previous && !previous.code && previous.at !== undefined && clock >= previous.at && clock - previous.at < 60_000)
             return previous;
         let until = backoffs.get(key) ?? 0;
         try {
-            if (id.stable)
-                until = Math.max(until, options.backoff?.get(source.provider, id.key) ?? 0);
+            const saved = id.stable ? options.backoff?.get(source.provider, id.key) : undefined;
+            if (typeof saved === 'number' && Number.isFinite(saved))
+                until = Math.max(until, saved);
+            else if (saved && typeof saved !== 'number' && Number.isFinite(saved.untilMs) && Number.isFinite(saved.at) && ['rate-limited', 'refresh-failed', 'unavailable', 'incomplete'].includes(saved.outcome)) {
+                until = Math.max(until, saved.untilMs);
+                if (!attempts.has(key))
+                    attempts.set(key, { at: saved.at, outcome: saved.outcome, retryAt: saved.untilMs });
+                if (!failures.has(`${key}\0${saved.outcome}`) && Number.isSafeInteger(saved.failures) && saved.failures > 0)
+                    failures.set(`${key}\0${saved.outcome}`, saved.failures);
+            }
         }
         catch { /* keep internal backoff */ }
-        if (until > clock)
-            return previous ? { ...previous, code: 'rate-limited' } : empty('rate-limited');
+        if (until > clock) {
+            const poll = attempts.get(key) ?? previous?.poll ?? { at: clock, outcome: 'unavailable', retryAt: until };
+            return { ...(previous ?? empty(poll.outcome === 'ok' ? 'unavailable' : poll.outcome)), code: poll.outcome === 'ok' ? undefined : poll.outcome, poll };
+        }
         const pending = inFlight.get(key);
         if (pending)
             return pending;
-        const attempt = attempts.get(key);
+        const attempt = attempts.get(key) ?? previous?.poll;
         if (attempt && clock >= attempt.at && clock - attempt.at < 60_000)
-            return previous ? { ...previous, code: attempt.code } : empty(attempt.code ?? 'unavailable');
+            return previous ? { ...previous, code: attempt.outcome === 'ok' ? undefined : attempt.outcome, poll: attempt } : empty(attempt.outcome === 'ok' ? 'unavailable' : attempt.outcome);
         const task = (async () => {
             let answer;
+            const pacing = { hook: options.pace, provider: source.provider, account: id.key, signal: opts?.signal };
             try {
-                answer = 'read' in source ? await customClaude(source, clock) : 'credentialsFile' in source ? await claudeUsage(source, options.fetch ?? globalThis.fetch, clock)
-                    : 'bin' in source ? await codexUsage(source) : await providerGet(source, options.fetch ?? globalThis.fetch, clock);
+                answer = 'folder' in source ? await managedClaudeUsage(source, options.fetch ?? globalThis.fetch, clock, pacing) : 'read' in source ? await customClaude(source, clock, pacing) : 'credentialsFile' in source ? await claudeUsage(source, options.fetch ?? globalThis.fetch, clock, pacing)
+                    : 'bin' in source ? await codexUsage(source) : await providerGet(source, options.fetch ?? globalThis.fetch, clock, pacing);
             }
             catch {
                 answer = { code: 'unavailable' };
             }
-            if (answer.code === 'rate-limited') {
-                let delay = backoffDelayMs(answer.retryAfterMs);
-                try {
-                    const selected = options.backoff?.delayMs?.(answer.retryAfterMs);
-                    if (selected !== undefined && Number.isFinite(selected) && selected >= 0)
-                        delay = selected;
+            const rows = safeWindows(source.provider, windows(source, answer.raw, clock));
+            const limited = !answer.code && (answer.limited === true || source.provider === 'codex' && codexHardLimit(answer.raw));
+            if (!answer.code && !rows.length && !limited)
+                answer = { code: 'incomplete' };
+            const poll = { at: clock, outcome: answer.code ?? 'ok' };
+            if (answer.code) {
+                const failureKey = `${key}\0${answer.code}`;
+                const count = (failures.get(failureKey) ?? 0) + 1;
+                failures.set(failureKey, count);
+                if (['rate-limited', 'refresh-failed', 'unavailable', 'incomplete'].includes(answer.code)) {
+                    const retry = Number.isFinite(answer.retryAfterMs) && answer.retryAfterMs >= 0 ? answer.retryAfterMs : undefined;
+                    let delay = answer.code === 'rate-limited' ? 300_000 : Math.min(3_600_000, 60_000 * 2 ** Math.min(count - 1, 6));
+                    try {
+                        const selected = options.backoff?.delayMs?.(retry, { outcome: answer.code, failures: count });
+                        if (selected !== undefined && Number.isFinite(selected) && selected >= 0)
+                            delay = selected;
+                    }
+                    catch { /* internal policy stands */ }
+                    delay = Math.max(60_000, delay, retry ?? 0);
+                    poll.retryAt = clock + delay;
+                    backoffs.set(key, poll.retryAt);
+                    try {
+                        if (id.stable)
+                            options.backoff?.set(source.provider, id.key, poll.retryAt, { untilMs: poll.retryAt, at: clock, outcome: answer.code, failures: count });
+                    }
+                    catch { /* internal backoff stands */ }
                 }
-                catch { /* default */ }
-                backoffs.set(key, clock + delay);
+            }
+            else {
+                for (const outcome of ['rate-limited', 'refresh-failed', 'unavailable', 'incomplete'])
+                    failures.delete(`${key}\0${outcome}`);
+                backoffs.delete(key);
                 try {
                     if (id.stable)
-                        options.backoff?.set(source.provider, id.key, clock + delay);
+                        options.backoff?.set(source.provider, id.key, 0);
                 }
-                catch { /* internal backoff stands */ }
+                catch { /* expired host policy remains bounded */ }
             }
-            const rows = safeWindows(source.provider, windows(source, answer.raw, clock));
-            if (!answer.code && !rows.length)
-                answer = { code: 'incomplete' };
-            attempts.set(key, { at: clock, code: answer.code });
-            if (rows.length && !answer.code) {
+            attempts.set(key, poll);
+            if ((rows.length || limited) && !answer.code) {
+                // Explicit host/snapshot time is authoritative, including unknown or future time.
+                const observed = 'at' in answer ? answer.at : clock;
+                const at = typeof observed === 'number' && Number.isFinite(observed) ? observed : undefined;
+                const reading = { provider: source.provider, windows: rows, ...(at !== undefined ? { at } : {}), ...(limited ? { limited: true } : {}), poll };
                 try {
-                    (id.stable ? disk : transient).put(source.provider, id.key, { at: clock, windows: rows });
+                    (id.stable ? disk : transient).put(source.provider, id.key, { at: reading.at, windows: rows, ...(limited ? { limited: true } : {}), poll });
                 }
                 catch { /* reads survive a store failure */ }
-                return { provider: source.provider, windows: rows, at: clock };
+                return reading;
+            }
+            if (previous) {
+                try {
+                    (id.stable ? disk : transient).put(source.provider, id.key, { at: previous.at, windows: previous.windows, ...(previous.limited ? { limited: true } : {}), poll });
+                }
+                catch { /* last-good remains in memory */ }
             }
-            return previous ? { ...previous, code: answer.code } : empty(answer.code ?? 'unavailable');
+            return { ...(previous ?? empty(answer.code ?? 'unavailable')), code: answer.code, poll };
         })();
         inFlight.set(key, task);
         try {

package/dist/providers.d.ts

@@ -1,22 +1,41 @@
-import type { Code, Source } from './types.ts';
-export interface Answer {
-    raw?: unknown;
-    code?: Code;
-    retryAfterMs?: number;
-}
+import type { Source, SourceAnswer, PacingHook } from './types.ts';
+export type Answer = SourceAnswer;
 type TokenSource = Extract<Source, {
     access: string;
 } | {
     key: string;
 }>;
-export declare function providerGet(source: TokenSource, fetcher: typeof fetch, nowMs: number): Promise<Answer>;
+/** One bounded request; credentials and response bodies never become errors. */
+export declare function providerHttp(url: string, key: string, fetcher: typeof fetch, nowMs: number, extra?: {
+    headers?: Record<string, string>;
+    body?: unknown;
+}, pacing?: {
+    hook?: PacingHook;
+    provider: Source['provider'];
+    account: string;
+    signal?: AbortSignal;
+}): Promise<Answer>;
+export declare function providerGet(source: TokenSource, fetcher: typeof fetch, nowMs: number, pacing?: {
+    hook?: PacingHook;
+    provider: Source['provider'];
+    account: string;
+    signal?: AbortSignal;
+}): Promise<Answer>;
 /** A host hook gets the same deadline and failure envelope as built-in sources. */
 export declare function customClaude(source: Extract<Source, {
     read: unknown;
-}>, nowMs: number): Promise<Answer>;
+}>, nowMs: number, pacing?: {
+    hook?: PacingHook;
+    account: string;
+    signal?: AbortSignal;
+}): Promise<Answer>;
 export declare function codexUsage(source: Extract<Source, {
     bin: string;
 }>): Promise<Answer>;
+/** The single bounded app-server transport used for identity and usage. */
+export declare function codexRequest(source: Extract<Source, {
+    bin: string;
+}>, method: 'account/read' | 'account/rateLimits/read', timeoutMs?: number): Promise<Answer>;
 /** Re-read the tool's credentials so its own renewal is picked up; never renew or write them. */
 export declare function claudeAuth(source: Extract<Source, {
     credentialsFile: string;
@@ -27,5 +46,10 @@ export declare function claudeAuth(source: Extract<Source, {
 } | undefined;
 export declare function claudeUsage(source: Extract<Source, {
     credentialsFile: string;
-}>, fetcher: typeof fetch, nowMs: number): Promise<Answer>;
+}>, fetcher: typeof fetch, nowMs: number, pacing?: {
+    hook?: PacingHook;
+    provider: Source['provider'];
+    account: string;
+    signal?: AbortSignal;
+}): Promise<Answer>;
 export {};

package/dist/providers.js

@@ -5,10 +5,23 @@ import { claudeWindows, record } from "./windows.js";
 import { grokWindows } from "./quota.js";
 const USER_AGENT = 'byokit/usage/0.2.0';
 /** One bounded request; credentials and response bodies never become errors. */
-async function request(url, key, fetcher, nowMs, extra = {}) {
+export async function providerHttp(url, key, fetcher, nowMs, extra = {}, pacing) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 10_000);
+    const abort = () => controller.abort();
+    pacing?.signal?.addEventListener('abort', abort, { once: true });
+    if (pacing?.signal?.aborted)
+        controller.abort();
+    const timer = setTimeout(abort, 10_000);
     try {
+        if (pacing?.hook)
+            await Promise.race([pacing.hook({ provider: pacing.provider, account: pacing.account, origin: new URL(url).origin, signal: controller.signal }), new Promise((_, reject) => {
+                    if (controller.signal.aborted)
+                        reject(new Error());
+                    else
+                        controller.signal.addEventListener('abort', () => reject(new Error()), { once: true });
+                })]);
+        if (controller.signal.aborted)
+            return { code: 'unavailable' };
         const response = await fetcher(url, { headers: { accept: 'application/json', authorization: `Bearer ${key}`, 'User-Agent': USER_AGENT,
                 ...(extra.body !== undefined ? { 'content-type': 'application/json' } : {}), ...extra.headers },
             ...(extra.body !== undefined ? { method: 'POST', body: JSON.stringify(extra.body) } : {}), redirect: 'error', signal: controller.signal });
@@ -51,11 +64,12 @@ async function request(url, key, fetcher, nowMs, extra = {}) {
     }
     finally {
         clearTimeout(timer);
+        pacing?.signal?.removeEventListener('abort', abort);
     }
 }
-export async function providerGet(source, fetcher, nowMs) {
+export async function providerGet(source, fetcher, nowMs, pacing) {
     const key = 'access' in source ? source.access : source.key;
-    const get = (url, extra) => request(url, key, fetcher, nowMs, extra);
+    const get = (url, extra) => providerHttp(url, key, fetcher, nowMs, extra, pacing);
     switch (source.provider) {
         case 'claude': return get('https://api.anthropic.com/api/oauth/usage', { headers: { 'anthropic-beta': 'oauth-2025-04-20' } });
         case 'codex': return get('https://chatgpt.com/backend-api/wham/usage', { headers: { 'ChatGPT-Account-Id': source.accountId } });
@@ -91,12 +105,28 @@ export async function providerGet(source, fetcher, nowMs) {
     }
 }
 /** A host hook gets the same deadline and failure envelope as built-in sources. */
-export async function customClaude(source, nowMs) {
+export async function customClaude(source, nowMs, pacing) {
     const controller = new AbortController();
-    let timer;
+    const abort = () => controller.abort();
+    pacing?.signal?.addEventListener('abort', abort, { once: true });
+    if (pacing?.signal?.aborted)
+        controller.abort();
+    const timer = setTimeout(abort, 10_000);
     try {
-        return await Promise.race([source.read({ nowMs, signal: controller.signal }), new Promise((resolve) => {
-                timer = setTimeout(() => { controller.abort(); resolve({ code: 'unavailable' }); }, 10_000);
+        const operation = async () => {
+            if (source.origin && pacing?.hook)
+                await pacing.hook({ provider: source.provider, account: pacing.account, origin: source.origin, signal: controller.signal });
+            if (controller.signal.aborted)
+                return { code: 'unavailable' };
+            const answer = await source.read({ nowMs, signal: controller.signal });
+            // Host readers may return cached figures; only the host knows observation time.
+            return { ...answer, at: answer.at };
+        };
+        return await Promise.race([operation(), new Promise((resolve) => {
+                if (controller.signal.aborted)
+                    resolve({ code: 'unavailable' });
+                else
+                    controller.signal.addEventListener('abort', () => resolve({ code: 'unavailable' }), { once: true });
             })]);
     }
     catch {
@@ -104,9 +134,14 @@ export async function customClaude(source, nowMs) {
     }
     finally {
         clearTimeout(timer);
+        pacing?.signal?.removeEventListener('abort', abort);
     }
 }
 export function codexUsage(source) {
+    return codexRequest(source, 'account/rateLimits/read', 20_000);
+}
+/** The single bounded app-server transport used for identity and usage. */
+export function codexRequest(source, method, timeoutMs = 15_000) {
     return new Promise((resolve) => {
         const child = spawn(source.bin, ['app-server'], { env: { ...source.env, CODEX_HOME: source.home }, stdio: ['pipe', 'pipe', 'ignore'] });
         let buffer = '';
@@ -125,7 +160,7 @@ export function codexUsage(source) {
             }
             resolve(answer);
         };
-        const timer = setTimeout(() => finish({ code: 'unavailable' }), 20_000);
+        const timer = setTimeout(() => finish({ code: 'unavailable' }), timeoutMs);
         child.once('error', () => finish({ code: 'unavailable' }));
         child.once('close', () => { clearTimeout(escalation); finish({ code: 'unavailable' }); });
         child.stdin.on('error', () => finish({ code: 'unavailable' }));
@@ -150,7 +185,7 @@ export function codexUsage(source) {
                     if (!record(message))
                         continue;
                     if (message.id === 1)
-                        child.stdin.write(`${JSON.stringify({ id: 2, method: 'account/rateLimits/read', params: {} })}\n`);
+                        child.stdin.write(`${JSON.stringify({ id: 2, method, params: {} })}\n`);
                     if (message.id === 2)
                         finish(record(message.result) ? { raw: message.result } : { code: 'incomplete' });
                 }
@@ -174,14 +209,18 @@ export function claudeAuth(source) {
         return undefined;
     return { token, account: identity, ...(typeof credentials.expiresAt === 'number' && Number.isFinite(credentials.expiresAt) ? { expiresAt: credentials.expiresAt } : {}) };
 }
-export async function claudeUsage(source, fetcher, nowMs) {
+export async function claudeUsage(source, fetcher, nowMs, pacing) {
     const snapshot = source.statuslineFile ? readJsonSnapshot(source.statuslineFile, 64 * 1024) : undefined;
-    if (snapshot && nowMs >= snapshot.modified && nowMs - snapshot.modified < 300_000 && claudeWindows(snapshot.value).length)
-        return { raw: snapshot.value };
+    if (snapshot && record(snapshot.value) && claudeWindows(snapshot.value).length) {
+        const rawTime = snapshot.value.fetched_at;
+        const at = typeof rawTime === 'number' ? rawTime : typeof rawTime === 'string' ? Date.parse(rawTime) : undefined;
+        if (at === undefined || !Number.isFinite(at) || nowMs < at || nowMs - at < 300_000)
+            return { raw: snapshot.value, at };
+    }
     const auth = claudeAuth(source);
     if (!auth)
         return { code: 'not-connected' };
     if (auth.expiresAt !== undefined && auth.expiresAt <= nowMs)
         return { code: 'expired' };
-    return providerGet({ provider: 'claude', access: auth.token }, fetcher, nowMs);
+    return providerGet({ provider: 'claude', access: auth.token }, fetcher, nowMs, pacing);
 }

package/dist/quota.d.ts

@@ -1,5 +1,6 @@
 import type { Window } from './types.ts';
-export declare function codexTokenWindows(raw: unknown): Window[];
+export declare function codexTokenWindows(raw: unknown, nowMs?: number): Window[];
+export declare function codexHardLimit(raw: unknown): boolean;
 export declare function copilotWindows(raw: unknown): Window[];
 export declare function grokWindows(raw: unknown): Window[];
 export declare function minimaxWindows(raw: unknown): Window[];

package/dist/quota.js

@@ -12,18 +12,22 @@ const ratio = (used, limit, remaining) => {
     const left = number(remaining);
     return cap !== undefined && cap > 0 && (consumed !== undefined || left !== undefined) ? 100 * (consumed ?? cap - left) / cap : undefined;
 };
-export function codexTokenWindows(raw) {
+export function codexTokenWindows(raw, nowMs) {
     const source = obj(raw);
     const plan = obj(source.rate_limit);
-    const group = (value, name) => ({ limitName: name,
-        ...Object.fromEntries(['primary', 'secondary'].map((key) => {
+    const group = (value, name) => ({ limitName: name, limitReached: value.limit_reached === true,
+        ...Object.fromEntries(['primary', 'secondary'].filter((key) => record(value[`${key}_window`])).map((key) => {
             const w = obj(value[`${key}_window`]);
-            return [key, { usedPercent: w.used_percent, windowDurationMins: typeof w.limit_window_seconds === 'number' ? w.limit_window_seconds / 60 : undefined, resetsAt: w.reset_at }];
+            return [key, { usedPercent: w.used_percent, windowDurationMins: typeof w.limit_window_seconds === 'number' ? w.limit_window_seconds / 60 : undefined, resetsAt: w.reset_at !== undefined ? w.reset_at : number(w.reset_after_seconds) !== undefined && number(w.reset_after_seconds) >= 0 && nowMs !== undefined ? (nowMs + number(w.reset_after_seconds) * 1000) / 1000 : undefined }];
         })) });
     return codexWindows({ rateLimitsByLimitId: Object.fromEntries([
             ['plan', group(plan, 'Codex')], ...rows(source.additional_rate_limits).map((v, i) => { const extra = obj(v); return [String(i), group(obj(extra.rate_limit), label(extra.limit_name))]; }),
         ]) });
 }
+export function codexHardLimit(raw) {
+    const source = obj(raw);
+    return obj(source.rate_limit).limit_reached === true || obj(source.rateLimits).limitReached === true || Object.values(obj(source.rateLimitsByLimitId)).some((v) => obj(v).limitReached === true) || rows(source.additional_rate_limits).some((v) => obj(obj(v).rate_limit).limit_reached === true);
+}
 export function copilotWindows(raw) {
     const source = obj(raw);
     return Object.entries(obj(source.quota_snapshots)).flatMap(([key, value]) => {

package/dist/room.d.ts

@@ -1,3 +1,3 @@
 import type { Reading, Room } from './types.ts';
-/** Tightest known quota, valid for 24 hours. Refused/authless sources report unknown room. */
+/** Figures retain their observation age; poll failure does not imply exhaustion. */
 export declare function roomOf(reading: Reading, nowMs: number): Room;

package/dist/room.js

@@ -1,11 +1,25 @@
-/** Tightest known quota, valid for 24 hours. Refused/authless sources report unknown room. */
+/** Figures retain their observation age; poll failure does not imply exhaustion. */
 export function roomOf(reading, nowMs) {
-    if (!Number.isFinite(reading.at) || !Number.isFinite(nowMs) || nowMs < reading.at || nowMs - reading.at > 86_400_000 || ['not-connected', 'expired', 'auth', 'no-plan'].includes(reading.code ?? ''))
-        return { left: 'unknown', at: reading.at };
-    const tight = reading.windows.reduce((worst, window) => Number.isFinite(window.usedPercent) && (!worst || window.usedPercent > worst.usedPercent) ? window : worst, undefined);
+    const at = reading.at;
+    const ageMs = at !== undefined && Number.isFinite(at) && Number.isFinite(nowMs) && nowMs >= at ? nowMs - at : undefined;
+    const freshness = at === undefined || !Number.isFinite(at) || !Number.isFinite(nowMs) ? 'unknown' : nowMs < at ? 'future' : ageMs > 86_400_000 ? 'stale' : 'fresh';
+    const meta = { ...(at !== undefined ? { at } : {}), ...(ageMs !== undefined ? { ageMs } : {}), freshness,
+        ...(reading.poll ? { poll: reading.poll } : {}) };
+    const blocked = reading.windows.find((w) => w.limited === true);
+    // A reset prediction never clears an authoritative block, even in an old reading.
+    if (reading.limited || blocked)
+        return { ...meta, left: 0, span: 'tightest', limited: true,
+            ...(blocked?.scope ? { scope: blocked.scope } : {}), ...(blocked?.resetsAt !== undefined ? { resetsAt: blocked.resetsAt } : {}) };
+    if (freshness !== 'fresh' || ['not-connected', 'expired', 'auth', 'no-plan'].includes(reading.code ?? ''))
+        return { ...meta, left: 'unknown' };
+    const tight = reading.windows.reduce((worst, w) => typeof w.usedPercent === 'number' && Number.isFinite(w.usedPercent) && (!worst || w.usedPercent > worst.usedPercent) ? w : worst, undefined);
     if (!tight)
-        return { left: 'unknown', at: reading.at };
+        return { ...meta, left: 'unknown' };
     const span = tight.kind === 'weekly' ? 'week' : tight.kind === 'monthly' ? 'month' : tight.kind === 'session' ? 'session' : 'tightest';
-    return { left: Math.max(0, Math.min(100, 100 - tight.usedPercent)), span, at: reading.at,
+    const left = Math.max(0, Math.min(100, 100 - tight.usedPercent));
+    // Incomplete applicable windows cannot establish available room. Known exhaustion still stands.
+    if (left > 0 && reading.windows.some((w) => w.usedPercent === undefined))
+        return { ...meta, left: 'unknown' };
+    return { ...meta, left, span, ...(tight.scope ? { scope: tight.scope } : {}),
         ...(Number.isFinite(tight.resetsAt) ? { resetsAt: tight.resetsAt } : {}) };
 }

package/dist/store.d.ts

@@ -1,4 +1,4 @@
-import type { Provider, StoredReading, UsageStore, Window } from './types.ts';
+import type { Provider, StoredReading, UsageStore, Window, Poll } from './types.ts';
 export type Stored = StoredReading;
 /** Bounded regular files only; do not follow credential or state symlinks. */
 export declare function readJsonSnapshot(file: string, cap: number): {
@@ -7,6 +7,8 @@ export declare function readJsonSnapshot(file: string, cap: number): {
 } | undefined;
 export declare function readJson(file: string, cap: number): unknown;
 export declare function fingerprint(salt: string): (provider: Provider, value: string) => string;
+/** Poll metadata is distinct from the observation timestamp. */
+export declare function safePoll(raw: unknown): Poll | undefined;
 export declare function store(stateDir: string): UsageStore;
 /** Public stores receive only these quota fields, never raw provider payloads. */
 export declare function safeWindows(provider: Provider, raw: unknown): Window[];

package/dist/store.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID, scryptSync } from 'node:crypto';
 import { chmodSync, closeSync, fstatSync, mkdirSync, openSync, readSync, renameSync, unlinkSync, writeFileSync, constants } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { UsageError } from "./types.js";
-import { record } from "./windows.js";
+import { record, quotaScope } from "./windows.js";
 /** Bounded regular files only; do not follow credential or state symlinks. */
 export function readJsonSnapshot(file, cap) {
     let fd;
@@ -44,6 +44,12 @@ export function fingerprint(salt) {
         return fp;
     };
 }
+/** Poll metadata is distinct from the observation timestamp. */
+export function safePoll(raw) {
+    if (!record(raw) || typeof raw.at !== 'number' || !Number.isFinite(raw.at) || !['ok', 'not-connected', 'expired', 'auth', 'no-plan', 'rate-limited', 'unavailable', 'incomplete', 'refresh-failed'].includes(String(raw.outcome)))
+        return undefined;
+    return { at: raw.at, outcome: raw.outcome, ...(typeof raw.retryAt === 'number' && Number.isFinite(raw.retryAt) ? { retryAt: raw.retryAt } : {}) };
+}
 export function store(stateDir) {
     if (typeof stateDir !== 'string' || !isAbsolute(stateDir) || /[\0\r\n]/.test(stateDir))
         throw new UsageError();
@@ -59,8 +65,8 @@ export function store(stateDir) {
                 continue;
             const readings = Object.create(null);
             for (const [fp, r] of Object.entries(entries)) {
-                if (/^[a-f0-9]{64}$/.test(fp) && record(r) && typeof r.at === 'number' && Number.isFinite(r.at))
-                    readings[fp] = { at: r.at, windows: safeWindows(id, r.windows) };
+                if (/^[a-f0-9]{64}$/.test(fp) && record(r) && (r.at === undefined || typeof r.at === 'number' && Number.isFinite(r.at)))
+                    readings[fp] = { ...(typeof r.at === 'number' ? { at: r.at } : {}), windows: safeWindows(id, r.windows), ...(r.limited === true ? { limited: true } : {}), ...(safePoll(r.poll) ? { poll: safePoll(r.poll) } : {}) };
             }
             plans[id] = readings;
         }
@@ -75,9 +81,9 @@ export function store(stateDir) {
             try {
                 const plans = load();
                 const entries = plans[id] ?? {};
-                if (reading.at < (entries[fp]?.at ?? -Infinity))
+                if (reading.at !== undefined && reading.at < (entries[fp]?.at ?? -Infinity))
                     return;
-                entries[fp] = { at: reading.at, windows: safeWindows(id, reading.windows) };
+                entries[fp] = { at: reading.at, windows: safeWindows(id, reading.windows), ...(reading.limited ? { limited: true } : {}), ...(safePoll(reading.poll) ? { poll: safePoll(reading.poll) } : {}) };
                 plans[id] = entries;
                 const body = JSON.stringify({ plans });
                 if (Buffer.byteLength(body) > 256 * 1024)
@@ -100,9 +106,10 @@ export function store(stateDir) {
 /** Public stores receive only these quota fields, never raw provider payloads. */
 export function safeWindows(provider, raw) {
     return (Array.isArray(raw) ? raw : []).slice(0, 64).flatMap((value) => {
-        if (!record(value) || !['session', 'weekly', 'monthly', 'rolling', 'custom'].includes(String(value.kind)) || typeof value.usedPercent !== 'number' || !Number.isFinite(value.usedPercent))
+        if (!record(value) || !['session', 'weekly', 'monthly', 'rolling', 'custom'].includes(String(value.kind)) || value.usedPercent !== undefined && (typeof value.usedPercent !== 'number' || !Number.isFinite(value.usedPercent)))
             return [];
-        return [{ provider, kind: value.kind, usedPercent: Math.max(0, Math.min(100, value.usedPercent)),
+        return [{ provider, kind: value.kind, ...(typeof value.usedPercent === 'number' ? { usedPercent: Math.max(0, Math.min(100, value.usedPercent)) } : {}),
+                ...(quotaScope(value.scope) ? { scope: quotaScope(value.scope) } : {}),
                 ...(typeof value.minutes === 'number' && Number.isFinite(value.minutes) && value.minutes > 0 ? { minutes: value.minutes } : {}),
                 ...(typeof value.resetsAt === 'number' && Number.isFinite(value.resetsAt) ? { resetsAt: value.resetsAt } : {}),
                 ...(value.limited === true ? { limited: true } : {}),
@@ -111,7 +118,7 @@ export function safeWindows(provider, raw) {
 }
 export function memoryUsageStore() {
     const readings = new Map();
-    return { get: (provider, account) => { const r = readings.get(`${provider}\0${account}`); return r ? { at: r.at, windows: safeWindows(provider, r.windows) } : undefined; },
-        put: (provider, account, reading) => { const key = `${provider}\0${account}`; if (reading.at >= (readings.get(key)?.at ?? -Infinity))
-            readings.set(key, { at: reading.at, windows: safeWindows(provider, reading.windows) }); } };
+    return { get: (provider, account) => { const r = readings.get(`${provider}\0${account}`); return r ? { at: r.at, windows: safeWindows(provider, r.windows), ...(r.limited ? { limited: true } : {}), ...(safePoll(r.poll) ? { poll: safePoll(r.poll) } : {}) } : undefined; },
+        put: (provider, account, reading) => { const key = `${provider}\0${account}`; if (reading.at === undefined || reading.at >= (readings.get(key)?.at ?? -Infinity))
+            readings.set(key, { at: reading.at, windows: safeWindows(provider, reading.windows), ...(reading.limited ? { limited: true } : {}), ...(safePoll(reading.poll) ? { poll: safePoll(reading.poll) } : {}) }); } };
 }

package/dist/types.d.ts

@@ -4,6 +4,13 @@ type Identity = {
     accountId?: string;
 };
 export type Source = {
+    provider: 'claude';
+    folder: string;
+    headers: {
+        'anthropic-beta': string;
+        'User-Agent': string;
+    };
+} | {
     provider: 'codex';
     bin: string;
     home: string;
@@ -20,6 +27,7 @@ export type Source = {
     provider: 'claude';
     accountUuid: string;
     read: ClaudeReader;
+    origin?: string;
     connected?: () => boolean;
 }) | {
     provider: 'claude';
@@ -43,34 +51,55 @@ export type Window = {
     provider: Provider;
     kind: Kind;
     limit?: string;
-    usedPercent: number;
+    usedPercent?: number;
+    scope?: Scope;
     minutes?: number;
     resetsAt?: number;
     limited?: boolean;
 };
-export type Code = 'not-connected' | 'expired' | 'auth' | 'no-plan' | 'rate-limited' | 'unavailable' | 'incomplete';
+export type Scope = {
+    model?: string;
+    surface?: string;
+};
+export type Poll = {
+    at: number;
+    outcome: Code | 'ok';
+    retryAt?: number;
+};
+export type Freshness = 'fresh' | 'stale' | 'future' | 'unknown';
+export type Code = 'not-connected' | 'expired' | 'auth' | 'no-plan' | 'rate-limited' | 'unavailable' | 'incomplete' | 'refresh-failed';
 export type Reading = {
     provider: Provider;
     windows: Window[];
-    at: number;
+    at?: number;
+    limited?: boolean;
+    poll?: Poll;
     code?: Code;
 };
 export type Room = {
+    at?: number;
+    ageMs?: number;
+    freshness: Freshness;
+    poll?: Poll;
+    scope?: Scope;
+    limited?: boolean;
+} & ({
     left: number;
     span: 'session' | 'week' | 'month' | 'tightest';
     resetsAt?: number;
-    at: number;
 } | {
     left: 'unknown';
-    at?: number;
-};
+});
 export type ReadOptions = {
     nowMs?: number;
+    signal?: AbortSignal;
 };
 export type SourceAnswer = {
     raw?: unknown;
     code?: Code;
     retryAfterMs?: number;
+    limited?: boolean;
+    at?: number;
 };
 /** The app owns credential reads/refresh and sends its own requests through this seam. */
 export type ClaudeReader = (options: {
@@ -78,19 +107,36 @@ export type ClaudeReader = (options: {
     signal: AbortSignal;
 }) => Promise<SourceAnswer>;
 export type StoredReading = {
-    at: number;
+    at?: number;
     windows: Window[];
+    limited?: boolean;
+    poll?: Poll;
 };
 export interface UsageStore {
     get(provider: Provider, account: string): StoredReading | undefined;
     put(provider: Provider, account: string, reading: StoredReading): void;
 }
+export type BackoffState = {
+    untilMs: number;
+    at: number;
+    outcome: Code;
+    failures: number;
+};
 export interface BackoffPolicy {
-    get(provider: Provider, account: string): number | undefined;
-    set(provider: Provider, account: string, untilMs: number): void;
-    /** Retry-After duration to wait; default at least five minutes. */
-    delayMs?(retryAfterMs: number | undefined): number;
+    get(provider: Provider, account: string): number | BackoffState | undefined;
+    set(provider: Provider, account: string, untilMs: number, state?: BackoffState): void;
+    /** Retry-After duration to wait; context carries the current outcome and its consecutive failures. */
+    delayMs?(retryAfterMs: number | undefined, context: {
+        outcome: Code;
+        failures: number;
+    }): number;
 }
+export type PacingHook = (request: {
+    provider: Provider;
+    account: string;
+    origin: string;
+    signal: AbortSignal;
+}) => Promise<void>;
 export type UsageOptions = {
     stateDir?: string;
     store?: UsageStore;
@@ -98,6 +144,7 @@ export type UsageOptions = {
     salt?: string;
     fetch?: typeof fetch;
     now?: () => number;
+    pace?: PacingHook;
 };
 export interface Usage {
     read(source: Source, options?: ReadOptions): Promise<Reading>;

package/dist/windows.d.ts

@@ -1,7 +1,9 @@
-import type { Kind, Provider, Window } from './types.ts';
+import type { Kind, Provider, Window, Scope } from './types.ts';
 export declare const record: (v: unknown) => v is Record<string, unknown>;
 export declare function window(provider: Provider, kind: Kind, used: unknown, minutes?: number, resetsAt?: number, limited?: boolean, limit?: string): Window[];
-/** Accepts both the statusline envelope and the provider's usage payload. */
+/** Scope is an allowlisted descriptor, never arbitrary provider data. */
+export declare function quotaScope(raw: unknown): Scope | undefined;
+/** Normalized rows override legacy aggregates of the same kind, even if incomplete. */
 export declare function claudeWindows(raw: unknown): Window[];
 /** Accepts the `usage` member; monthly length is deliberately absent. */
 export declare function goWindows(raw: unknown): Window[];

package/dist/windows.js

@@ -1,25 +1,53 @@
 export const record = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const obj = (v) => record(v) ? v : {};
 export function window(provider, kind, used, minutes, resetsAt, limited = false, limit) {
-    if (typeof used !== 'number' || !Number.isFinite(used))
+    if (used !== undefined && (typeof used !== 'number' || !Number.isFinite(used))) {
+        if (!limited)
+            return [];
+        used = undefined;
+    }
+    if (used === undefined && !limited)
         return [];
-    return [{ provider, kind, usedPercent: Math.max(0, Math.min(100, used)),
+    return [{ provider, kind, ...(typeof used === 'number' ? { usedPercent: Math.max(0, Math.min(100, used)) } : {}),
             ...(minutes !== undefined && Number.isFinite(minutes) && minutes > 0 ? { minutes } : {}),
             ...(Number.isFinite(resetsAt) ? { resetsAt } : {}), ...(limited ? { limited: true } : {}), ...(limit ? { limit } : {}) }];
 }
-/** Accepts both the statusline envelope and the provider's usage payload. */
+/** Scope is an allowlisted descriptor, never arbitrary provider data. */
+export function quotaScope(raw) {
+    const value = obj(raw);
+    const scope = {};
+    for (const key of ['model', 'surface']) {
+        if (typeof value[key] === 'string' && value[key].length > 0 && value[key].length <= 80 && !/[\x00-\x1f]/.test(value[key]))
+            scope[key] = value[key];
+    }
+    return Object.keys(scope).length ? scope : undefined;
+}
+/** Normalized rows override legacy aggregates of the same kind, even if incomplete. */
 export function claudeWindows(raw) {
     const source = obj(obj(raw).rate_limits ?? raw);
-    return ['five_hour', 'seven_day'].flatMap((id) => {
+    const normalized = (Array.isArray(source.limits) ? source.limits : []).filter(record)
+        .filter((row) => ['session', 'weekly_all', 'weekly_scoped'].includes(String(row.kind)));
+    const rows = normalized.flatMap((w) => {
+        const used = typeof w.percent === 'number' && Number.isFinite(w.percent) ? Math.max(0, Math.min(100, w.percent)) : undefined;
+        const reset = typeof w.resets_at === 'number' ? w.resets_at * 1000 : Date.parse(String(w.resets_at));
+        const scope = quotaScope(w.scope);
+        return [{ provider: 'claude', kind: w.kind === 'session' ? 'session' : 'weekly',
+                ...(used !== undefined ? { usedPercent: used } : {}), ...(scope ? { scope } : {}),
+                ...(Number.isFinite(reset) ? { resetsAt: reset } : {}), ...(w.limit_reached === true ? { limited: true } : {}) }];
+    });
+    const legacy = ['five_hour', 'seven_day'].flatMap((id) => {
+        if (normalized.some((w) => w.kind === (id === 'five_hour' ? 'session' : 'weekly_all')))
+            return [];
         const w = obj(source[id]);
         return window('claude', id === 'five_hour' ? 'session' : 'weekly', Number.isFinite(w.utilization) ? w.utilization : w.used_percentage, id === 'five_hour' ? 300 : 10080, typeof w.resets_at === 'number' ? w.resets_at * 1000 : Date.parse(String(w.resets_at)));
     });
+    return [...rows, ...legacy];
 }
 /** Accepts the `usage` member; monthly length is deliberately absent. */
 export function goWindows(raw) {
     return ['rolling', 'weekly', 'monthly'].flatMap((kind) => {
         const w = obj(obj(raw)[kind]);
-        if (typeof w.percent !== 'number' || w.percent < 0 || !['ok', 'rate-limited'].includes(String(w.status)))
+        if (typeof w.percent === 'number' && w.percent < 0 || !['ok', 'rate-limited'].includes(String(w.status)))
             return [];
         return window('opencode', kind, w.percent, kind === 'monthly' ? undefined : kind === 'weekly' ? 10080 : 300, Date.parse(String(w.resetsAt)), w.status === 'rate-limited');
     });
@@ -43,13 +71,15 @@ export function codexWindows(result) {
             return [];
         const name = String(raw.limitName ?? raw.limitId ?? 'Codex').replace(/[^\x20-\x7e]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80) || 'Codex';
         const rows = ['primary', 'secondary'].flatMap((key) => {
+            if (!record(raw[key]))
+                return [];
             const w = obj(raw[key]);
             const m = typeof w.windowDurationMins === 'number' && w.windowDurationMins > 0 && Number.isFinite(w.windowDurationMins) ? w.windowDurationMins : undefined;
-            return window('codex', m === 300 ? 'session' : m === 10080 ? 'weekly' : m === 43200 ? 'monthly' : 'custom', w.usedPercent, m, typeof w.resetsAt === 'number' ? w.resetsAt * 1000 : undefined, false, name.toLowerCase() === 'codex' ? undefined : name);
+            return window('codex', m === 300 ? 'session' : m === 10080 ? 'weekly' : m === 43200 ? 'monthly' : 'custom', w.usedPercent, m, typeof w.resetsAt === 'number' ? w.resetsAt * 1000 : undefined, raw.limitReached === true || w.limitReached === true, name.toLowerCase() === 'codex' ? undefined : name);
         }).sort((a, b) => (a.minutes ?? 0) - (b.minutes ?? 0));
         return rows.length ? [rows] : [];
     });
-    const chosen = groups.flat().sort((a, b) => b.usedPercent - a.usedPercent).slice(0, 8);
+    const chosen = groups.flat().sort((a, b) => Number(b.limited === true) - Number(a.limited === true) || (b.usedPercent ?? -1) - (a.usedPercent ?? -1)).slice(0, 8);
     return groups.map((rows, ordinal) => ({ rows: rows.filter((w) => chosen.includes(w)), ordinal }))
-        .filter((g) => g.rows.length).sort((a, b) => Math.max(...b.rows.map((w) => w.usedPercent)) - Math.max(...a.rows.map((w) => w.usedPercent)) || a.ordinal - b.ordinal).flatMap((g) => g.rows);
+        .filter((g) => g.rows.length).sort((a, b) => Math.max(...b.rows.map((w) => w.usedPercent ?? -1)) - Math.max(...a.rows.map((w) => w.usedPercent ?? -1)) || a.ordinal - b.ordinal).flatMap((g) => g.rows);
 }

package/dist/words.json

@@ -5,5 +5,6 @@
     "code.no-plan": "This {name} account has no plan with limits.",
     "code.rate-limited": "{name} asked us to wait. Showing the last reading.",
     "code.unavailable": "{name} didn't answer. Trying again shortly.",
-    "code.incomplete": "{name} answered in a way we can't read yet."
+    "code.incomplete": "{name} answered in a way we can't read yet.",
+    "code.refresh-failed": "This sign-in could not be renewed. Check it in its own app."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/usage",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Read subscription usage windows per provider and account.",
   "license": "Apache-2.0",
   "type": "module",