@juspay/neurolink 10.12.4 → 10.12.6

package/dist/processors/archive/zipEntryReader.js

@@ -0,0 +1,80 @@
+/**
+ * Bounded ZIP entry reading, shared by every processor that opens a ZIP.
+ *
+ * Extracted from ArchiveProcessor because the Office formats are ZIPs too:
+ * .pptx and .odt read their entries directly and so can be handed the same
+ * bomb, and need the same refusal. One implementation rather than three means
+ * a correction to the guard lands everywhere at once.
+ *
+ * .docx and .xlsx deliberately do NOT use this. mammoth and exceljs unzip for
+ * themselves and were measured refusing a 400MB bomb at 46MB and 53MB peak,
+ * so wrapping them in a pre-scan bought no safety and roughly tripled the cost
+ * of every ordinary document.
+ *
+ * @module processors/archive/zipEntryReader
+ */
+/** ZIP compression methods this reader handles (APPNOTE 4.4.5). */
+export const ZIP_METHOD_STORED = 0;
+export const ZIP_METHOD_DEFLATED = 8;
+/**
+ * Whether a zlib rejection is the output bound firing rather than bad input.
+ *
+ * `maxOutputLength` aborts an inflate the moment its output would pass the cap,
+ * which is the whole point — but it surfaces as a plain `RangeError`, and a
+ * bomb reported as "failed to decompress" reads as a corrupt upload and invites
+ * the user to send it again. It will fail identically every time.
+ *
+ * Keyed on `code`, not the message: the message embeds a byte count.
+ */
+export const isDecompressionBoundExceeded = (error) => error?.code === "ERR_BUFFER_TOO_LARGE";
+/**
+ * Read one ZIP entry's bytes without trusting the size it declares.
+ *
+ * `entry.getData()` cannot be used for this. It sizes its output buffer from
+ * the central-directory `size` field, which the archive author chooses, and
+ * adm-zip only arms its own guard when that field is positive:
+ *
+ *   const option = version >= 15 && expectedLength > 0
+ *     ? { maxOutputLength: expectedLength } : {};
+ *
+ * So an entry declaring 0 disables the bound and the caller's `size > maxSize`
+ * check in one move — `0 > 5MB` is false, and the inflate then runs uncapped.
+ * The declared size is the attack, so nothing here may depend on it: the cap
+ * comes from our own limit and is handed to the decoder.
+ *
+ * CRC is verified on both paths rather than dropped, so bypassing `getData()`
+ * does not also quietly lose its corruption check — a STORED entry is copied
+ * out rather than decoded, but it can be damaged just the same. It detects
+ * damage, not malice — the CRC field is attacker-controlled too.
+ */
+export function readZipEntryWithinLimit(entry, maxBytes, zlibModule) {
+    const compressed = entry.getCompressedData();
+    const matchesCrc = (data) => (zlibModule.crc32(data) >>> 0) === (entry.header.crc >>> 0);
+    // STORED: the bytes are already the payload, so its own length is the bound.
+    if (entry.header.method === ZIP_METHOD_STORED) {
+        if (compressed.length > maxBytes) {
+            return { status: "too-large" };
+        }
+        return matchesCrc(compressed)
+            ? { status: "ok", buffer: compressed }
+            : { status: "corrupt" };
+    }
+    if (entry.header.method !== ZIP_METHOD_DEFLATED) {
+        return { status: "unsupported-method" };
+    }
+    let inflated;
+    try {
+        inflated = zlibModule.inflateRawSync(compressed, {
+            maxOutputLength: maxBytes,
+        });
+    }
+    catch (error) {
+        if (isDecompressionBoundExceeded(error)) {
+            return { status: "too-large" };
+        }
+        return { status: "corrupt" };
+    }
+    return matchesCrc(inflated)
+        ? { status: "ok", buffer: inflated }
+        : { status: "corrupt" };
+}

package/dist/processors/document/OpenDocumentProcessor.js

@@ -7,7 +7,9 @@
  * @module processors/document/OpenDocumentProcessor
  */
 import { createRequire } from "node:module";
