@juspay/neurolink 10.4.1 → 10.4.3

package/dist/lib/proxy/proxyAnalysis.js

@@ -1,17 +1,41 @@
 import { createReadStream } from "node:fs";
-import { readdir } from "node:fs/promises";
+import { lstat, readdir, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 const LIFECYCLE_FILE_PATTERN = /^proxy-lifecycle-\d{4}-\d{2}-\d{2}\.jsonl$/;
 const REQUEST_FILE_PATTERN = /^proxy-\d{4}-\d{2}-\d{2}\.jsonl$/;
 const ATTEMPT_FILE_PATTERN = /^proxy-attempts-\d{4}-\d{2}-\d{2}\.jsonl$/;
+const DEBUG_FILE_PATTERN = /^proxy-debug-\d{4}-\d{2}-\d{2}\.jsonl$/;
+const ARTIFACT_STAT_CONCURRENCY = 64;
 const LIFECYCLE_EVENTS = new Set([
     "request_accepted",
     "response_headers",
     "response_first_chunk",
     "request_terminal",
 ]);
+function isContainedPath(root, candidate) {
+    const candidateRelative = relative(root, candidate);
+    return (candidateRelative.length > 0 &&
+        !isAbsolute(candidateRelative) &&
+        candidateRelative !== ".." &&
+        !candidateRelative.startsWith(`..${sep}`));
+}
+async function inspectBodyArtifact(artifactPath, canonicalBodiesRoot) {
+    if (!canonicalBodiesRoot) {
+        return "missing";
+    }
+    try {
+        const canonicalArtifactPath = await realpath(artifactPath);
+        if (!isContainedPath(canonicalBodiesRoot, canonicalArtifactPath)) {
+            return "invalid";
+        }
+        return (await stat(canonicalArtifactPath)).isFile() ? "present" : "missing";
+    }
+    catch {
+        return "missing";
+    }
+}
 function increment(counter, key) {
     counter[key] = (counter[key] ?? 0) + 1;
 }
@@ -192,6 +216,7 @@ async function discoverLogFiles(logsDir) {
         lifecycleFiles: matching(LIFECYCLE_FILE_PATTERN),
         requestFiles: matching(REQUEST_FILE_PATTERN),
         attemptFiles: matching(ATTEMPT_FILE_PATTERN),
+        debugFiles: matching(DEBUG_FILE_PATTERN),
     };
 }
 /** Analyze local proxy logs without reading request or response body artifacts. */
