@juspay/neurolink 10.8.22 → 10.9.1

package/dist/cli/commands/proxy.js

@@ -45,6 +45,8 @@ const PROXY_TELEMETRY_SCRIPT_PATH = fileURLToPath(new URL("../../../scripts/obse
 const PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS = 5_000;
 const LEGACY_STATUS_ACCOUNT_CACHE_TTL_MS = 5_000;
 const PROXY_STATUS_TOKEN_READ_TIMEOUT_MS = 2_000;
+const PROXY_STATUS_RECONCILE_TIMEOUT_MS = 750;
+const PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS = 750;
 let legacyStatusAccountCache;
 // Allowed drift between a pid's OS-reported start time and the persisted
 // ProxySupervisorState.startTime before processLooksLikeProxySupervisor
@@ -1592,9 +1594,20 @@ export async function createProxyStartApp(params) {
         const activeAccountAllowlist = runtimeConfig
             ? runtimeConfig.accountAllowlist
             : params.accountAllowlist;
-        const { getReconciledUsageSnapshot, getUsageStatsPersistenceStatus } = await import("../../lib/proxy/usageStats.js");
+        const { getReconciledUsageSnapshot, getUsageSnapshot, getUsageStatsPersistenceStatus, } = await import("../../lib/proxy/usageStats.js");
         const { loadAccountCooldowns } = await import("../../lib/proxy/accountCooldown.js");
-        const usageSnapshot = await getReconciledUsageSnapshot();
+        let usageSnapshot = getUsageSnapshot();
+        let snapshotSource = "memory";
+        try {
+            usageSnapshot = await withTimeout(getReconciledUsageSnapshot(), PROXY_STATUS_RECONCILE_TIMEOUT_MS, "[proxy] /status usage reconciliation timed out");
+            snapshotSource = "reconciled";
+        }
+        catch (error) {
+            // Status must not become an outage amplifier when a cross-process lock or
+            // a slow filesystem stalls reconciliation. The process-local snapshot is
+            // coherent and its source is explicit to callers.
+            logger.debug(`[proxy] /status using memory stats snapshot: ${error instanceof Error ? error.message : String(error)}`);
+        }
         const { stats, terminalErrors } = usageSnapshot;
         const terminalErrorDetailsComparable = usageSnapshot.statsVersion === usageSnapshot.terminalErrorsVersion;
         const lastTerminalError = terminalErrors.recent.at(-1) ?? null;
@@ -1608,40 +1621,52 @@ export async function createProxyStartApp(params) {
         const supervisorState = loadProxySupervisorState();
         const rollingSupervisorRunning = isRollingHandoffCapable(supervisorState);
         const updateState = loadUpdateState();
-        const cooldowns = await loadAccountCooldowns();
+        const cooldowns = await withTimeout(loadAccountCooldowns(), PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS, "[proxy] /status cooldown inspection timed out").catch((error) => {
+            logger.debug(`[proxy] /status using empty cooldown snapshot: ${error instanceof Error ? error.message : String(error)}`);
+            return {};
+        });
         const storedAccountKeys = new Set();
         const storedAccountExpirations = new Map();
         const disabledAccountKeys = new Set();
         let accountInventoryLoaded = false;
         try {
             const { tokenStore } = await import("../../lib/auth/tokenStore.js");
-            const storedKeys = await tokenStore.listByPrefix("anthropic:");
+            const storedKeys = await withTimeout(tokenStore.listByPrefix("anthropic:"), PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS, "[proxy] /status account enumeration timed out");
             for (const key of storedKeys) {
-                const normalizedKey = normalizeAnthropicAccountKey(key);
-                storedAccountKeys.add(normalizedKey);
+                storedAccountKeys.add(normalizeAnthropicAccountKey(key));
             }
-            await Promise.all(storedKeys.map(async (key) => {
-                const normalizedKey = normalizeAnthropicAccountKey(key);
-                try {
-                    const tokens = await withTimeout(tokenStore.peekTokens(key), PROXY_STATUS_TOKEN_READ_TIMEOUT_MS, "[proxy] /status token inspection timed out");
-                    if (tokens) {
-                        storedAccountExpirations.set(normalizedKey, tokens.expiresAt);
+            // Once account names are known, preserve them even when optional token
+            // metadata is slow. That keeps the status table useful and avoids
+            // incorrectly presenting known accounts as removed.
+            accountInventoryLoaded = true;
+            const inventory = await withTimeout((async () => {
+                const tokenExpirations = await Promise.all(storedKeys.map(async (key) => {
+                    try {
+                        const tokens = await withTimeout(tokenStore.peekTokens(key), PROXY_STATUS_TOKEN_READ_TIMEOUT_MS, "[proxy] /status token inspection timed out");
+                        return tokens ? [key, tokens.expiresAt] : undefined;
                     }
+                    catch (error) {
+                        logger.debug(`[proxy] /status: failed to inspect token metadata for ${normalizeAnthropicAccountKey(key)}: ${error instanceof Error ? error.message : String(error)}`);
+                        return undefined;
+                    }
+                }));
+                const disabledKeys = await tokenStore.listDisabled();
+                return { tokenExpirations, disabledKeys };
+            })(), PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS, "[proxy] /status account metadata timed out");
+            for (const expiration of inventory.tokenExpirations) {
+                if (expiration) {
+                    storedAccountExpirations.set(normalizeAnthropicAccountKey(expiration[0]), expiration[1]);
                 }
-                catch (err) {
-                    logger.debug(`[proxy] /status: failed to inspect token metadata for ${normalizedKey}: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }));
-            for (const key of await tokenStore.listDisabled()) {
+            }
+            for (const key of inventory.disabledKeys) {
                 disabledAccountKeys.add(normalizeAnthropicAccountKey(key));
             }
-            accountInventoryLoaded = true;
         }
         catch (err) {
             logger.debug(`[proxy] /status: failed to resolve account cooldown labels: ${err instanceof Error ? err.message : String(err)}`);
         }
         const legacyAccountLabel = accountInventoryLoaded
-            ? await resolveLegacyStatusAccountLabel(storedAccountKeys.size)
+            ? await withTimeout(resolveLegacyStatusAccountLabel(storedAccountKeys.size), PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS, "[proxy] /status legacy account inspection timed out").catch(() => null)
             : null;
         const now = Date.now();
         const health = buildProxyHealthResponse(readiness, {
@@ -1649,7 +1674,12 @@ export async function createProxyStartApp(params) {
             passthrough: activePassthrough,
             version: PROXY_VERSION,
         });
-        const primaryAccount = await resolveStatusPrimaryAccount(activeProxyConfig);
+        const primaryAccount = await withTimeout(resolveStatusPrimaryAccount(activeProxyConfig), PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS, "[proxy] /status primary account inspection timed out").catch(() => ({
+            configured: activeProxyConfig?.routing?.primaryAccount?.trim() || null,
+            key: null,
+            label: null,
+            source: "fallback",
+        }));
         const activeUpdaterPid = supervisorState?.updaterPid ?? runtimeState?.updaterPid;
         const accountRows = Object.values(stats.accounts).map((account) => {
             const normalizedKey = normalizeAnthropicAccountKey(account.label);
@@ -1813,6 +1843,7 @@ export async function createProxyStartApp(params) {
                 terminalErrorDetailsComparable,
                 terminalErrorDetailsMissing,
                 terminalErrorDetailsExcess,
+                snapshotSource,
                 accounts: accountRows,
                 primaryAccount,
                 persistence: getUsageStatsPersistenceStatus(),

package/dist/lib/agent/directTools.d.ts

@@ -1,4 +1,69 @@
 import type { AllToolsMap, BasicToolsMap, FilesystemToolsMap, Tool, UtilityToolsMap } from "../types/index.js";
+/**
+ * Vertex location for the websearchGrounding tool:
+ * NEUROLINK_WEBSEARCH_LOCATION, else `global`.
+ *
+ * Deliberately does NOT inherit GOOGLE_VERTEX_LOCATION. The search models are
+ * served only from the `global`, `us` and `eu` endpoints — never from a single
+ * region — so inheriting a regional value produces a 404 for the model rather
+ * than a working search. That is not hypothetical: a deployment pinned to
+ * us-east5 for Claude-on-Vertex sent web search to us-east5 too and every
+ * query failed with NOT_FOUND.
+ *
+ * Set NEUROLINK_WEBSEARCH_LOCATION to `us` or `eu` where the multi-region
+ * endpoints are required, e.g. for data residency.
+ */
+export declare function resolveWebsearchLocation(): string;
+/** Model for websearchGrounding — NEUROLINK_WEBSEARCH_MODEL, else the default. */
+export declare function resolveWebsearchModel(): string;
+/**
+ * The generateContent request for a web search. Google Search grounding is
+ * requested natively through `config.tools`.
+ */
+export declare function buildWebsearchRequest(model: string, query: string, maxWords: number): {
+    model: string;
+    contents: {
+        role: string;
+        parts: {
+            text: string;
+        }[];
+    }[];
+    config: {
+        tools: {
+            googleSearch: {};
+        }[];
+    };
+};
+/**
+ * Display domain for one grounding chunk.
+ *
+ * Blank `domain` values count as absent, and the uri fallback is guarded by
+ * `URL.canParse` — an unparseable provider uri would otherwise throw and take
+ * the entire search down with it.
+ */
+export declare function resolveGroundingDomain(web: {
+    uri?: string;
+    domain?: string;
+}): string;
+/**
+ * Map grounding chunks onto search results, capped at `limitedResults`.
+ * Returns an empty array when there is no usable grounding metadata, which the
+ * caller replaces with a single synthesised result.
+ */
+export declare function buildWebsearchResults(groundingMetadata: {
+    groundingChunks?: {
+        web?: {
+            uri?: string;
+            title?: string;
+            domain?: string;
+        };
+    }[];
+} | undefined, searchContent: string, limitedResults: number): {
+    title: string;
+    url: string;
+    snippet: string;
+    domain: string;
+}[];
 /**
  * Direct tool definitions that work immediately with Gemini/AI SDK
  * These bypass MCP complexity and provide reliable agent functionality

package/dist/lib/agent/directTools.js

@@ -6,6 +6,8 @@ import { logger } from "../utils/logger.js";
 import { CSVProcessor } from "../utils/csvProcessor.js";
 import { shouldEnableBashTool } from "../utils/toolUtils.js";
 import { tool } from "../utils/tool.js";
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { TIMEOUTS } from "../constants/timeouts.js";
 const MAX_OUTPUT_BYTES = 102400; // 100KB
 function truncateOutput(output) {
     if (output.length > MAX_OUTPUT_BYTES) {
@@ -35,16 +37,77 @@ function resolveWithinCwd(filePath) {
     }
     return { path: resolvedPath };
 }
-// Runtime Google Search tool creation - bypasses TypeScript strict typing
-function createGoogleSearchTools() {
-    const searchTool = {};
-    // Dynamically assign google_search property at runtime
-    Object.defineProperty(searchTool, "google_search", {
-        value: {},
-        enumerable: true,
-        configurable: true,
-    });
-    return [searchTool];
+/**
+ * Vertex location for the websearchGrounding tool:
+ * NEUROLINK_WEBSEARCH_LOCATION, else `global`.
+ *
+ * Deliberately does NOT inherit GOOGLE_VERTEX_LOCATION. The search models are
+ * served only from the `global`, `us` and `eu` endpoints — never from a single
+ * region — so inheriting a regional value produces a 404 for the model rather
+ * than a working search. That is not hypothetical: a deployment pinned to
+ * us-east5 for Claude-on-Vertex sent web search to us-east5 too and every
+ * query failed with NOT_FOUND.
+ *
+ * Set NEUROLINK_WEBSEARCH_LOCATION to `us` or `eu` where the multi-region
+ * endpoints are required, e.g. for data residency.
+ */
+export function resolveWebsearchLocation() {
+    return process.env.NEUROLINK_WEBSEARCH_LOCATION?.trim() || "global";
+}
+/** Model for websearchGrounding — NEUROLINK_WEBSEARCH_MODEL, else the default. */
+export function resolveWebsearchModel() {
+    return (process.env.NEUROLINK_WEBSEARCH_MODEL?.trim() || "gemini-3.1-flash-lite");
+}
+/**
+ * The generateContent request for a web search. Google Search grounding is
+ * requested natively through `config.tools`.
+ */
+export function buildWebsearchRequest(model, query, maxWords) {
+    return {
+        model,
+        contents: [
+            {
+                role: "user",
+                parts: [
+                    {
+                        text: `Search for: "${query}". Provide a concise summary in no more than ${maxWords} words.`,
+                    },
+                ],
+            },
+        ],
+        config: { tools: [{ googleSearch: {} }] },
+    };
+}
+/**
+ * Display domain for one grounding chunk.
+ *
+ * Blank `domain` values count as absent, and the uri fallback is guarded by
+ * `URL.canParse` — an unparseable provider uri would otherwise throw and take
+ * the entire search down with it.
+ */
+export function resolveGroundingDomain(web) {
+    return (web.domain?.trim() ||
+        (web.uri && URL.canParse(web.uri) ? new URL(web.uri).hostname : "unknown"));
+}
+/**
+ * Map grounding chunks onto search results, capped at `limitedResults`.
+ * Returns an empty array when there is no usable grounding metadata, which the
+ * caller replaces with a single synthesised result.
+ */
+export function buildWebsearchResults(groundingMetadata, searchContent, limitedResults) {
+    const searchResults = [];
+    for (const chunk of groundingMetadata?.groundingChunks?.slice(0, limitedResults) ?? []) {
+        if (chunk.web) {
+            searchResults.push({
+                title: chunk.web.title || "No title",
+                url: chunk.web.uri || "",
+                // Full content — maxWords already bounds the length.
+                snippet: searchContent,
+                domain: resolveGroundingDomain(chunk.web),
+            });
+        }
+    }
+    return searchResults;
 }
 /**
  * Direct tool definitions that work immediately with Gemini/AI SDK
@@ -593,7 +656,7 @@ export const directAgentTools = {
             try {
                 const hasCredentials = process.env.GOOGLE_APPLICATION_CREDENTIALS;
                 const hasProjectId = process.env.GOOGLE_VERTEX_PROJECT;
-                const projectLocation = process.env.GOOGLE_VERTEX_LOCATION || "us-central1";
+                const projectLocation = resolveWebsearchLocation();
                 if (!hasCredentials || !hasProjectId) {
                     return {
                         success: false,
@@ -605,31 +668,19 @@ export const directAgentTools = {
                     };
                 }
                 const limitedResults = Math.min(Math.max(maxResults, 1), 5);
-                const { VertexAI } = await import("@google-cloud/vertexai");
-                const vertex_ai = new VertexAI({
+                const { GoogleGenAI } = await import("@google/genai");
+                const vertex_ai = new GoogleGenAI({
+                    vertexai: true,
                     project: hasProjectId,
                     location: projectLocation,
                 });
-                const websearchModel = process.env.NEUROLINK_WEBSEARCH_MODEL?.trim() ||
-                    "gemini-2.5-flash-lite";
-                const model = vertex_ai.getGenerativeModel({
-                    model: websearchModel,
-                    tools: createGoogleSearchTools(),
-                });
-                // Search query with word limit constraint
-                const searchPrompt = `Search for: "${query}". Provide a concise summary in no more than ${maxWords} words.`;
+                const websearchModel = resolveWebsearchModel();
                 const startTime = Date.now();
-                const response = await model.generateContent({
-                    contents: [
-                        {
-                            role: "user",
-                            parts: [{ text: searchPrompt }],
-                        },
-                    ],
-                });
+                // A stalled Vertex call would otherwise leave the tool pending
+                // indefinitely; the outer catch turns a timeout into the failure shape.
+                const result = await withTimeout(vertex_ai.models.generateContent(buildWebsearchRequest(websearchModel, query, maxWords)), TIMEOUTS.TOOL.EXECUTION_DEFAULT_MS, "[websearchGrounding] Vertex AI web search request timed out");
                 const responseTime = Date.now() - startTime;
                 // Extract grounding metadata and search results
-                const result = response.response;
                 const candidates = result.candidates;
                 if (!candidates || candidates.length === 0) {
                     return {
@@ -638,33 +689,18 @@ export const directAgentTools = {
                         query,
                     };
                 }
-                const content = candidates[0].content;
-                if (!content || !content.parts || content.parts.length === 0) {
+                // Extract raw search content. The aggregated `text` getter joins every
+                // text part, so it survives responses that lead with a non-text part.
+                const searchContent = result.text?.trim() || "";
+                if (!searchContent) {
                     return {
                         success: false,
                         error: "No search content found",
                         query,
                     };
                 }
-                // Extract raw search content
-                const searchContent = content.parts[0].text || "";
                 // Extract grounding sources if available
-                const groundingMetadata = candidates[0]?.groundingMetadata;
-                const searchResults = [];
-                if (groundingMetadata?.groundingChunks) {
-                    for (const chunk of groundingMetadata.groundingChunks.slice(0, limitedResults)) {
-                        if (chunk.web) {
-                            searchResults.push({
-                                title: chunk.web.title || "No title",
-                                url: chunk.web.uri || "",
-                                snippet: searchContent, // Use full content since maxWords already limits length
-                                domain: chunk.web.uri
-                                    ? new URL(chunk.web.uri).hostname
-                                    : "unknown",
-                            });
-                        }
-                    }
-                }
+                const searchResults = buildWebsearchResults(candidates[0]?.groundingMetadata, searchContent, limitedResults);
                 // If no grounding metadata, create basic result structure
                 if (searchResults.length === 0) {
                     searchResults.push({

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

@@ -1,3 +1,4 @@
+import { appendFile } from "node:fs/promises";
 import type { ProxyLifecycleEventInput, ProxyLifecycleLoggerOptions, ProxyLifecycleLoggerSnapshot } from "../types/index.js";
 export declare function hashProxyLifecycleSessionId(sessionId: string | undefined): string | undefined;
 export declare function configureProxyLifecycleLogger(options: ProxyLifecycleLoggerOptions): void;
@@ -6,3 +7,7 @@ export declare function logProxyLifecycleEvent(input: ProxyLifecycleEventInput):
 export declare function flushProxyLifecycleEvents(): Promise<void>;
 export declare function getProxyLifecycleLoggerSnapshot(): ProxyLifecycleLoggerSnapshot;
 export declare function resetProxyLifecycleLoggerForTests(): void;
+/** Isolated failure injection for lifecycle durability tests. */
+export declare const __proxyLifecycleTestHooks: {
+    setAppendFileForTests(append: typeof appendFile): void;
+};

package/dist/lib/proxy/proxyLifecycle.js

@@ -9,6 +9,8 @@ const SCHEMA_VERSION = 1;
 const DEFAULT_QUEUE_CAPACITY = 10_000;
 const DEFAULT_BATCH_SIZE = 256;
 const DEFAULT_FLUSH_INTERVAL_MS = 25;
+const DEFAULT_MAX_WRITE_RETRIES = 3;
+const MAX_WRITE_RETRY_DELAY_MS = 1_000;
 const LIFECYCLE_APPEND_TIMEOUT_MS = 2_000;
 const MAX_SHORT_FIELD_LENGTH = 256;
 const SESSION_KEY_FILE = ".proxy-lifecycle-session-key";
@@ -17,6 +19,7 @@ let lifecycleLogDir;
 let queueCapacity = DEFAULT_QUEUE_CAPACITY;
 let batchSize = DEFAULT_BATCH_SIZE;
 let flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS;
+let maxWriteRetries = DEFAULT_MAX_WRITE_RETRIES;
 let processInstanceId = randomUUID();
 let sessionHashKey = randomBytes(32);
 let nextSequence = 1;
@@ -28,10 +31,13 @@ let queueDrops = 0;
 let invalidDrops = 0;
 let writeDrops = 0;
 let writeFailures = 0;
+let writeRetries = 0;
 let inFlight = 0;
 let queue = [];
 let flushTimer;
 let flushInFlight;
+let nextFlushDelayMs;
+let appendLifecycleFile = appendFile;
 function positiveInteger(value, fallback) {
     return Number.isInteger(value) && (value ?? 0) > 0
         ? value
@@ -123,14 +129,14 @@ function clearScheduledFlush() {
         flushTimer = undefined;
     }
 }
-function scheduleFlush() {
+function scheduleFlush(delayMs = flushIntervalMs) {
     if (flushTimer || flushInFlight || queue.length === 0) {
         return;
     }
     flushTimer = setTimeout(() => {
         flushTimer = undefined;
         void startFlush();
-    }, flushIntervalMs);
+    }, delayMs);
     flushTimer.unref?.();
 }
 async function flushBatch() {
@@ -143,27 +149,53 @@ async function flushBatch() {
         const byPath = new Map();
         for (const item of batch) {
             const path = join(item.logDir, `proxy-lifecycle-${item.date}.jsonl`);
-            const lines = byPath.get(path) ?? [];
-            lines.push(`${JSON.stringify(item.record)}\n`);
-            byPath.set(path, lines);
+            const items = byPath.get(path) ?? [];
+            items.push(item);
+            byPath.set(path, items);
         }
-        for (const [path, lines] of byPath) {
+        const retries = [];
+        let retryDelayMs = 0;
+        for (const [path, items] of byPath) {
+            const lines = items.map((item) => `${JSON.stringify(item.record)}\n`);
             try {
                 // This best-effort telemetry sink intentionally avoids fsync so request
                 // throughput is not coupled to storage latency. Loss is surfaced by
                 // writeDrops/writeFailures rather than delaying proxy responses.
-                await withTimeout(appendFile(path, lines.join(""), { mode: 0o600 }), LIFECYCLE_APPEND_TIMEOUT_MS, "Timed out writing proxy lifecycle metadata");
+                await withTimeout(appendLifecycleFile(path, lines.join(""), { mode: 0o600 }), LIFECYCLE_APPEND_TIMEOUT_MS, "Timed out writing proxy lifecycle metadata");
                 written += lines.length;
             }
             catch (error) {
-                dropped += lines.length;
-                writeDrops += lines.length;
                 writeFailures += 1;
+                const retryable = items.filter((item) => item.writeRetries < maxWriteRetries);
+                const exhausted = items.length - retryable.length;
+                if (retryable.length > 0) {
+                    const nextRetries = retryable.map((item) => ({
+                        ...item,
+                        writeRetries: item.writeRetries + 1,
+                    }));
+                    retries.push(...nextRetries);
+                    writeRetries += nextRetries.length;
+                    retryDelayMs = Math.max(retryDelayMs, Math.min(MAX_WRITE_RETRY_DELAY_MS, flushIntervalMs *
+                        2 ** Math.max(...nextRetries.map((item) => item.writeRetries))));
+                }
+                if (exhausted > 0) {
+                    dropped += exhausted;
+                    writeDrops += exhausted;
+                }
                 logger.warn("[proxy] lifecycle metadata write failed", {
+                    path,
+                    retrying: retryable.length,
+                    dropped: exhausted,
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
         }
+        if (retries.length > 0) {
+            // Keep retried records ahead of newly admitted records. This preserves
+            // per-file sequence order while continuing to keep request paths async.
+            queue.unshift(...retries);
+            nextFlushDelayMs = Math.max(nextFlushDelayMs ?? 0, retryDelayMs || flushIntervalMs);
+        }
     }
     finally {
         inFlight = Math.max(0, inFlight - batch.length);
@@ -179,21 +211,27 @@ function startFlush() {
         if (flushInFlight === currentFlush) {
             flushInFlight = undefined;
         }
-        scheduleFlush();
+        const delayMs = nextFlushDelayMs;
+        nextFlushDelayMs = undefined;
+        scheduleFlush(delayMs);
     }, () => {
         if (flushInFlight === currentFlush) {
             flushInFlight = undefined;
         }
-        scheduleFlush();
+        const delayMs = nextFlushDelayMs;
+        nextFlushDelayMs = undefined;
+        scheduleFlush(delayMs);
     });
     return currentFlush;
 }
 export function configureProxyLifecycleLogger(options) {
     clearScheduledFlush();
+    nextFlushDelayMs = undefined;
     loggerEnabled = false;
     lifecycleLogDir = undefined;
     queueCapacity = positiveInteger(options.queueCapacity, DEFAULT_QUEUE_CAPACITY);
     batchSize = positiveInteger(options.batchSize, DEFAULT_BATCH_SIZE);
+    maxWriteRetries = positiveInteger(options.maxWriteRetries, DEFAULT_MAX_WRITE_RETRIES);
     flushIntervalMs = positiveInteger(options.flushIntervalMs, DEFAULT_FLUSH_INTERVAL_MS);
     if (options.enabled && options.logDir) {
         try {
@@ -268,6 +306,7 @@ export function logProxyLifecycleEvent(input) {
             logDir: lifecycleLogDir,
             date: String(record.timestamp).slice(0, 10),
             record,
+            writeRetries: 0,
         });
         enqueued += 1;
         scheduleFlush();
@@ -303,6 +342,7 @@ export function getProxyLifecycleLoggerSnapshot() {
         invalidDrops,
         writeDrops,
         writeFailures,
+        writeRetries,
         pending: queue.length,
         inFlight,
         flushing: flushInFlight !== undefined,
@@ -315,6 +355,7 @@ export function resetProxyLifecycleLoggerForTests() {
     queueCapacity = DEFAULT_QUEUE_CAPACITY;
     batchSize = DEFAULT_BATCH_SIZE;
     flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS;
+    maxWriteRetries = DEFAULT_MAX_WRITE_RETRIES;
     processInstanceId = randomUUID();
     sessionHashKey = randomBytes(32);
     nextSequence = 1;
@@ -326,8 +367,17 @@ export function resetProxyLifecycleLoggerForTests() {
     invalidDrops = 0;
     writeDrops = 0;
     writeFailures = 0;
+    writeRetries = 0;
     inFlight = 0;
     queue = [];
     flushInFlight = undefined;
+    nextFlushDelayMs = undefined;
+    appendLifecycleFile = appendFile;
 }
+/** Isolated failure injection for lifecycle durability tests. */
+export const __proxyLifecycleTestHooks = {
+    setAppendFileForTests(append) {
+        appendLifecycleFile = append;
+    },
+};
 //# sourceMappingURL=proxyLifecycle.js.map

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

@@ -77,6 +77,8 @@ export declare function recordFinalSuccess(accountLabel?: string, accountType?:
 export declare function recordAttemptError(accountLabel: string, accountType: string, status: number, rateLimitKind?: "transient" | "quota"): void;
 export declare function recordFinalError(status: number, accountLabel?: string, accountType?: string, details?: ProxyTerminalErrorDetails): void;
 export declare function getStats(): ProxyStats;
+/** Return the process-local coherent snapshot without filesystem reconciliation. */
+export declare function getUsageSnapshot(): ProxyUsageStatsSnapshot;
 export declare function getReconciledStats(): Promise<ProxyStats>;
 export declare function getReconciledUsageSnapshot(): Promise<ProxyUsageStatsSnapshot>;
 export declare function getAccountStats(label: string): AccountStats | undefined;

package/dist/lib/proxy/usageStats.js

@@ -1121,6 +1121,10 @@ export function recordFinalError(status, accountLabel, accountType, details) {
 export function getStats() {
     return defaultStore.getStats();
 }
+/** Return the process-local coherent snapshot without filesystem reconciliation. */
+export function getUsageSnapshot() {
+    return defaultStore.getUsageSnapshot();
+}
 export async function getReconciledStats() {
     return defaultStore.reconcile();
 }

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

@@ -1246,6 +1246,8 @@ export type ProxyLifecycleLoggerSnapshot = {
     invalidDrops: number;
     writeDrops: number;
     writeFailures: number;
+    /** Events requeued after a transient lifecycle metadata write failure. */
+    writeRetries: number;
     pending: number;
     inFlight: number;
     flushing: boolean;
@@ -1257,12 +1259,15 @@ export type ProxyLifecycleLoggerOptions = {
     queueCapacity?: number;
     batchSize?: number;
     flushIntervalMs?: number;
+    /** Bounded retries for a metadata batch that cannot be appended immediately. */
+    maxWriteRetries?: number;
 };
 /** Serialized lifecycle line awaiting a bounded batch write. */
 export type QueuedProxyLifecycleEvent = {
     logDir: string;
     date: string;
     record: Record<string, unknown>;
+    writeRetries: number;
 };
 /** Percentile summary used by offline proxy log analysis. */
 export type ProxyLatencySummary = {
@@ -2167,6 +2172,8 @@ export type StatusStats = {
     terminalErrorDetailsComparable?: boolean;
     terminalErrorDetailsMissing?: number;
     terminalErrorDetailsExcess?: number;
+    /** Whether this status response reconciled shared state or used local memory. */
+    snapshotSource?: "reconciled" | "memory";
     accounts?: {
         label: string;
         type: string;

package/dist/proxy/proxyLifecycle.d.ts

@@ -1,3 +1,4 @@
+import { appendFile } from "node:fs/promises";
 import type { ProxyLifecycleEventInput, ProxyLifecycleLoggerOptions, ProxyLifecycleLoggerSnapshot } from "../types/index.js";
 export declare function hashProxyLifecycleSessionId(sessionId: string | undefined): string | undefined;
 export declare function configureProxyLifecycleLogger(options: ProxyLifecycleLoggerOptions): void;
@@ -6,3 +7,7 @@ export declare function logProxyLifecycleEvent(input: ProxyLifecycleEventInput):
 export declare function flushProxyLifecycleEvents(): Promise<void>;
 export declare function getProxyLifecycleLoggerSnapshot(): ProxyLifecycleLoggerSnapshot;
 export declare function resetProxyLifecycleLoggerForTests(): void;
+/** Isolated failure injection for lifecycle durability tests. */
+export declare const __proxyLifecycleTestHooks: {
+    setAppendFileForTests(append: typeof appendFile): void;
+};