+import * as zlib from "node:zlib";
 import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
+import { readZipEntryWithinLimit } from "../archive/zipEntryReader.js";
 import { SIZE_LIMITS } from "../config/index.js";
 const require = createRequire(import.meta.url);
 // Re-import for local use within this file
@@ -64,7 +66,17 @@ export class OpenDocumentProcessor extends BaseFileProcessor {
             // Try to get content.xml
             const contentEntry = zip.getEntry("content.xml");
             if (contentEntry) {
-                const xmlContent = contentEntry.getData().toString("utf-8");
+                // Bounded rather than `getData()`: an ODF file is a ZIP, so its
+                // content.xml can declare any uncompressed size it likes, and
+                // `maxSizeMB` only ever saw the compressed archive on the way in.
+                const read = readZipEntryWithinLimit(contentEntry, SIZE_LIMITS.DOCUMENT_MAX_MB * 1024 * 1024, zlib);
+                if (read.status === "too-large") {
+                    throw new Error(`content.xml exceeds the ${SIZE_LIMITS.DOCUMENT_MAX_MB}MB limit for OpenDocument content`);
+                }
+                if (read.status !== "ok") {
+                    throw new Error("content.xml could not be read from the archive");
+                }
+                const xmlContent = read.buffer.toString("utf-8");
                 const extracted = this.extractTextFromXml(xmlContent);
                 textContent = extracted.text;
                 paragraphCount = extracted.paragraphCount;

package/dist/processors/document/PptxProcessor.js

@@ -27,6 +27,47 @@
  * ```
  */
 import AdmZip from "adm-zip";
+import * as zlib from "node:zlib";
+import { readZipEntryWithinLimit } from "../archive/zipEntryReader.js";
+import { SIZE_LIMITS } from "../config/index.js";
+/**
+ * Total budget for everything read out of one presentation.
+ *
+ * This class is a static utility with no `BaseFileProcessor` behind it, so
+ * there is no `maxSizeMB` to inherit and nothing else was bounding these
+ * reads at all — not even a late check. A .pptx is a ZIP, so any entry in it
+ * can declare whatever uncompressed size its author likes.
+ */
+const PPTX_MAX_TOTAL_BYTES = SIZE_LIMITS.DOCUMENT_MAX_MB * 1024 * 1024;
+/**
+ * Read entries out of one presentation, refusing once the total passes budget.
+ *
+ * The budget spans the call rather than each entry: a deck of two hundred
+ * slides that each sit just under a per-entry limit is the obvious way around
+ * one. Returns null for an absent or unreadable entry, which every call site
+ * already treats as "no content here".
+ */
+function createBoundedEntryReader() {
+    let spent = 0;
+    return (entry) => {
+        if (!entry) {
+            return null;
+        }
+        const remaining = PPTX_MAX_TOTAL_BYTES - spent;
+        if (remaining <= 0) {
+            throw new Error(`PPTX content exceeds the ${SIZE_LIMITS.DOCUMENT_MAX_MB}MB limit`);
+        }
+        const read = readZipEntryWithinLimit(entry, remaining, zlib);
+        if (read.status === "too-large") {
+            throw new Error(`PPTX content exceeds the ${SIZE_LIMITS.DOCUMENT_MAX_MB}MB limit`);
+        }
+        if (read.status !== "ok") {
+            return null;
+        }
+        spent += read.buffer.length;
+        return read.buffer.toString("utf-8");
+    };
+}
 /**
  * Regex to match text content within PowerPoint XML `<a:t>` elements.
  * These elements contain the actual visible text on slides.
@@ -63,14 +104,17 @@ export class PptxProcessor {
     static async extractText(content) {
         const zip = new AdmZip(content);
         const entries = zip.getEntries();
+        const readEntry = createBoundedEntryReader();
         // Collect slide entries with their slide numbers for sorting
         const slides = [];
         for (const entry of entries) {
             const match = entry.entryName.match(SLIDE_ENTRY_REGEX);
             if (match) {
                 const slideNumber = parseInt(match[1], 10);
-                const xmlContent = entry.getData().toString("utf-8");
-                slides.push({ slideNumber, xml: xmlContent });
+                const xmlContent = readEntry(entry);
+                if (xmlContent !== null) {
+                    slides.push({ slideNumber, xml: xmlContent });
+                }
             }
         }
         // Sort slides by number (slide1, slide2, ...)
@@ -82,7 +126,7 @@ export class PptxProcessor {
         parts.push(`Presentation: ${slides.length} slide(s)\n`);
         for (const slide of slides) {
             const texts = PptxProcessor.extractTextFromXml(slide.xml);
-            const notes = PptxProcessor.extractNotesForSlide(zip, slide.slideNumber);
+            const notes = PptxProcessor.extractNotesForSlide(zip, slide.slideNumber, readEntry);
             // Emit a slide section when it has either body text or speaker notes.
             if (texts.length > 0 || notes) {
                 parts.push(`### Slide ${slide.slideNumber}`);
@@ -111,12 +155,11 @@ export class PptxProcessor {
      * @param slideNumber - 1-indexed slide number
      * @returns The notes text (runs joined by a space), or null when absent
      */
-    static extractNotesForSlide(zip, slideNumber) {
-        const relsEntry = zip.getEntry(SLIDE_RELS_NAME(slideNumber));
-        if (!relsEntry) {
+    static extractNotesForSlide(zip, slideNumber, readEntry) {
+        const relsXml = readEntry(zip.getEntry(SLIDE_RELS_NAME(slideNumber)));
+        if (relsXml === null) {
             return null;
         }
-        const relsXml = relsEntry.getData().toString("utf-8");
         let notesTarget = null;
         RELATIONSHIP_TAG_REGEX.lastIndex = 0;
         for (let match = RELATIONSHIP_TAG_REGEX.exec(relsXml); match !== null; match = RELATIONSHIP_TAG_REGEX.exec(relsXml)) {
@@ -134,11 +177,11 @@ export class PptxProcessor {
         const normalized = notesTarget
             .replace(/^\.\.\//, "ppt/")
             .replace(/^\/+/, "");
-        const notesEntry = zip.getEntry(normalized);
-        if (!notesEntry) {
+        const notesXml = readEntry(zip.getEntry(normalized));
+        if (notesXml === null) {
             return null;
         }
-        const notes = PptxProcessor.extractTextFromXml(notesEntry.getData().toString("utf-8")).join(" ");
+        const notes = PptxProcessor.extractTextFromXml(notesXml).join(" ");
         return notes.trim() || null;
     }
     /**
@@ -175,6 +218,7 @@ export class PptxProcessor {
     static async extractSlides(content, slideNumbers) {
         const zip = new AdmZip(content);
         const entries = zip.getEntries();
+        const readEntry = createBoundedEntryReader();
         // Collect all slides
         const slides = [];
         for (const entry of entries) {
@@ -182,8 +226,10 @@ export class PptxProcessor {
             if (match) {
                 const slideNumber = parseInt(match[1], 10);
                 if (slideNumbers.includes(slideNumber)) {
-                    const xmlContent = entry.getData().toString("utf-8");
-                    slides.push({ slideNumber, xml: xmlContent });
+                    const xmlContent = readEntry(entry);
+                    if (xmlContent !== null) {
+                        slides.push({ slideNumber, xml: xmlContent });
+                    }
                 }
             }
         }

package/dist/proxy/logCleanupScheduler.d.ts

@@ -0,0 +1,12 @@
+import type { ProxyLogCleanupScheduler } from "../types/index.js";
+/**
+ * Runs retention in a worker so large log trees cannot delay readiness or
+ * block active streams. Concurrent runs are coalesced into the active scan.
+ */
+export declare function startProxyLogCleanupScheduler(params: {
+    logsDir: string;
+    maxAgeDays?: number;
+    maxSizeMb?: number;
+    initialDelayMs?: number;
+    intervalMs?: number;
+}): ProxyLogCleanupScheduler;

package/dist/proxy/logCleanupScheduler.js

@@ -0,0 +1,73 @@
+import { Worker } from "node:worker_threads";
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { logger } from "../utils/logger.js";
+const DEFAULT_INITIAL_DELAY_MS = 30_000;
+const DEFAULT_INTERVAL_MS = 60 * 60 * 1000;
+const WORKER_TERMINATION_TIMEOUT_MS = 5_000;
+/**
+ * Runs retention in a worker so large log trees cannot delay readiness or
+ * block active streams. Concurrent runs are coalesced into the active scan.
+ */
+export function startProxyLogCleanupScheduler(params) {
+    const maxAgeDays = params.maxAgeDays ?? 7;
+    const maxSizeMb = params.maxSizeMb ?? 500;
+    let activeWorker;
+    let stopped = false;
+    const trigger = () => {
+        if (stopped || activeWorker) {
+            return false;
+        }
+        let worker;
+        try {
+            worker = new Worker(params.workerUrl ??
+                new URL("./logCleanupWorkerEntry.js", import.meta.url), {
+                execArgv: process.execArgv.filter((argument) => !argument.startsWith("--input-type")),
+                workerData: {
+                    logsDir: params.logsDir,
+                    maxAgeDays,
+                    maxSizeMb,
+                },
+            });
+        }
+        catch (error) {
+            logger.debug(`[proxy] could not start background log cleanup: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+        activeWorker = worker;
+        worker.unref();
+        worker.once("error", (error) => {
+            logger.debug(`[proxy] background log cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        worker.once("exit", (code) => {
+            if (activeWorker === worker) {
+                activeWorker = undefined;
+            }
+            if (code !== 0 && !stopped) {
+                logger.debug(`[proxy] background log cleanup exited with code ${code}`);
+            }
+        });
+        return true;
+    };
+    const initialTimer = setTimeout(trigger, params.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS);
+    initialTimer.unref();
+    const interval = setInterval(trigger, params.intervalMs ?? DEFAULT_INTERVAL_MS);
+    interval.unref();
+    return {
+        trigger,
+        stop: async () => {
+            stopped = true;
+            clearTimeout(initialTimer);
+            clearInterval(interval);
+            const worker = activeWorker;
+            activeWorker = undefined;
+            if (worker) {
+                try {
+                    await withTimeout(worker.terminate(), WORKER_TERMINATION_TIMEOUT_MS, "Timed out terminating the proxy log cleanup worker");
+                }
+                catch (error) {
+                    logger.debug(`[proxy] background log cleanup termination failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        },
+    };
+}

package/dist/proxy/logCleanupWorkerEntry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/proxy/logCleanupWorkerEntry.js

@@ -0,0 +1,14 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { cleanupLogsAt } from "./requestLogger.js";
+const data = workerData;
+try {
+    cleanupLogsAt(data.logsDir, data.maxAgeDays, data.maxSizeMb);
+    parentPort?.postMessage({ ok: true });
+}
+catch (error) {
+    parentPort?.postMessage({
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+    });
+    process.exitCode = 1;
+}

package/dist/proxy/proxyAnalysis.js

@@ -737,6 +737,10 @@ export async function analyzeProxyLogs(options) {
     const artifactsReferenced = artifactsPresent + artifactsMissing;
     const finalSummary = summarizeFinalRequests(finalRequests, terminalStreamErrors, attemptsByRequest, accounts);
     const routingSummary = summarizeRouting(finalRequests);
+    const streamComplete = (stream) => {
+        const range = observedRanges[stream];
+        return range.from !== null && range.from <= sinceMs;
+    };
     return {
         generatedAt: new Date(nowMs).toISOString(),
         since: new Date(sinceMs).toISOString(),
@@ -755,6 +759,7 @@ export async function analyzeProxyLogs(options) {
             attemptLatency: attemptLatency.length > 0,
             cacheUsage: finalSummary.cache.requestsWithUsage > 0,
             routingDecisions: routingSummary.totalRecords > 0,
+            comparableRequestAttempts: streamComplete("requests") && streamComplete("attempts"),
         },
         dataQuality: {
             linesRead,
@@ -768,6 +773,7 @@ export async function analyzeProxyLogs(options) {
                     observedFrom: range.from === null ? null : new Date(range.from).toISOString(),
                     observedTo: range.to === null ? null : new Date(range.to).toISOString(),
                     startsAtOrBeforeRequestedWindow: range.from !== null && range.from <= sinceMs,
+                    completeWindow: range.from !== null && range.from <= sinceMs,
                 },
             ])),
             bodyArtifacts: {

package/dist/proxy/requestLogger.d.ts

@@ -70,3 +70,9 @@ export declare function logStreamError(entry: {
  * Non-fatal — proxy keeps working even if cleanup fails.
  */
 export declare function cleanupLogs(maxAgeDays?: number, maxSizeMb?: number): void;
+/**
+ * Path-scoped retention implementation used by the proxy cleanup worker.
+ * This function is intentionally synchronous: callers must run it outside the
+ * request-serving process when the directory can contain many artifacts.
+ */
+export declare function cleanupLogsAt(activeLogDir: string, maxAgeDays?: number, maxSizeMb?: number): void;

package/dist/proxy/requestLogger.js

@@ -700,60 +700,70 @@ export async function logStreamError(entry) {
  * Non-fatal — proxy keeps working even if cleanup fails.
  */
 export function cleanupLogs(maxAgeDays = 7, maxSizeMb = 500) {
-    if (!logDir || !existsSync(logDir)) {
+    if (!logDir) {
         return;
     }
     try {
-        const activeLogDir = logDir;
-        const files = collectManagedLogFiles(activeLogDir).sort((a, b) => a.mtime - b.mtime); // oldest first
-        const currentDate = new Date().toISOString().split("T")[0];
-        const currentMetadataLogs = new Set(["proxy", "proxy-attempts", "proxy-debug", "proxy-lifecycle"].map((prefix) => join(activeLogDir, `${prefix}-${currentDate}.jsonl`)));
-        const canDelete = (file) => !currentMetadataLogs.has(file.path);
-        const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
-        let deletedCount = 0;
-        let freedBytes = 0;
-        // Pass 1: delete files older than maxAgeDays
-        const remaining = [];
-        for (const file of files) {
-            if (file.mtime < cutoff && canDelete(file)) {
-                unlinkSync(file.path);
-                deletedCount++;
-                freedBytes += file.size;
-            }
-            else {
-                remaining.push(file);
-            }
-        }
-        const bodiesDir = join(logDir, "bodies");
-        if (existsSync(bodiesDir)) {
-            pruneEmptyDirectories(bodiesDir, bodiesDir);
-        }
-        // Pass 2: if total size exceeds maxSizeMb, delete oldest until under limit
-        const maxBytes = maxSizeMb * 1024 * 1024;
-        let totalSize = remaining.reduce((sum, f) => sum + f.size, 0);
-        const deletionCandidates = remaining.filter(canDelete);
-        // Current-day metadata is the only reliable source for final-request,
-        // attempt, lifecycle, and body-index reconciliation. Keep those indexes
-        // intact during size cleanup; body artifacts and older indexes remain
-        // eligible for eviction.
-        while (totalSize > maxBytes && deletionCandidates.length > 0) {
-            const oldest = deletionCandidates.shift();
-            if (!oldest) {
-                break;
-            }
-            unlinkSync(oldest.path);
-            totalSize -= oldest.size;
+        cleanupLogsAt(logDir, maxAgeDays, maxSizeMb);
+    }
+    catch {
+        // Non-fatal for legacy in-process callers.
+    }
+}
+/**
+ * Path-scoped retention implementation used by the proxy cleanup worker.
+ * This function is intentionally synchronous: callers must run it outside the
+ * request-serving process when the directory can contain many artifacts.
+ */
+export function cleanupLogsAt(activeLogDir, maxAgeDays = 7, maxSizeMb = 500) {
+    if (!existsSync(activeLogDir)) {
+        return;
+    }
+    const files = collectManagedLogFiles(activeLogDir).sort((a, b) => a.mtime - b.mtime); // oldest first
+    const currentDate = new Date().toISOString().split("T")[0];
+    const currentMetadataLogs = new Set(["proxy", "proxy-attempts", "proxy-debug", "proxy-lifecycle"].map((prefix) => join(activeLogDir, `${prefix}-${currentDate}.jsonl`)));
+    const canDelete = (file) => !currentMetadataLogs.has(file.path);
+    const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+    let deletedCount = 0;
+    let freedBytes = 0;
+    // Pass 1: delete files older than maxAgeDays
+    const remaining = [];
+    for (const file of files) {
+        if (file.mtime < cutoff && canDelete(file)) {
+            unlinkSync(file.path);
             deletedCount++;
-            freedBytes += oldest.size;
+            freedBytes += file.size;
         }
-        if (existsSync(bodiesDir)) {
-            pruneEmptyDirectories(bodiesDir, bodiesDir);
+        else {
+            remaining.push(file);
         }
-        if (deletedCount > 0) {
-            logger.info(`[proxy] log cleanup: deleted ${deletedCount} file(s), freed ${(freedBytes / 1024 / 1024).toFixed(1)} MB`);
+    }
+    const bodiesDir = join(activeLogDir, "bodies");
+    if (existsSync(bodiesDir)) {
+        pruneEmptyDirectories(bodiesDir, bodiesDir);
+    }
+    // Pass 2: if total size exceeds maxSizeMb, delete oldest until under limit
+    const maxBytes = maxSizeMb * 1024 * 1024;
+    let totalSize = remaining.reduce((sum, f) => sum + f.size, 0);
+    const deletionCandidates = remaining.filter(canDelete);
+    // Current-day metadata is the only reliable source for final-request,
+    // attempt, lifecycle, and body-index reconciliation. Keep those indexes
+    // intact during size cleanup; body artifacts and older indexes remain
+    // eligible for eviction.
+    while (totalSize > maxBytes && deletionCandidates.length > 0) {
+        const oldest = deletionCandidates.shift();
+        if (!oldest) {
+            break;
         }
+        unlinkSync(oldest.path);
+        totalSize -= oldest.size;
+        deletedCount++;
+        freedBytes += oldest.size;
     }
-    catch {
-        // Non-fatal
+    if (existsSync(bodiesDir)) {
+        pruneEmptyDirectories(bodiesDir, bodiesDir);
+    }
+    if (deletedCount > 0) {
+        logger.info(`[proxy] log cleanup: deleted ${deletedCount} file(s), freed ${(freedBytes / 1024 / 1024).toFixed(1)} MB`);
     }
 }

package/dist/proxy/rollingWorkerSupervisor.d.ts

@@ -14,6 +14,7 @@ export declare class RollingWorkerSupervisor {
     private replacement;
     private rejectedSockets;
     private failedTransfers;
+    private readonly recentEvents;
     private lastFailure;
     private closed;
     private shutdownPromise;
@@ -38,5 +39,6 @@ export declare class RollingWorkerSupervisor {
     private describeTransferError;
     private extractLifecycleFailureDetails;
     private recordFailure;
+    private recordEvent;
     private publishState;
 }

package/dist/proxy/rollingWorkerSupervisor.js

@@ -3,6 +3,7 @@ const DEFAULT_READY_TIMEOUT_MS = 30_000;
 const DEFAULT_SOCKET_QUEUE_LIMIT = 1_024;
 const DEFAULT_SOCKET_QUEUE_TIMEOUT_MS = 30_000;
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
+const MAX_RECENT_SUPERVISOR_EVENTS = 100;
 /**
  * Owns worker generations while the caller owns the public listening socket.
  * Sockets are transferred once to the active worker, so response bytes never
@@ -18,6 +19,7 @@ export class RollingWorkerSupervisor {
     replacement = null;
     rejectedSockets = 0;
     failedTransfers = 0;
+    recentEvents = [];
     lastFailure = null;
     closed = false;
     shutdownPromise = null;
@@ -56,6 +58,7 @@ export class RollingWorkerSupervisor {
             queuedSockets: this.queuedSockets.length,
             rejectedSockets: this.rejectedSockets,
             failedTransfers: this.failedTransfers,
+            recentEvents: [...this.recentEvents],
             lastFailure: this.lastFailure,
         };
     }
@@ -302,6 +305,11 @@ export class RollingWorkerSupervisor {
                     this.maybeDrainWorker(previous);
                 }
                 this.options.log?.(`[proxy-supervisor] activated generation=${generation} pid=${handle.pid} version=${expectedVersion}`);
+                this.recordEvent({
+                    type: "activated",
+                    generation,
+                    version: expectedVersion,
+                });
                 this.publishState();
                 finish();
             });
@@ -410,6 +418,13 @@ export class RollingWorkerSupervisor {
     handleTransferFailure(worker, socket, error) {
         this.failedTransfers += 1;
         const detail = this.describeTransferError(error);
+        this.recordEvent({
+            type: "failed_transfer",
+            generation: worker.generation,
+            version: worker.version,
+            phase: "transfer",
+            reason: detail,
+        });
         const lifecycle = this.extractLifecycleFailureDetails(error, worker.handle.pid);
         this.recordFailure(worker.generation, worker.version, "transfer", `worker ${worker.handle.pid} failed to accept a transferred socket: ${detail}`, {
             ...lifecycle.details,
@@ -432,10 +447,16 @@ export class RollingWorkerSupervisor {
             }
             this.publishState();
         }
-        this.rejectSocket(socket);
+        this.rejectSocket(socket, worker.generation, worker.version, "transfer_failure");
     }
-    rejectSocket(socket) {
+    rejectSocket(socket, generation = this.active?.generation ?? null, version = this.active?.version ?? null, reason = "unavailable") {
         this.rejectedSockets += 1;
+        this.recordEvent({
+            type: "rejected_socket",
+            generation,
+            version,
+            reason,
+        });
         socket.destroy();
         this.publishState();
     }
@@ -479,6 +500,23 @@ export class RollingWorkerSupervisor {
             message: message.slice(0, 1_000),
             ...details,
         };
+        this.recordEvent({
+            type: "failure",
+            generation,
+            version,
+            phase,
+            reason: message,
+        });
+    }
+    recordEvent(event) {
+        this.recentEvents.push({
+            at: new Date().toISOString(),
+            ...event,
+            ...(event.reason ? { reason: event.reason.slice(0, 1_000) } : {}),
+        });
+        if (this.recentEvents.length > MAX_RECENT_SUPERVISOR_EVENTS) {
+            this.recentEvents.splice(0, this.recentEvents.length - MAX_RECENT_SUPERVISOR_EVENTS);
+        }
     }
     publishState() {
         try {

package/dist/server/routes/claudeProxyRoutes.d.ts

@@ -310,6 +310,7 @@ declare function shouldAttemptClaudeFallback(loopState: AnthropicLoopState): boo
 export declare function createClaudeProxyRoutes(modelRouter?: ModelRouterInterface, basePath?: string, accountStrategy?: "round-robin" | "fill-first", passthroughMode?: boolean, primaryAccountKey?: string, accountAllowlistOrRuntimeOptions?: AccountAllowlist | ClaudeProxyRouteRuntimeOptions): RouteGroup;
 declare function reconcileEligibleAccountRuntimeState(account: ProxyPassthroughAccount): void;
 export declare function getTransientSameAccountRetryDelayMs(retryNumber: number): number;
+export declare function getOverloadRotationDelayMs(attemptNumber: number): number;
 declare function describeTransportError(error: unknown): string;
 /**
  * Determine whether a POST can be retried without risking duplicate provider
@@ -400,6 +401,7 @@ export declare const __testHooks: {
     describeTransportError: typeof describeTransportError;
     redactProviderErrorMessage: typeof redactProviderErrorMessage;
     isUpstreamOverload: typeof isUpstreamOverload;
+    getOverloadRotationDelayMs: typeof getOverloadRotationDelayMs;
     shouldAttemptClaudeFallback: typeof shouldAttemptClaudeFallback;
     executeClaudeFallbackWithRetry: typeof executeClaudeFallbackWithRetry;
     buildClaudeAnthropicFailureResponse: typeof buildClaudeAnthropicFailureResponse;