@@ -199,7 +224,24 @@ export async function analyzeProxyLogs(options) {
     const nowMs = options?.nowMs ?? Date.now();
     const sinceMs = parseSince(options?.since ?? "24h", nowMs);
     const logsDir = resolve(options?.logsDir ?? join(homedir(), ".neurolink", "logs"));
-    const { lifecycleFiles, requestFiles, attemptFiles } = await discoverLogFiles(logsDir);
+    const { lifecycleFiles, requestFiles, attemptFiles, debugFiles } = await discoverLogFiles(logsDir);
+    const observedRanges = {
+        lifecycle: { from: null, to: null },
+        requests: { from: null, to: null },
+        attempts: { from: null, to: null },
+        debug: { from: null, to: null },
+    };
+    const observeTimestamp = (stream, record) => {
+        const timestamp = Date.parse(String(record.timestamp ?? ""));
+        if (!Number.isFinite(timestamp)) {
+            return null;
+        }
+        const range = observedRanges[stream];
+        range.from =
+            range.from === null ? timestamp : Math.min(range.from, timestamp);
+        range.to = range.to === null ? timestamp : Math.max(range.to, timestamp);
+        return timestamp;
+    };
     let linesRead = 0;
     let malformedLines = 0;
     let unsupportedLifecycleLines = 0;
@@ -216,8 +258,8 @@ export async function analyzeProxyLogs(options) {
     const sequences = new Map();
     for (const filePath of lifecycleFiles) {
         linesRead += await readJsonLines(filePath, (record) => {
-            const timestamp = Date.parse(String(record.timestamp ?? ""));
-            if (!Number.isFinite(timestamp) || timestamp < sinceMs) {
+            const timestamp = observeTimestamp("lifecycle", record);
+            if (timestamp === null || timestamp < sinceMs) {
                 return;
             }
             const event = stringValue(record.event);
@@ -298,8 +340,8 @@ export async function analyzeProxyLogs(options) {
     let unclassifiedRateLimits = 0;
     for (const filePath of attemptFiles) {
         linesRead += await readJsonLines(filePath, (record) => {
-            const timestamp = Date.parse(String(record.timestamp ?? ""));
-            if (!Number.isFinite(timestamp) || timestamp < sinceMs) {
+            const timestamp = observeTimestamp("attempts", record);
+            if (timestamp === null || timestamp < sinceMs) {
                 return;
             }
             const requestId = stringValue(record.requestId);
@@ -360,8 +402,8 @@ export async function analyzeProxyLogs(options) {
     const terminalStreamErrors = new Set();
     for (const filePath of requestFiles) {
         linesRead += await readJsonLines(filePath, (record) => {
-            const timestamp = Date.parse(String(record.timestamp ?? ""));
-            if (!Number.isFinite(timestamp) || timestamp < sinceMs) {
+            const timestamp = observeTimestamp("requests", record);
+            if (timestamp === null || timestamp < sinceMs) {
                 return;
             }
             const requestId = stringValue(record.requestId);
@@ -391,6 +433,70 @@ export async function analyzeProxyLogs(options) {
             malformedLines += 1;
         });
     }
+    let capturesIndexed = 0;
+    let truncatedCaptures = 0;
+    let writeFailures = 0;
+    let invalidPaths = 0;
+    const referencedArtifacts = new Set();
+    const bodiesRoot = resolve(logsDir, "bodies");
+    for (const filePath of debugFiles) {
+        linesRead += await readJsonLines(filePath, (record) => {
+            const timestamp = observeTimestamp("debug", record);
+            if (timestamp === null || timestamp < sinceMs) {
+                return;
+            }
+            if (record.type !== "body_capture") {
+                return;
+            }
+            capturesIndexed += 1;
+            truncatedCaptures += record.bodyTruncated === true ? 1 : 0;
+            writeFailures += record.bodyWriteFailed === true ? 1 : 0;
+            const bodyPath = stringValue(record.bodyPath);
+            if (!bodyPath) {
+                return;
+            }
+            if (bodyPath.includes("\0") || bodyPath.split(/[\\/]/).includes("..")) {
+                invalidPaths += 1;
+                return;
+            }
+            const resolvedBodyPath = resolve(logsDir, bodyPath);
+            if (!isContainedPath(bodiesRoot, resolvedBodyPath)) {
+                invalidPaths += 1;
+                return;
+            }
+            referencedArtifacts.add(resolvedBodyPath);
+        }, () => {
+            malformedLines += 1;
+        });
+    }
+    const artifactPaths = [...referencedArtifacts];
+    let canonicalBodiesRoot = null;
+    let bodiesRootUnsafe = false;
+    try {
+        const bodiesRootStat = await lstat(bodiesRoot);
+        if (bodiesRootStat.isDirectory() && !bodiesRootStat.isSymbolicLink()) {
+            canonicalBodiesRoot = await realpath(bodiesRoot);
+        }
+        else {
+            bodiesRootUnsafe = true;
+        }
+    }
+    catch {
+        // A missing body directory means every lexically valid reference is absent.
+    }
+    let artifactsPresent = 0;
+    let artifactsMissing = 0;
+    for (let offset = 0; offset < artifactPaths.length; offset += ARTIFACT_STAT_CONCURRENCY) {
+        const presence = await Promise.all(artifactPaths
+            .slice(offset, offset + ARTIFACT_STAT_CONCURRENCY)
+            .map((artifactPath) => bodiesRootUnsafe
+            ? Promise.resolve("invalid")
+            : inspectBodyArtifact(artifactPath, canonicalBodiesRoot)));
+        artifactsPresent += presence.filter((value) => value === "present").length;
+        artifactsMissing += presence.filter((value) => value === "missing").length;
+        invalidPaths += presence.filter((value) => value === "invalid").length;
+    }
+    const artifactsReferenced = artifactsPresent + artifactsMissing;
     const finalSummary = summarizeFinalRequests(finalRequests, terminalStreamErrors, attemptsByRequest, accounts);
     return {
         generatedAt: new Date(nowMs).toISOString(),
@@ -400,11 +506,12 @@ export async function analyzeProxyLogs(options) {
             lifecycle: lifecycleFiles.length,
             requests: requestFiles.length,
             attempts: attemptFiles.length,
+            debug: debugFiles.length,
         },
         coverage: {
-            lifecycle: lifecycleFiles.length > 0,
-            finalRequests: requestFiles.length > 0,
-            attempts: attemptFiles.length > 0,
+            lifecycle: accepted.size + headers.size + firstChunks.size + terminal.size > 0,
+            finalRequests: finalRequests.size > 0 || terminalStreamErrors.size > 0,
+            attempts: totalAttempts > 0,
             attemptLatency: attemptLatency.length > 0,
             cacheUsage: finalSummary.cache.requestsWithUsage > 0,
         },
@@ -414,6 +521,23 @@ export async function analyzeProxyLogs(options) {
             unsupportedLifecycleLines,
             lifecycleSequenceGaps,
             lifecycleSequenceDuplicates,
+            streams: Object.fromEntries(Object.entries(observedRanges).map(([stream, range]) => [
+                stream,
+                {
+                    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,
+                },
+            ])),
+            bodyArtifacts: {
+                capturesIndexed,
+                artifactsReferenced,
+                artifactsPresent,
+                artifactsMissing,
+                invalidPaths,
+                writeFailures,
+                truncatedCaptures,
+            },
         },
         lifecycle: {
             accepted: accepted.size,

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

@@ -6,6 +6,8 @@
  * Useful for debugging and auditing proxy traffic.
  */
 import type { ProxyBodyCaptureEntry, RequestAttemptLogEntry, RequestLogEntry } from "../types/index.js";
+/** Wait, up to a bounded deadline, for admitted request/body writes to settle. */
+export declare function flushRequestLogs(timeoutMs?: number): Promise<void>;
 export declare function initRequestLogger(enabled?: boolean, customLogsDir?: string): void;
 export declare function logRequest(entry: RequestLogEntry): Promise<void>;
 /**

package/dist/lib/proxy/requestLogger.js

@@ -9,15 +9,49 @@ import { join } from "path";
 import { homedir } from "os";
 import { logger } from "../utils/logger.js";
 import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, unlinkSync, } from "fs";
-import { appendFile, writeFile } from "fs/promises";
+import { writeFile } from "fs/promises";
 import { createHash } from "crypto";
 import { promisify } from "util";
 import { gzip as gzipCallback } from "zlib";
 import { OtelBridge } from "../observability/otelBridge.js";
 import { SeverityNumber } from "@opentelemetry/api-logs";
 import { configureProxyLifecycleLogger } from "./proxyLifecycle.js";
+import { withTimeout } from "../utils/async/withTimeout.js";
 let logDir = null;
 let logEnabled = false;
+const pendingLogOperations = new Set();
+const REQUEST_LOG_IO_TIMEOUT_MS = 5_000;
+function trackLogOperation(operation) {
+    pendingLogOperations.add(operation);
+    void operation.then(() => pendingLogOperations.delete(operation), () => pendingLogOperations.delete(operation));
+    return operation;
+}
+/** Wait, up to a bounded deadline, for admitted request/body writes to settle. */
+export async function flushRequestLogs(timeoutMs = REQUEST_LOG_IO_TIMEOUT_MS) {
+    const deadline = Date.now() + Math.max(1, timeoutMs);
+    while (pendingLogOperations.size > 0) {
+        const admitted = [...pendingLogOperations];
+        const remainingMs = Math.max(1, deadline - Date.now());
+        try {
+            await withTimeout(Promise.allSettled(admitted), remainingMs, `Timed out flushing ${admitted.length} proxy request log operation(s)`);
+        }
+        catch (error) {
+            for (const operation of admitted) {
+                pendingLogOperations.delete(operation);
+            }
+            throw error;
+        }
+        if (Date.now() >= deadline && pendingLogOperations.size > 0) {
+            const remaining = pendingLogOperations.size;
+            throw new Error(`Timed out flushing ${remaining} proxy request log operation(s)`);
+        }
+    }
+}
+/** @internal Test-only hook for exercising shutdown behavior without real I/O. */
+export const __requestLoggerTestHooks = {
+    pendingOperationCount: () => pendingLogOperations.size,
+    trackLogOperation,
+};
 /**
  * Lazily-resolved LoggerProvider from OTel instrumentation.
  * null = not resolved yet (will retry), LoggerProvider = resolved, false = permanently unavailable.
@@ -86,7 +120,11 @@ export async function logRequest(entry) {
     const logFile = join(logDir, `proxy-${new Date().toISOString().split("T")[0]}.jsonl`);
     const line = JSON.stringify(entry) + "\n";
     try {
-        await appendFile(logFile, line, { mode: 0o600 });
+        await trackLogOperation(writeFile(logFile, line, {
+            mode: 0o600,
+            flag: "a",
+            signal: AbortSignal.timeout(REQUEST_LOG_IO_TIMEOUT_MS),
+        }));
     }
     catch {
         // Non-fatal — don't crash proxy for logging failures
@@ -114,7 +152,11 @@ export async function logRequestAttempt(entry) {
     const logFile = join(logDir, `proxy-attempts-${new Date().toISOString().split("T")[0]}.jsonl`);
     const line = JSON.stringify(entry) + "\n";
     try {
-        await appendFile(logFile, line, { mode: 0o600 });
+        await trackLogOperation(writeFile(logFile, line, {
+            mode: 0o600,
+            flag: "a",
+            signal: AbortSignal.timeout(REQUEST_LOG_IO_TIMEOUT_MS),
+        }));
     }
     catch {
         // Non-fatal — don't crash proxy for logging failures
@@ -353,7 +395,7 @@ function collectManagedLogFiles(rootDir) {
                 continue;
             }
             const isTopLevelProxyLog = directory === rootDir &&
-                /^proxy(?:-attempts|-debug)?-.*\.jsonl$/.test(entry.name);
+                /^proxy(?:-attempts|-debug|-lifecycle)?-.*\.jsonl$/.test(entry.name);
             const isBodyArtifact = entry.name.endsWith(".json.gz") &&
                 entryPath.includes(`${join(rootDir, "bodies")}`);
             if (!isTopLevelProxyLog && !isBodyArtifact) {
@@ -427,7 +469,10 @@ async function writeBodyArtifact(entry, redactedHeaders, redactedBody, bodyTrunc
         metadata: entry.metadata,
     });
     const compressed = await gzip(payload);
-    await writeFile(bodyPath, compressed, { mode: 0o600 });
+    await writeFile(bodyPath, compressed, {
+        mode: 0o600,
+        signal: AbortSignal.timeout(REQUEST_LOG_IO_TIMEOUT_MS),
+    });
     return {
         bodyPath,
         bodySha256: sha256(redactedBody),
@@ -510,7 +555,7 @@ export async function logBodyCapture(entry) {
     const preparedBody = prepareRedactedBody(entry.body);
     let stored;
     try {
-        stored = await writeBodyArtifact(entry, redactedHeaders, preparedBody.value, preparedBody.truncated);
+        stored = await trackLogOperation(writeBodyArtifact(entry, redactedHeaders, preparedBody.value, preparedBody.truncated));
     }
     catch (writeError) {
         logger.warn("[RequestLogger] writeBodyArtifact failed, falling back to in-memory body for OTLP", { error: writeError });
@@ -518,6 +563,7 @@ export async function logBodyCapture(entry) {
             redactedBody: preparedBody.value,
             redactedBodyBytes: preparedBody.bytes,
             bodyTruncated: preparedBody.truncated,
+            bodyWriteFailed: true,
         };
     }
     const dateStr = new Date(entry.timestamp).toISOString().split("T")[0];
@@ -542,6 +588,7 @@ export async function logBodyCapture(entry) {
         redactedBodyBytes: stored.redactedBodyBytes ?? preparedBody.bytes,
         storedFileBytes: stored.storedFileBytes,
         bodyTruncated: stored.bodyTruncated ?? preparedBody.truncated,
+        bodyWriteFailed: stored.bodyWriteFailed,
         metadata: entry.metadata,
     };
     if (traceCtx) {
@@ -549,9 +596,11 @@ export async function logBodyCapture(entry) {
         indexEntry.spanId = traceCtx.spanId;
     }
     try {
-        await appendFile(logFile, JSON.stringify(indexEntry) + "\n", {
+        await trackLogOperation(writeFile(logFile, JSON.stringify(indexEntry) + "\n", {
             mode: 0o600,
-        });
+            flag: "a",
+            signal: AbortSignal.timeout(REQUEST_LOG_IO_TIMEOUT_MS),
+        }));
     }
     catch {
         // Non-fatal
@@ -623,9 +672,11 @@ export async function logStreamError(entry) {
         logEntry.spanId = traceCtx.spanId;
     }
     try {
-        await appendFile(logFile, JSON.stringify(logEntry) + "\n", {
+        await trackLogOperation(writeFile(logFile, JSON.stringify(logEntry) + "\n", {
             mode: 0o600,
-        });
+            flag: "a",
+            signal: AbortSignal.timeout(REQUEST_LOG_IO_TIMEOUT_MS),
+        }));
     }
     catch {
         // Non-fatal — don't crash proxy for logging failures
@@ -644,13 +695,16 @@ export function cleanupLogs(maxAgeDays = 7, maxSizeMb = 500) {
     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) {
+            if (file.mtime < cutoff && canDelete(file)) {
                 unlinkSync(file.path);
                 deletedCount++;
                 freedBytes += file.size;
@@ -666,8 +720,13 @@ export function cleanupLogs(maxAgeDays = 7, maxSizeMb = 500) {
         // 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);
-        while (totalSize > maxBytes && remaining.length > 0) {
-            const oldest = remaining.shift();
+        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;
             }

package/dist/lib/proxy/rollingProxyServer.js

@@ -10,8 +10,28 @@ export async function startRollingProxyServer(options) {
     let listening = false;
     let recoveryFailures = 0;
     let recoveryTimer;
+    let requestedReplacementTimer;
+    let requestedReplacementSchedule = 0;
+    let requestedReplacementPending = false;
+    let replacementQueueTail = null;
     const recoveryDelayMs = Math.max(1, options.recoveryDelayMs ?? DEFAULT_RECOVERY_DELAY_MS);
     const maxRecoveryDelayMs = Math.max(recoveryDelayMs, options.maxRecoveryDelayMs ?? DEFAULT_MAX_RECOVERY_DELAY_MS);
+    const queueReplacement = (operation) => {
+        const predecessor = replacementQueueTail;
+        const result = (predecessor ?? Promise.resolve()).then(operation);
+        const completion = result.then(() => undefined, () => undefined);
+        replacementQueueTail = completion;
+        void completion.finally(() => {
+            if (replacementQueueTail !== completion) {
+                return;
+            }
+            replacementQueueTail = null;
+            if (requestedReplacementPending) {
+                scheduleRequestedReplacement();
+            }
+        });
+        return result;
+    };
     const scheduleRecovery = () => {
         if (closing || !listening || recoveryTimer) {
             return;
@@ -23,11 +43,13 @@ export async function startRollingProxyServer(options) {
             // An explicit replace() may have started (or completed) a generation
             // while this timer was pending. Re-validate before recovering so we never
             // launch a duplicate generation that conflicts with the requested worker.
-            const snapshot = supervisor.snapshot();
-            if (closing || snapshot.active || snapshot.candidate) {
-                return;
-            }
-            void supervisor.replace(desiredVersion).then(() => {
+            void queueReplacement(async () => {
+                const snapshot = supervisor.snapshot();
+                if (closing || snapshot.active || snapshot.candidate) {
+                    return;
+                }
+                await supervisor.replace(desiredVersion);
+            }).then(() => {
                 recoveryFailures = 0;
             }, (error) => {
                 recoveryFailures += 1;
@@ -48,6 +70,38 @@ export async function startRollingProxyServer(options) {
             scheduleRecovery();
         }
     };
+    function scheduleRequestedReplacement() {
+        if (closing) {
+            return;
+        }
+        requestedReplacementPending = true;
+        if (requestedReplacementTimer || replacementQueueTail) {
+            return;
+        }
+        const schedule = ++requestedReplacementSchedule;
+        requestedReplacementTimer = setTimeout(() => {
+            requestedReplacementTimer = undefined;
+            if (schedule !== requestedReplacementSchedule) {
+                return;
+            }
+            if (closing || !supervisor.snapshot().active) {
+                return;
+            }
+            requestedReplacementPending = false;
+            const replacementVersion = desiredVersion;
+            void queueReplacement(async () => {
+                if (closing || !supervisor.snapshot().active) {
+                    return;
+                }
+                options.log?.(`[proxy-supervisor] preparing same-version worker replacement version=${replacementVersion} reason=environment`);
+                await supervisor.replace(replacementVersion);
+                options.log?.(`[proxy-supervisor] same-version worker replacement complete version=${replacementVersion} reason=environment`);
+            }).catch((error) => {
+                options.log?.(`[proxy-supervisor] same-version worker replacement failed version=${replacementVersion} reason=environment: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }, 50);
+        requestedReplacementTimer.unref?.();
+    }
     const supervisor = new RollingWorkerSupervisor({
         spawnWorker: options.spawnWorker,
         readyTimeoutMs: options.readyTimeoutMs,
@@ -55,9 +109,14 @@ export async function startRollingProxyServer(options) {
         socketQueueTimeoutMs: options.socketQueueTimeoutMs,
         shutdownTimeoutMs: options.shutdownTimeoutMs,
         onStateChange: stateChanged,
+        onReplacementRequested: scheduleRequestedReplacement,
         log: options.log,
     });
     const listener = createServer({ pauseOnConnect: true }, (socket) => {
+        // The parent keeps its descriptor until the worker commits the IPC
+        // transfer. Consume client resets during that interval so they cannot
+        // terminate the long-lived supervisor process.
+        socket.once("error", () => socket.destroy());
         supervisor.acceptSocket(socket);
     });
     await new Promise((resolve, reject) => {
@@ -89,8 +148,8 @@ export async function startRollingProxyServer(options) {
     }
     const address = listener.address();
     if (!address || typeof address === "string") {
-        listener.close();
-        void supervisor.close();
+        await new Promise((resolve) => listener.close(() => resolve()));
+        await supervisor.close().catch(() => undefined);
         throw ErrorFactory.proxyWorkerLifecycle("rolling proxy listener did not expose a TCP address");
     }
     return {
@@ -111,8 +170,14 @@ export async function startRollingProxyServer(options) {
                 clearTimeout(recoveryTimer);
                 recoveryTimer = undefined;
             }
+            if (requestedReplacementTimer) {
+                clearTimeout(requestedReplacementTimer);
+                requestedReplacementTimer = undefined;
+            }
+            requestedReplacementSchedule += 1;
+            requestedReplacementPending = false;
             try {
-                const snapshot = await supervisor.replace(expectedVersion);
+                const snapshot = await queueReplacement(() => supervisor.replace(expectedVersion));
                 recoveryFailures = 0;
                 return snapshot;
             }
@@ -139,6 +204,12 @@ export async function startRollingProxyServer(options) {
                 clearTimeout(recoveryTimer);
                 recoveryTimer = undefined;
             }
+            if (requestedReplacementTimer) {
+                clearTimeout(requestedReplacementTimer);
+                requestedReplacementTimer = undefined;
+            }
+            requestedReplacementSchedule += 1;
+            requestedReplacementPending = false;
             const listenerClosed = new Promise((resolve, reject) => {
                 listener.close((error) => (error ? reject(error) : resolve()));
             });

package/dist/lib/proxy/rollingWorkerProcess.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { ErrorFactory } from "../utils/errorHandling.js";
 import { isProxyWorkerStatusMessage, PROXY_SOCKET_WORKER_ENV, } from "./rollingWorkerProtocol.js";
 export function spawnProxySocketWorker(options) {
-    const socketAckTimeoutMs = Math.max(1, options.socketAckTimeoutMs ?? 5_000);
+    const socketAckTimeoutMs = Math.max(1, options.socketAckTimeoutMs ?? 30_000);
     let nextSocketId = 0;
     const pendingSockets = new Map();
     const statusListeners = new Set();
@@ -59,6 +59,18 @@ export function spawnProxySocketWorker(options) {
         }
         pendingSockets.delete(socketId);
         clearTimeout(pending.timeout);
+        if (error && child.connected && !pending.accepted) {
+            try {
+                child.send({
+                    type: "proxy-worker:socket-cancel",
+                    generation: options.generation,
+                    socketId,
+                }, () => undefined);
+            }
+            catch {
+                // The supervisor will quarantine the worker after the failed transfer.
+            }
+        }
         if (!error) {
             pending.socket.destroy();
         }
@@ -92,9 +104,14 @@ export function spawnProxySocketWorker(options) {
             publishStatus(message);
         }
     });
-    child.once("exit", () => {
+    child.once("exit", (code, signal) => {
         for (const socketId of [...pendingSockets.keys()]) {
-            settleSocket(socketId, new Error(`proxy worker ${childPid} exited before accepting socket`));
+            settleSocket(socketId, ErrorFactory.proxyWorkerLifecycle(`proxy worker ${childPid} exited before socket transfer committed (code=${code ?? "none"}, signal=${signal ?? "none"})`, {
+                workerPid: childPid,
+                generation: options.generation,
+                exitCode: code,
+                signal,
+            }));
         }
     });
     const sendControl = (message) => {
@@ -117,18 +134,6 @@ export function spawnProxySocketWorker(options) {
             }
             const socketId = `${generation}:${++nextSocketId}`;
             const timeout = setTimeout(() => {
-                if (child.connected) {
-                    try {
-                        child.send({
-                            type: "proxy-worker:socket-cancel",
-                            generation,
-                            socketId,
-                        });
-                    }
-                    catch {
-                        // The worker is terminated after the failed transfer is reported.
-                    }
-                }
                 settleSocket(socketId, new Error(`proxy worker ${childPid} did not accept socket within ${socketAckTimeoutMs}ms`));
             }, socketAckTimeoutMs);
             timeout.unref?.();

package/dist/lib/proxy/rollingWorkerProtocol.js

@@ -38,6 +38,9 @@ export function isProxyWorkerStatusMessage(value) {
     if (message.type === "proxy-worker:socket-accepted") {
         return typeof message.socketId === "string" && message.socketId.length > 0;
     }
+    if (message.type === "proxy-worker:replacement-requested") {
+        return message.reason === "environment";
+    }
     return (message.type === "proxy-worker:fatal" && typeof message.message === "string");
 }
 //# sourceMappingURL=rollingWorkerProtocol.js.map

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

@@ -34,6 +34,7 @@ export declare class RollingWorkerSupervisor {
     private transferSocket;
     private handleTransferFailure;
     private rejectSocket;
+    private describeTransferError;
     private recordFailure;
     private publishState;
 }