@juspay/neurolink 10.4.3 → 10.4.4

package/dist/lib/types/proxy.d.ts

@@ -671,6 +671,29 @@ export type AnthropicUpstreamFetchResult = {
     sawNetworkError: boolean;
     upstreamSpan?: Span;
 };
+export type ProxyTerminalErrorCategory = "authentication" | "client_cancelled" | "fallback_exhausted" | "invalid_request" | "proxy_error" | "rate_limit" | "stream_error" | "unclassified" | "upstream_error" | "other";
+/** Compact, redacted terminal failure retained independently of body logs. */
+export type ProxyTerminalErrorSummary = {
+    id: string;
+    at: number;
+    status: number;
+    category: ProxyTerminalErrorCategory;
+    requestId?: string;
+    account?: string;
+    accountType?: string;
+    errorType?: string;
+    errorCode?: string;
+    terminalOutcome?: string;
+    message?: string;
+};
+/** Optional terminal context supplied when a final request error is recorded. */
+export type ProxyTerminalErrorDetails = {
+    requestId?: string;
+    errorType?: string;
+    errorCode?: string;
+    terminalOutcome?: string;
+    message?: string;
+};
 export type AccountStats = {
     label: string;
     type: string;
@@ -700,6 +723,19 @@ export type ProxyStats = {
     totalQuotaRateLimits: number;
     accounts: Record<string, AccountStats>;
 };
+/** Bounded terminal-error state stored separately from counters and body logs. */
+export type ProxyTerminalErrorJournal = {
+    startedAt: number;
+    totalErrors: number;
+    counts: Record<ProxyTerminalErrorCategory, number>;
+    recent: ProxyTerminalErrorSummary[];
+};
+export type ProxyUsageStatsSnapshot = {
+    stats: ProxyStats;
+    statsVersion: number;
+    terminalErrors: ProxyTerminalErrorJournal;
+    terminalErrorsVersion: number;
+};
 /** Durability and reconciliation state for the proxy usage counters. */
 export type ProxyStatsPersistenceStatus = {
     enabled: boolean;
@@ -712,6 +748,14 @@ export type ProxyStatsPersistenceStatus = {
     lastReconciledAt: number | null;
     lastRecoveryAt: number | null;
     lastError: string | null;
+    terminalErrorsFilePath?: string | null;
+    terminalErrorsRevision?: number;
+    terminalErrorsPending?: number;
+    terminalErrorsInFlight?: number;
+    terminalErrorsUnpersisted?: number;
+    terminalErrorsLastFlushedAt?: number | null;
+    terminalErrorsLastRecoveryAt?: number | null;
+    terminalErrorsLastError?: string | null;
 };
 /** Versioned on-disk snapshot shared by overlapping proxy workers. */
 export type PersistedProxyStatsSnapshot = {
@@ -720,6 +764,13 @@ export type PersistedProxyStatsSnapshot = {
     updatedAt: number;
     stats: ProxyStats;
 };
+/** Versioned terminal-error snapshot isolated from rolling-worker counter writes. */
+export type PersistedProxyTerminalErrorSnapshot = {
+    schemaVersion: 1;
+    revision: number;
+    updatedAt: number;
+    journal: ProxyTerminalErrorJournal;
+};
 /** Ownership metadata for the proxy statistics cross-process lock. */
 export type ProxyStatsLockOwner = {
     token: string;
@@ -729,6 +780,7 @@ export type ProxyStatsLockOwner = {
 /** Construction options for an isolated proxy statistics store. */
 export type ProxyUsageStatsStoreOptions = {
     filePath?: string;
+    terminalErrorsFilePath?: string;
     flushIntervalMs?: number;
     lockTimeoutMs?: number;
     staleLockMs?: number;
@@ -1951,6 +2003,11 @@ export type StatusStats = {
     totalRateLimits: number;
     totalTransientRateLimits?: number;
     totalQuotaRateLimits?: number;
+    terminalErrors?: ProxyTerminalErrorJournal;
+    lastTerminalError?: ProxyTerminalErrorSummary | null;
+    terminalErrorDetailsComparable?: boolean;
+    terminalErrorDetailsMissing?: number;
+    terminalErrorDetailsExcess?: number;
     accounts?: {
         label: string;
         type: string;
@@ -1963,7 +2020,9 @@ export type StatusStats = {
         transientRateLimits?: number;
         quotaRateLimits?: number;
         cooling: boolean;
-        status?: "active" | "cooling" | "disabled" | "excluded" | "removed" | "unattributed";
+        allowed?: boolean;
+        expired?: boolean;
+        status?: "active" | "cooling" | "disabled" | "expired" | "excluded" | "removed" | "internal" | "unattributed";
     }[];
     persistence?: ProxyStatsPersistenceStatus;
 };

package/dist/proxy/proxyTranslationEngine.d.ts

@@ -77,6 +77,7 @@ export declare function handleTranslatedJsonRequest(args: {
     attempts: ProxyTranslationAttempt[];
     tracer?: ProxyTracer;
     requestStartTime: number;
+    terminalFailureStatus?: number;
 }): Promise<unknown>;
 /**
  * Build the /v1/models response in OpenAI list format.

package/dist/proxy/proxyTranslationEngine.js

@@ -247,6 +247,7 @@ export async function handleTranslatedStreamRequest(args) {
     let keepAliveTimer;
     let cancelled = false;
     let succeeded = false;
+    let streamInterruptedAfterOutput = false;
     let translatedModel;
     let finalStreamError = "No translation providers succeeded";
     let upstreamIterator;
@@ -267,6 +268,9 @@ export async function handleTranslatedStreamRequest(args) {
             }, KEEPALIVE_INTERVAL_MS);
             try {
                 for (let attemptIndex = 0; attemptIndex < attempts.length; attemptIndex++) {
+                    if (cancelled) {
+                        break;
+                    }
                     const attempt = attempts[attemptIndex];
                     lastAttemptLabel = attempt.label ?? "translation";
                     logger.always(`[proxy:${format}] attempt ${attemptIndex + 1}/${attempts.length}: ${attempt.label}`);
@@ -295,10 +299,14 @@ export async function handleTranslatedStreamRequest(args) {
                                 }
                             }
                         }
+                        if (cancelled) {
+                            return;
+                        }
                         const toolCalls = streamResult.toolCalls ?? [];
                         if (!hasTranslatedOutput(collectedText, toolCalls)) {
                             finalStreamError = `Translated provider ${attempt.label} returned no content or tool calls`;
                             logger.debug(`${tag} translation attempt ${attempt.label} returned no content or tool calls`);
+                            recordAttemptError(lastAttemptLabel, "translation", 502);
                             continue;
                         }
                         if (!cancelled && toolCalls.length) {
@@ -331,7 +339,6 @@ export async function handleTranslatedStreamRequest(args) {
                         tracer?.recordMetrics();
                         translatedModel = streamResult.model;
                         succeeded = true;
-                        recordFinalSuccess(lastAttemptLabel, "translation");
                         return;
                     }
                     catch (streamErr) {
@@ -343,6 +350,8 @@ export async function handleTranslatedStreamRequest(args) {
                                 ? streamErr.message
                                 : String(streamErr);
                         if (collectedText.trim().length > 0) {
+                            streamInterruptedAfterOutput = true;
+                            recordAttemptError(lastAttemptLabel, "translation", 502);
                             logger.always(`${tag} mid-stream error: ${finalStreamError}`);
                             for (const frame of serializer.emitError(`Upstream stream interrupted: ${finalStreamError}`)) {
                                 controller.enqueue(encoder.encode(frame));
@@ -354,7 +363,6 @@ export async function handleTranslatedStreamRequest(args) {
                     }
                 }
                 // All attempts exhausted
-                recordFinalError(500, lastAttemptLabel, "translation");
                 if (!cancelled) {
                     logger.always(`${tag} all translation attempts failed: ${finalStreamError}`);
                     for (const frame of serializer.emitError(finalStreamError)) {
@@ -372,12 +380,38 @@ export async function handleTranslatedStreamRequest(args) {
                 if (tracer && translatedModel && translatedModel !== requestModel) {
                     tracer.setModelSubstitution(requestModel, translatedModel);
                 }
-                if (!succeeded) {
-                    tracer?.setError("generation_error", finalStreamError.slice(0, 500));
+                const terminalStatus = cancelled
+                    ? 499
+                    : succeeded
+                        ? 200
+                        : streamInterruptedAfterOutput
+                            ? 502
+                            : 500;
+                const terminalErrorType = cancelled
+                    ? "client_cancelled"
+                    : streamInterruptedAfterOutput
+                        ? "stream_error"
+                        : succeeded
+                            ? undefined
+                            : "generation_error";
+                const terminalErrorMessage = cancelled
+                    ? "Client cancelled the streaming response"
+                    : succeeded
+                        ? undefined
+                        : finalStreamError;
+                if (terminalErrorType && terminalErrorMessage) {
+                    tracer?.setError(terminalErrorType, terminalErrorMessage.slice(0, 500));
+                    recordFinalError(terminalStatus, lastAttemptLabel, "translation", {
+                        requestId: ctx.requestId,
+                        errorType: terminalErrorType,
+                        terminalOutcome: terminalErrorType,
+                        message: terminalErrorMessage,
+                    });
+                }
+                else {
+                    recordFinalSuccess(lastAttemptLabel, "translation");
                 }
-                // Use the real outcome status so trace data matches the logged
-                // responseStatus below (success path is 200, exhausted-attempts path is 500).
-                tracer?.end(succeeded ? 200 : 500, Date.now() - requestStartTime);
+                tracer?.end(terminalStatus, Date.now() - requestStartTime);
                 const traceCtx = tracer?.getTraceContext();
                 logRequest({
                     timestamp: new Date().toISOString(),
@@ -389,8 +423,12 @@ export async function handleTranslatedStreamRequest(args) {
                     toolCount: Object.keys(parsed.tools).length,
                     account: "translation",
                     accountType: "translation",
-                    responseStatus: succeeded ? 200 : 500,
+                    responseStatus: terminalStatus,
                     responseTimeMs: Date.now() - requestStartTime,
+                    ...(terminalErrorType ? { errorType: terminalErrorType } : {}),
+                    ...(terminalErrorMessage
+                        ? { errorMessage: terminalErrorMessage.slice(0, 500) }
+                        : {}),
                     ...(traceCtx?.traceId ? { traceId: traceCtx.traceId } : {}),
                     ...(traceCtx?.spanId ? { spanId: traceCtx.spanId } : {}),
                 });
@@ -424,7 +462,7 @@ export async function handleTranslatedStreamRequest(args) {
  * Handles a translated non-streaming request for either Claude or OpenAI format.
  */
 export async function handleTranslatedJsonRequest(args) {
-    const { ctx, format, requestModel, parsed, attempts, tracer, requestStartTime, } = args;
+    const { ctx, format, requestModel, parsed, attempts, tracer, requestStartTime, terminalFailureStatus = 500, } = args;
     const tag = logTag(format);
     let lastAttemptError = "No translation providers succeeded";
     let lastAttemptLabel = "translation";
@@ -448,6 +486,7 @@ export async function handleTranslatedJsonRequest(args) {
             if (!hasTranslatedOutput(collectedText, streamResult.toolCalls)) {
                 lastAttemptError = `Translated provider ${attempt.label} returned no content or tool calls`;
                 logger.debug(`${tag} translation attempt ${attempt.label} returned no content or tool calls`);
+                recordAttemptError(lastAttemptLabel, "translation", 502);
                 continue;
             }
             const internal = {
@@ -505,9 +544,14 @@ export async function handleTranslatedJsonRequest(args) {
             recordAttemptError(lastAttemptLabel, "translation", 500);
         }
     }
-    recordFinalError(500, lastAttemptLabel, "translation");
+    recordFinalError(terminalFailureStatus, lastAttemptLabel, "translation", {
+        requestId: ctx.requestId,
+        errorType: "generation_error",
+        terminalOutcome: "handler_error",
+        message: lastAttemptError,
+    });
     tracer?.setError("generation_error", lastAttemptError.slice(0, 500));
-    tracer?.end(500, Date.now() - requestStartTime);
+    tracer?.end(terminalFailureStatus, Date.now() - requestStartTime);
     const traceCtx = tracer?.getTraceContext();
     logRequest({
         timestamp: new Date().toISOString(),
@@ -519,7 +563,7 @@ export async function handleTranslatedJsonRequest(args) {
         toolCount: Object.keys(parsed.tools).length,
         account: "translation",
         accountType: "translation",
-        responseStatus: 500,
+        responseStatus: terminalFailureStatus,
         responseTimeMs: Date.now() - requestStartTime,
         errorType: "generation_error",
         errorMessage: lastAttemptError.slice(0, 500),

package/dist/proxy/rawStreamCapture.js

@@ -60,7 +60,11 @@ export function createRawStreamCapture() {
         },
     });
     const innerWriter = transform.writable.getWriter();
+    let writableController;
     const writable = new WritableStream({
+        start(controller) {
+            writableController = controller;
+        },
         write(chunk) {
             return innerWriter.write(chunk);
         },
@@ -72,9 +76,51 @@ export function createRawStreamCapture() {
             return innerWriter.abort(reason);
         },
     });
+    // A downstream reader cancellation errors the TransformStream's writable
+    // side, but this wrapper otherwise hides that state from the upstream pipe.
+    // Mirror it onto the wrapper so cancellation reaches the source reader.
+    void innerWriter.closed.catch((reason) => {
+        settle();
+        try {
+            writableController.error(reason);
+        }
+        catch {
+            // The wrapper may already be closing or aborted.
+        }
+    });
+    const innerReader = transform.readable.getReader();
+    const readable = new ReadableStream({
+        async pull(controller) {
+            try {
+                const { done, value } = await innerReader.read();
+                if (done) {
+                    controller.close();
+                }
+                else {
+                    controller.enqueue(value);
+                }
+            }
+            catch (error) {
+                controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            settle();
+            try {
+                writableController.error(reason);
+            }
+            catch {
+                // The wrapper may already be closing or aborted.
+            }
+            await Promise.allSettled([
+                innerReader.cancel(reason),
+                innerWriter.abort(reason),
+            ]);
+        },
+    });
     return {
         stream: {
-            readable: transform.readable,
+            readable,
             writable,
         },
         capture,

package/dist/proxy/sseInterceptor.js

@@ -429,7 +429,11 @@ export function createSSEInterceptor(options = {}) {
     // Wrap the writable side so we can intercept abort() — which does NOT
     // trigger the TransformStream's flush() or cancel() callbacks.
     const innerWriter = transform.writable.getWriter();
+    let writableController;
     const writable = new WritableStream({
+        start(controller) {
+            writableController = controller;
+        },
         write(chunk) {
             return innerWriter.write(chunk);
         },
@@ -441,8 +445,50 @@ export function createSSEInterceptor(options = {}) {
             return innerWriter.abort(reason);
         },
     });
+    // Preserve downstream cancellation across the wrapped writable. Without
+    // this bridge, client disconnects leave the upstream source and telemetry
+    // promise open indefinitely after the readable side is cancelled.
+    void innerWriter.closed.catch((reason) => {
+        settle();
+        try {
+            writableController.error(reason);
+        }
+        catch {
+            // The wrapper may already be closing or aborted.
+        }
+    });
+    const innerReader = transform.readable.getReader();
+    const readable = new ReadableStream({
+        async pull(controller) {
+            try {
+                const { done, value } = await innerReader.read();
+                if (done) {
+                    controller.close();
+                }
+                else {
+                    controller.enqueue(value);
+                }
+            }
+            catch (error) {
+                controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            settle();
+            try {
+                writableController.error(reason);
+            }
+            catch {
+                // The wrapper may already be closing or aborted.
+            }
+            await Promise.allSettled([
+                innerReader.cancel(reason),
+                innerWriter.abort(reason),
+            ]);
+        },
+    });
     const stream = {
-        readable: transform.readable,
+        readable,
         writable,
     };
     return { stream, telemetry: telemetryPromise };

package/dist/proxy/tokenRefresh.d.ts

@@ -8,5 +8,11 @@ export declare function isPermanentRefreshFailure(result: RefreshResult): boolea
  * loaded either the old token or the newly rotated token around persistence.
  */
 export declare function refreshToken(account: RefreshableAccount): Promise<RefreshResult>;
+/**
+ * Refreshes against the latest persisted credential generation. Queued
+ * requests can otherwise reject a rotated refresh token and disable a newer
+ * login that was saved while they were waiting.
+ */
+export declare function refreshTokenFromLatest(account: RefreshableAccount, target?: TokenPersistTarget): Promise<RefreshResult>;
 export declare function clearRefreshStateForTests(): void;
 export declare function persistTokens(target: TokenPersistTarget, account: RefreshableAccount): Promise<void>;

package/dist/proxy/tokenRefresh.js

@@ -1,12 +1,14 @@
 import { logger } from "../utils/logger.js";
 import { tokenStore } from "../auth/tokenStore.js";
+import { ANTHROPIC_TOKEN_URL, ANTHROPIC_TOKEN_URL_FALLBACK, CLAUDE_CLI_USER_AGENT, CLAUDE_CODE_CLIENT_ID, } from "../auth/anthropicOAuth.js";
 import { writeJsonSnapshotAtomically } from "./snapshotPersistence.js";
-const REFRESH_URL = "https://api.anthropic.com/v1/oauth/token";
-const REFRESH_URL_FALLBACK = "https://console.anthropic.com/v1/oauth/token";
-const CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { redactUrlForError } from "../utils/logSanitize.js";
 const BUFFER_MS = 5 * 60 * 1000;
 const SUCCESS_CACHE_MS = 60_000;
-const USER_AGENT = "claude-cli/2.1.80 (external, cli)";
+// Bound the best-effort persisted-credential reconciliation read so a hung or
+// slow token-store decrypt can never stall (or abort) a live token refresh.
+const PEEK_TOKENS_TIMEOUT_MS = 2_000;
 const refreshesInFlight = new Map();
 export function needsRefresh(account) {
     return !!(account.expiresAt &&
@@ -23,28 +25,33 @@ async function performTokenRefresh(account) {
     if (!account.refreshToken) {
         return { success: false, error: "No refresh token available" };
     }
-    const formBody = new URLSearchParams({
+    // OAuth 2.0 token endpoints require an `application/x-www-form-urlencoded`
+    // request body (RFC 6749 §6); a JSON body is nonstandard for this grant and
+    // is rejected by RFC-compliant endpoints. Mirror the interactive auth flow
+    // in `anthropicOAuth.ts::_refreshAccessToken`.
+    const requestBody = new URLSearchParams({
         grant_type: "refresh_token",
         refresh_token: account.refreshToken,
-        client_id: CLIENT_ID,
+        client_id: CLAUDE_CODE_CLIENT_ID,
     }).toString();
     const headers = {
         "Content-Type": "application/x-www-form-urlencoded",
-        "User-Agent": USER_AGENT,
+        Accept: "application/json",
+        "User-Agent": CLAUDE_CLI_USER_AGENT,
     };
-    const urls = [REFRESH_URL, REFRESH_URL_FALLBACK];
+    const urls = [ANTHROPIC_TOKEN_URL, ANTHROPIC_TOKEN_URL_FALLBACK];
     let terminalFailure;
     for (const url of urls) {
         try {
             const resp = await fetch(url, {
                 method: "POST",
                 headers,
-                body: formBody,
+                body: requestBody,
                 signal: AbortSignal.timeout(10_000),
             });
             if (!resp.ok) {
                 const errorBody = await resp.text();
-                logger.warn(`[token-refresh] failed for ${account.label} at ${url}`, {
+                logger.warn(`[token-refresh] failed for ${account.label} at ${redactUrlForError(url)}`, {
                     status: resp.status,
                     error: errorBody.slice(0, 500),
                 });
@@ -57,7 +64,7 @@ async function performTokenRefresh(account) {
                     terminalFailure = failure;
                 }
                 // If primary URL returned a non-ok status, try fallback.
-                if (url === REFRESH_URL) {
+                if (url === ANTHROPIC_TOKEN_URL) {
                     continue;
                 }
                 return terminalFailure ?? failure;
@@ -75,11 +82,11 @@ async function performTokenRefresh(account) {
             return { success: true };
         }
         catch (e) {
-            logger.warn(`[token-refresh] exception for ${account.label} at ${url}`, {
+            logger.warn(`[token-refresh] exception for ${account.label} at ${redactUrlForError(url)}`, {
                 error: String(e),
             });
             // If primary URL threw, try fallback
-            if (url === REFRESH_URL) {
+            if (url === ANTHROPIC_TOKEN_URL) {
                 continue;
             }
             return terminalFailure ?? { success: false, error: String(e) };
@@ -151,6 +158,54 @@ export async function refreshToken(account) {
     }
     return shared.result;
 }
+async function reloadPersistedTokenStoreAccount(account, target) {
+    if (!target || typeof target === "string" || !("providerKey" in target)) {
+        return false;
+    }
+    // Best-effort, bounded reconciliation: this only adopts a newer persisted
+    // credential generation if one exists. A decryption/IO failure — or a hung
+    // read — must NOT abort the caller, which can still refresh with the
+    // already-loaded token. Swallow the failure and treat it as "no newer
+    // persisted generation found" so refresh proceeds instead of the account
+    // being spuriously disabled.
+    let stored;
+    try {
+        stored = await withTimeout(tokenStore.peekTokens(target.providerKey), PEEK_TOKENS_TIMEOUT_MS, "[token-refresh] peekTokens reconciliation timed out");
+    }
+    catch (err) {
+        logger.debug("[token-refresh] skipping persisted-state reconciliation (peek failed)", { error: err instanceof Error ? err.message : String(err) });
+        return false;
+    }
+    if (!stored ||
+        stored.expiresAt <= (account.expiresAt ?? 0) ||
+        (stored.accessToken === account.token &&
+            stored.refreshToken === account.refreshToken &&
+            stored.expiresAt === account.expiresAt)) {
+        return false;
+    }
+    account.token = stored.accessToken;
+    account.refreshToken = stored.refreshToken;
+    account.expiresAt = stored.expiresAt;
+    return true;
+}
+/**
+ * Refreshes against the latest persisted credential generation. Queued
+ * requests can otherwise reject a rotated refresh token and disable a newer
+ * login that was saved while they were waiting.
+ */
+export async function refreshTokenFromLatest(account, target) {
+    const reloadedBeforeRefresh = await reloadPersistedTokenStoreAccount(account, target);
+    if (reloadedBeforeRefresh && !needsRefresh(account)) {
+        return { success: true };
+    }
+    const result = await refreshToken(account);
+    if (result.success) {
+        return result;
+    }
+    return (await reloadPersistedTokenStoreAccount(account, target))
+        ? { success: true }
+        : result;
+}
 export function clearRefreshStateForTests() {
     refreshesInFlight.clear();
 }
@@ -183,7 +238,7 @@ async function persistLegacyCredentials(credPath, account) {
 }
 async function persistTokenStoreAccount(providerKey, account) {
     try {
-        const existing = await tokenStore.loadTokens(providerKey);
+        const existing = await withTimeout(tokenStore.peekTokens(providerKey), PEEK_TOKENS_TIMEOUT_MS, "[token-refresh] peekTokens for persistence timed out");
         const merged = {
             accessToken: account.token,
             refreshToken: account.refreshToken ?? existing?.refreshToken,
@@ -191,7 +246,7 @@ async function persistTokenStoreAccount(providerKey, account) {
             tokenType: existing?.tokenType ?? "Bearer",
             ...(existing?.scope ? { scope: existing.scope } : {}),
         };
-        await tokenStore.saveTokens(providerKey, merged);
+        await withTimeout(tokenStore.saveTokens(providerKey, merged), PEEK_TOKENS_TIMEOUT_MS, "[token-refresh] saveTokens timed out");
     }
     catch (err) {
         logger.warn("[token-refresh] Failed to persist TokenStore credentials", {

package/dist/proxy/usageStats.d.ts

@@ -5,34 +5,49 @@
  * shared snapshot asynchronously, under a cross-process lock, so overlapping
  * rolling workers cannot overwrite each other's counters.
  */
-import type { AccountStats, ProxyStats, ProxyStatsPersistenceStatus, ProxyUsageStatsStoreOptions } from "../types/index.js";
+import type { AccountStats, ProxyTerminalErrorDetails, ProxyTerminalErrorJournal, ProxyStats, ProxyStatsPersistenceStatus, ProxyUsageStatsSnapshot, ProxyUsageStatsStoreOptions } from "../types/index.js";
 export declare class ProxyUsageStatsStore {
     private readonly now;
     private readonly flushIntervalMs;
     private readonly lockTimeoutMs;
     private readonly staleLockMs;
     private filePath?;
+    private terminalErrorsFilePath?;
     private stats;
     private pending;
+    private terminalErrors;
+    private pendingTerminalErrors;
     private pendingMutations;
     private inFlightMutations;
+    private pendingTerminalErrorMutations;
+    private inFlightTerminalErrorMutations;
     private revision;
+    private terminalErrorsRevision;
     private flushTimer;
     private readonly flushMutex;
     private lastFlushedAt?;
     private lastReconciledAt?;
     private lastRecoveryAt?;
     private lastError?;
+    private terminalErrorsLastFlushedAt?;
+    private terminalErrorsLastRecoveryAt?;
+    private terminalErrorsLastError?;
+    private snapshotVersion;
     constructor(options?: ProxyUsageStatsStoreOptions);
     initialize(filePath?: string): Promise<void>;
     recordAttempt(accountLabel: string, accountType: string): void;
     recordFinalSuccess(accountLabel?: string, accountType?: string): void;
     recordAttemptError(accountLabel: string, accountType: string, status: number, rateLimitKind?: "transient" | "quota"): void;
-    recordFinalError(_status: number, accountLabel?: string, accountType?: string): void;
+    recordFinalError(status: number, accountLabel?: string, accountType?: string, details?: ProxyTerminalErrorDetails): void;
     getStats(): ProxyStats;
     getAccountStats(label: string): AccountStats | undefined;
+    getTerminalErrors(): ProxyTerminalErrorJournal;
+    getUsageSnapshot(): ProxyUsageStatsSnapshot;
     getPersistenceStatus(): ProxyStatsPersistenceStatus;
     flush(): Promise<void>;
+    private persistStatsDelta;
+    private persistTerminalErrorDelta;
+    reconcileUsageSnapshot(): Promise<ProxyUsageStatsSnapshot>;
     reconcile(): Promise<ProxyStats>;
     resetMemory(): void;
     resetForTests(): Promise<void>;
@@ -41,13 +56,18 @@ export declare class ProxyUsageStatsStore {
     private applyFinalSuccess;
     private applyAttemptError;
     private applyFinalError;
+    private applyTerminalError;
     private ensureAccount;
     private scheduleFlush;
     private cancelFlushTimer;
     private readSnapshot;
+    private readTerminalErrorSnapshot;
     private applySnapshot;
+    private applyTerminalErrorSnapshot;
     private recoverCorruptSnapshot;
+    private recoverCorruptTerminalErrorSnapshot;
     private quarantineCorruptSnapshot;
+    private quarantineCorruptTerminalErrorSnapshot;
     private pruneCorruptSnapshots;
     private describeError;
 }
@@ -55,10 +75,12 @@ export declare function initUsageStats(filePath: string): Promise<void>;
 export declare function recordAttempt(accountLabel: string, accountType: string): void;
 export declare function recordFinalSuccess(accountLabel?: string, accountType?: string): void;
 export declare function recordAttemptError(accountLabel: string, accountType: string, status: number, rateLimitKind?: "transient" | "quota"): void;
-export declare function recordFinalError(_status: number, accountLabel?: string, accountType?: string): void;
+export declare function recordFinalError(status: number, accountLabel?: string, accountType?: string, details?: ProxyTerminalErrorDetails): void;
 export declare function getStats(): ProxyStats;
 export declare function getReconciledStats(): Promise<ProxyStats>;
+export declare function getReconciledUsageSnapshot(): Promise<ProxyUsageStatsSnapshot>;
 export declare function getAccountStats(label: string): AccountStats | undefined;
+export declare function getTerminalErrors(): ProxyTerminalErrorJournal;
 export declare function getUsageStatsPersistenceStatus(): ProxyStatsPersistenceStatus;
 export declare function flushUsageStats(): Promise<void>;
 /** Reset process-local counters while intentionally preserving durable state. */