@juspay/neurolink 12.12.9 → 12.12.10

package/dist/proxy/requestLogger.js

@@ -10,9 +10,9 @@ import { homedir } from "os";
 import { logger } from "../utils/logger.js";
 import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, unlinkSync, } from "fs";
 import { writeFile } from "fs/promises";
-import { createHash } from "crypto";
-import { promisify } from "util";
-import { gzip as gzipCallback } from "zlib";
+import { setImmediate as yieldToRequests } from "node:timers/promises";
+import { captureProxyBody, getBodyCaptureWorkerSnapshot, PROXY_BODY_CAPTURE_DEADLINE_MS, } from "./bodyCaptureWorker.js";
+import { prepareProxyBodyForLogging as prepareRedactedBody, redactProxyHeadersForLogging as redactHeaders, splitUtf8StringByBytes, } from "./bodyCaptureProcessing.js";
 import { isBorrowedRequest } from "./shareContext.js";
 import { OtelBridge } from "../observability/otelBridge.js";
 import { SeverityNumber } from "@opentelemetry/api-logs";
@@ -40,15 +40,22 @@ const metadataSinks = {
     attempts: createSinkSnapshot(),
     debug: createSinkSnapshot(),
 };
+/**
+ * Expose independent metadata-sink and body-capture counters for incident reconciliation.
+ */
 export function getRequestLoggerSnapshot() {
     return {
         enabled: logEnabled,
         requests: { ...metadataSinks.requests },
         attempts: { ...metadataSinks.attempts },
         debug: { ...metadataSinks.debug },
+        bodyCapture: getBodyCaptureWorkerSnapshot(),
     };
 }
-async function appendMetadataRecord(file, line, kind) {
+/**
+ * Serialize append ownership; capture callers retain their memory lease until the write settles.
+ */
+async function appendMetadataRecord(file, line, kind, options = {}) {
     const sink = metadataSinks[kind];
     sink.attempted += 1;
     if (sink.pending + sink.inFlight >= MAX_PENDING_METADATA_RECORDS) {
@@ -86,16 +93,25 @@ async function appendMetadataRecord(file, line, kind) {
             appendChains.delete(file);
         }
     });
+    if (options.waitForPersistence) {
+        // Bulk capture owns a memory lease until publication settles. A caller
+        // timeout must not release that lease while the serialized index is queued.
+        return operation;
+    }
     // Bound the caller's wait, not the lifetime/ownership of the underlying write.
     await withTimeout(operation, REQUEST_LOG_IO_TIMEOUT_MS, "Proxy metadata write remains pending").catch(() => undefined);
 }
+/**
+ * Retain asynchronous log ownership until settlement so shutdown can await admitted publication.
+ */
 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) {
+export async function flushRequestLogs(timeoutMs = PROXY_BODY_CAPTURE_DEADLINE_MS +
+    2 * REQUEST_LOG_IO_TIMEOUT_MS) {
     const deadline = Date.now() + Math.max(1, timeoutMs);
     while (pendingLogOperations.size > 0) {
         const admitted = [...pendingLogOperations];
@@ -127,24 +143,10 @@ let otelLoggerProvider = null;
 let otelResolveAttempts = 0;
 /** Max number of resolve attempts before giving up. */
 const MAX_RESOLVE_ATTEMPTS = 10;
-/** Maximum body chunk size emitted to OTLP logs. */
 const BODY_OTLP_CHUNK_SIZE = 16_000;
-/** Maximum redacted body bytes persisted per capture entry. */
-const MAX_CAPTURED_BODY_BYTES = 1024 * 1024;
-const BODY_TRUNCATION_MARKER = "\n...[TRUNCATED]";
-const gzip = promisify(gzipCallback);
-/** Headers whose values must always be redacted. */
-const SENSITIVE_HEADER_NAMES = new Set([
-    "authorization",
-    "proxy-authorization",
-    "x-api-key",
-    "cookie",
-    "set-cookie",
-]);
-/** Pattern that matches header names likely to contain secrets. */
-const SENSITIVE_HEADER_PATTERN = /token|secret|key|password|credential/i;
-/** JSON keys whose values should be redacted in request/response bodies. */
-const SENSITIVE_BODY_KEYS = /("(?:password|access_token|refresh_token|api_key|apiKey|secret|authorization|token|credential|x-api-key)"\s*:\s*)"(?:[^"\\]|\\.)*"/gi;
+/**
+ * Initialize private request logs and preserve required lifecycle admission on startup failures.
+ */
 export function initRequestLogger(enabled = true, customLogsDir) {
     // Lifecycle metadata deliberately shares the request logger's enablement,
     // directory permissions, retention boundary, and operator privacy control.
@@ -164,7 +166,10 @@ export function initRequestLogger(enabled = true, customLogsDir) {
     catch (err) {
         logEnabled = false;
         logDir = null;
-        configureProxyLifecycleLogger({ enabled: false });
+        configureProxyLifecycleLogger({
+            enabled: true,
+            logDir: customLogsDir ?? join(homedir(), ".neurolink", "logs"),
+        });
         logger.warn(`[proxy] Request logging disabled — failed to create log directory: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
@@ -352,119 +357,17 @@ export function getLogDir() {
 /**
  * Redact sensitive header values in-place.
  */
-function redactHeaders(headers) {
-    if (!headers) {
-        return headers;
-    }
-    const redacted = {};
-    for (const [key, value] of Object.entries(headers)) {
-        const lower = key.toLowerCase();
-        if (SENSITIVE_HEADER_NAMES.has(lower) ||
-            SENSITIVE_HEADER_PATTERN.test(lower)) {
-            redacted[key] = "[REDACTED]";
-        }
-        else {
-            redacted[key] = value;
-        }
-    }
-    return redacted;
-}
-function serializeBody(body) {
-    if (body === undefined || body === null) {
-        return undefined;
-    }
-    return typeof body === "string" ? body : JSON.stringify(body);
-}
-/**
- * Redact sensitive keys from a JSON body string without truncation.
- */
-function redactBody(body) {
-    const str = serializeBody(body);
-    if (str === undefined) {
-        return undefined;
-    }
-    return str.replace(SENSITIVE_BODY_KEYS, '$1"[REDACTED]"');
-}
-function sanitizePhase(phase) {
-    return phase.replace(/[^a-zA-Z0-9._-]+/g, "_");
-}
-function sha256(value) {
-    return createHash("sha256").update(value).digest("hex");
-}
-function utf8ByteLength(value) {
-    return Buffer.byteLength(value, "utf8");
-}
-function truncateUtf8String(input, maxBytes, marker = BODY_TRUNCATION_MARKER) {
-    const inputBytes = utf8ByteLength(input);
-    if (inputBytes <= maxBytes) {
-        return { value: input, bytes: inputBytes, truncated: false };
-    }
-    const markerBytes = utf8ByteLength(marker);
-    if (maxBytes <= markerBytes) {
-        return { value: marker, bytes: markerBytes, truncated: true };
-    }
-    let value = "";
-    let bytes = 0;
-    for (const char of input) {
-        const charBytes = utf8ByteLength(char);
-        if (bytes + charBytes + markerBytes > maxBytes) {
-            break;
-        }
-        value += char;
-        bytes += charBytes;
-    }
-    const truncatedValue = `${value}${marker}`;
-    return {
-        value: truncatedValue,
-        bytes: utf8ByteLength(truncatedValue),
-        truncated: true,
-    };
-}
-function splitUtf8StringByBytes(input, maxBytes) {
-    if (!input) {
-        return [""];
-    }
-    const chunks = [];
-    let currentChunk = "";
-    let currentBytes = 0;
-    for (const char of input) {
-        const charBytes = utf8ByteLength(char);
-        if (currentChunk && currentBytes + charBytes > maxBytes) {
-            chunks.push(currentChunk);
-            currentChunk = char;
-            currentBytes = charBytes;
-            continue;
-        }
-        currentChunk += char;
-        currentBytes += charBytes;
-    }
-    if (currentChunk) {
-        chunks.push(currentChunk);
-    }
-    return chunks;
-}
-function prepareRedactedBody(body) {
-    const redacted = redactBody(body);
-    if (redacted === undefined) {
-        return { truncated: false };
-    }
-    return truncateUtf8String(redacted, MAX_CAPTURED_BODY_BYTES);
-}
-/** Shared redaction used by offline replay exports and direct comparisons. */
 export function redactProxyHeadersForLogging(headers) {
     return redactHeaders(headers);
 }
-/**
- * Apply the same bounded body redaction used by persisted proxy captures.
- * `value` and `bytes` are omitted only when the input is null or undefined.
- * This performs serialization immediately, so callers must keep it off proxy
- * hot paths unless body processing has already been explicitly requested.
- */
+/** Return a redacted body representation suitable for persisted request diagnostics. */
 export function prepareProxyBodyForLogging(body) {
     return prepareRedactedBody(body);
 }
+/** Enumerate recognized proxy journals and body artifacts for retention accounting. */
 function collectManagedLogFiles(rootDir) {
     const managedFiles = [];
+    /** Collect file sizes and modification times while descending the log directory. */
     const walk = (directory) => {
         for (const entry of readdirSync(directory, { withFileTypes: true })) {
             const entryPath = join(directory, entry.name);
@@ -473,7 +376,7 @@ function collectManagedLogFiles(rootDir) {
                 continue;
             }
             const isTopLevelProxyLog = directory === rootDir &&
-                /^proxy(?:-attempts|-debug|-lifecycle)?-.*\.jsonl$/.test(entry.name);
+                /^proxy(?:-attempts|-debug|-lifecycle|-supervisor)?-.*\.jsonl$/.test(entry.name);
             const isBodyArtifact = entry.name.endsWith(".json.gz") &&
                 entryPath.includes(`${join(rootDir, "bodies")}`);
             if (!isTopLevelProxyLog && !isBodyArtifact) {
@@ -514,55 +417,10 @@ function pruneEmptyDirectories(directory, stopAt) {
         // Non-fatal
     }
 }
-async function writeBodyArtifact(entry, redactedHeaders, redactedBody, bodyTruncated) {
-    if (!logDir || redactedBody === undefined) {
-        return {};
-    }
-    const dateStr = new Date(entry.timestamp).toISOString().split("T")[0];
-    const bodyDir = join(logDir, "bodies", dateStr, entry.requestId);
-    if (!existsSync(bodyDir)) {
-        mkdirSync(bodyDir, { recursive: true, mode: 0o700 });
-    }
-    chmodSync(bodyDir, 0o700);
-    const fileName = `${Date.now()}-${sanitizePhase(entry.phase)}` +
-        (entry.attempt !== undefined ? `-attempt-${entry.attempt}` : "") +
-        `.json.gz`;
-    const bodyPath = join(bodyDir, fileName);
-    const payload = JSON.stringify({
-        timestamp: entry.timestamp,
-        requestId: entry.requestId,
-        phase: entry.phase,
-        model: entry.model,
-        stream: entry.stream,
-        account: entry.account,
-        accountType: entry.accountType,
-        attempt: entry.attempt,
-        responseStatus: entry.responseStatus,
-        durationMs: entry.durationMs,
-        contentType: entry.contentType,
-        headers: redactedHeaders,
-        body: redactedBody,
-        traceId: entry.traceId,
-        spanId: entry.spanId,
-        metadata: entry.metadata,
-    });
-    const compressed = await gzip(payload);
-    await writeFile(bodyPath, compressed, {
-        mode: 0o600,
-        signal: AbortSignal.timeout(REQUEST_LOG_IO_TIMEOUT_MS),
-    });
-    return {
-        bodyPath,
-        bodySha256: sha256(redactedBody),
-        redactedBodyBytes: utf8ByteLength(redactedBody),
-        storedFileBytes: compressed.byteLength,
-        redactedBody,
-        bodyTruncated,
-    };
-}
+/** Publish redacted UTF-8 chunks, yielding between groups to keep requests responsive. */
 function emitOtlpBodyLogRecord(entry, stored) {
-    resolveLoggerProvider()
-        .then((provider) => {
+    return resolveLoggerProvider()
+        .then(async (provider) => {
         if (!provider || stored.redactedBody === undefined) {
             return;
         }
@@ -570,6 +428,9 @@ function emitOtlpBodyLogRecord(entry, stored) {
         const chunks = splitUtf8StringByBytes(stored.redactedBody, BODY_OTLP_CHUNK_SIZE);
         const totalChunks = Math.max(1, chunks.length);
         for (let chunkIndex = 0; chunkIndex < totalChunks; chunkIndex++) {
+            if (chunkIndex > 0 && chunkIndex % 4 === 0) {
+                await yieldToRequests();
+            }
             const chunk = chunks[chunkIndex] ?? "";
             otelLogger.emit({
                 severityNumber: (entry.responseStatus ?? 0) >= 400
@@ -621,6 +482,7 @@ function emitOtlpBodyLogRecord(entry, stored) {
         // Non-fatal — never crash proxy for OTLP log failures
     });
 }
+/** Capture an owned request body with bounded processing and tracked index/export publication. */
 export async function logBodyCapture(entry) {
     if (!logEnabled || !logDir) {
         return;
@@ -636,61 +498,61 @@ export async function logBodyCapture(entry) {
     const traceCtx = entry.traceId && entry.spanId
         ? { traceId: entry.traceId, spanId: entry.spanId }
         : bridge.getCurrentTraceContext();
-    const redactedHeaders = redactHeaders(entry.headers);
-    const preparedBody = prepareRedactedBody(entry.body);
-    let stored;
-    try {
-        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 });
-        stored = {
-            redactedBody: preparedBody.value,
-            redactedBodyBytes: preparedBody.bytes,
-            bodyTruncated: preparedBody.truncated,
-            bodyWriteFailed: true,
+    const destination = logDir;
+    // Publication callbacks retain metadata and the bounded redacted result,
+    // never the original unbounded body while a sink is slow.
+    const metadata = { ...entry, body: undefined };
+    /** Persist the processed capture index and publish its redacted body before releasing capacity. */
+    const consume = async (processed) => {
+        const redactedHeaders = processed.headers;
+        const stored = processed.stored;
+        const dateStr = new Date(metadata.timestamp).toISOString().split("T")[0];
+        const logFile = join(destination, `proxy-debug-${dateStr}.jsonl`);
+        const indexEntry = {
+            timestamp: metadata.timestamp,
+            type: "body_capture",
+            requestId: metadata.requestId,
+            phase: metadata.phase,
+            model: metadata.model,
+            stream: metadata.stream,
+            headers: redactedHeaders,
+            contentType: metadata.contentType,
+            responseStatus: metadata.responseStatus,
+            durationMs: metadata.durationMs,
+            account: metadata.account,
+            accountType: metadata.accountType,
+            attempt: metadata.attempt,
+            bodyPath: stored.bodyPath,
+            bodySha256: stored.bodySha256,
+            observedBodyBytes: metadata.bodySize,
+            redactedBodyBytes: stored.redactedBodyBytes,
+            storedFileBytes: stored.storedFileBytes,
+            bodyTruncated: stored.bodyTruncated,
+            bodyWriteFailed: stored.bodyWriteFailed,
+            captureError: processed.error,
+            captureQueueWaitMs: processed.queueWaitMs,
+            captureProcessingMs: processed.processingMs,
+            metadata: processed.error ? undefined : metadata.metadata,
         };
-    }
-    const dateStr = new Date(entry.timestamp).toISOString().split("T")[0];
-    const logFile = join(logDir, `proxy-debug-${dateStr}.jsonl`);
-    const indexEntry = {
-        timestamp: entry.timestamp,
-        type: "body_capture",
-        requestId: entry.requestId,
-        phase: entry.phase,
-        model: entry.model,
-        stream: entry.stream,
-        headers: redactedHeaders,
-        contentType: entry.contentType,
-        responseStatus: entry.responseStatus,
-        durationMs: entry.durationMs,
-        account: entry.account,
-        accountType: entry.accountType,
-        attempt: entry.attempt,
-        bodyPath: stored.bodyPath,
-        bodySha256: stored.bodySha256,
-        observedBodyBytes: entry.bodySize,
-        redactedBodyBytes: stored.redactedBodyBytes ?? preparedBody.bytes,
-        storedFileBytes: stored.storedFileBytes,
-        bodyTruncated: stored.bodyTruncated ?? preparedBody.truncated,
-        bodyWriteFailed: stored.bodyWriteFailed,
-        metadata: entry.metadata,
+        if (traceCtx) {
+            indexEntry.traceId = traceCtx.traceId;
+            indexEntry.spanId = traceCtx.spanId;
+        }
+        try {
+            await appendMetadataRecord(logFile, JSON.stringify(indexEntry) + "\n", "debug", { waitForPersistence: true });
+        }
+        catch {
+            // Non-fatal
+        }
+        // Emission yields between chunk groups. Keep it in the shutdown flush set
+        // so an exporter flush cannot race unfinished body-log publication.
+        await emitOtlpBodyLogRecord({
+            ...metadata,
+            traceId: traceCtx?.traceId ?? metadata.traceId,
+            spanId: traceCtx?.spanId ?? metadata.spanId,
+        }, stored);
     };
-    if (traceCtx) {
-        indexEntry.traceId = traceCtx.traceId;
-        indexEntry.spanId = traceCtx.spanId;
-    }
-    try {
-        await appendMetadataRecord(logFile, JSON.stringify(indexEntry) + "\n", "debug");
-    }
-    catch {
-        // Non-fatal
-    }
-    emitOtlpBodyLogRecord({
-        ...entry,
-        traceId: traceCtx?.traceId ?? entry.traceId,
-        spanId: traceCtx?.spanId ?? entry.spanId,
-    }, stored);
+    return trackLogOperation(captureProxyBody(entry, destination, consume));
 }
 /**
  * Log the FULL raw request and response for debugging.
@@ -787,7 +649,13 @@ export function cleanupLogsAt(activeLogDir, maxAgeDays = 7, maxSizeMb = 500) {
     }
     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 currentMetadataLogs = new Set([
+        "proxy",
+        "proxy-attempts",
+        "proxy-debug",
+        "proxy-lifecycle",
+        "proxy-supervisor",
+    ].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;

package/dist/proxy/rollingProxyServer.js

@@ -115,10 +115,14 @@ export async function startRollingProxyServer(options) {
         socketQueueTimeoutMs: options.socketQueueTimeoutMs,
         shutdownTimeoutMs: options.shutdownTimeoutMs,
         onStateChange: stateChanged,
+        onEvent: options.onEvent,
         onReplacementRequested: scheduleRequestedReplacement,
         log: options.log,
     });
+    const ownedSockets = new Set();
     const listener = createServer({ pauseOnConnect: true }, (socket) => {
+        ownedSockets.add(socket);
+        socket.once("close", () => ownedSockets.delete(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.
@@ -216,10 +220,17 @@ export async function startRollingProxyServer(options) {
             }
             requestedReplacementSchedule += 1;
             requestedReplacementPending = false;
-            const listenerClosed = new Promise((resolve, reject) => {
-                listener.close((error) => (error ? reject(error) : resolve()));
-            });
-            await Promise.all([listenerClosed, supervisor.close()]);
+            // Stop accepting immediately, then await the ownership we actually hold.
+            // Node's net.Server can retain _usingWorkers=true with an empty worker
+            // list after an IPC recipient exits. Its close callback then never fires,
+            // even though the listener and every descriptor have closed. Avoid that
+            // private bookkeeping path; the supervisor owns remote worker draining.
+            listener.close();
+            await supervisor.close();
+            await Promise.all([...ownedSockets].map((socket) => new Promise((resolve) => {
+                socket.once("close", resolve);
+                socket.destroy();
+            })));
         },
     };
 }

package/dist/proxy/rollingWorkerProcess.d.ts

@@ -1,2 +1,6 @@
 import type { RollingWorkerHandle, SpawnProxySocketWorkerOptions } from "../types/index.js";
+/**
+ * Spawn a generation-specific IPC worker with separate offer and commit
+ * ownership deadlines.
+ */
 export declare function spawnProxySocketWorker(options: SpawnProxySocketWorkerOptions): RollingWorkerHandle;

package/dist/proxy/rollingWorkerProcess.js

@@ -1,6 +1,10 @@
 import { spawn } from "node:child_process";
 import { ErrorFactory } from "../utils/errorHandling.js";
-import { isProxyWorkerStatusMessage, PROXY_SOCKET_WORKER_ENV, PROXY_SOCKET_OFFER_TIMEOUT, } from "./rollingWorkerProtocol.js";
+import { isProxyWorkerStatusMessage, PROXY_SOCKET_WORKER_ENV, PROXY_SOCKET_OFFER_TIMEOUT, PROXY_SOCKET_COMMIT_TIMEOUT, } from "./rollingWorkerProtocol.js";
+/**
+ * Spawn a generation-specific IPC worker with separate offer and commit
+ * ownership deadlines.
+ */
 export function spawnProxySocketWorker(options) {
     const socketAckTimeoutMs = Math.max(1, options.socketAckTimeoutMs ?? 30_000);
     let nextSocketId = 0;
@@ -8,7 +12,7 @@ export function spawnProxySocketWorker(options) {
     const statusListeners = new Set();
     const pendingStatusMessages = [];
     let spawnError;
-    const child = spawn(options.command, options.args, {
+    const child = (options.spawn ?? spawn)(options.command, options.args, {
         env: {
             ...process.env,
             ...options.env,
@@ -52,6 +56,10 @@ export function spawnProxySocketWorker(options) {
         child.kill("SIGTERM");
         throw ErrorFactory.proxyWorkerLifecycle("proxy worker spawn did not return a pid");
     }
+    /**
+     * Finish a handoff once and cancel its worker-side copy on uncertain
+     * delivery.
+     */
     const settleSocket = (socketId, error) => {
         const pending = pendingSockets.get(socketId);
         if (!pending) {
@@ -59,7 +67,7 @@ export function spawnProxySocketWorker(options) {
         }
         pendingSockets.delete(socketId);
         clearTimeout(pending.timeout);
-        if (error && child.connected && !pending.accepted) {
+        if (error && child.connected) {
             try {
                 child.send({
                     type: "proxy-worker:socket-cancel",
@@ -76,6 +84,10 @@ export function spawnProxySocketWorker(options) {
         }
         pending.callback(error);
     };
+    /**
+     * Accept messages only from this worker and start a fresh deadline for
+     * the commit phase.
+     */
     const onInternalMessage = (message) => {
         if (isProxyWorkerStatusMessage(message) &&
             message.type === "proxy-worker:socket-accepted" &&
@@ -86,6 +98,15 @@ export function spawnProxySocketWorker(options) {
                 return;
             }
             pending.accepted = true;
+            // Acceptance and commit are distinct phases. A late acceptance must not
+            // inherit an almost-expired offer timer and kill established streams.
+            clearTimeout(pending.timeout);
+            pending.timeout = setTimeout(() => {
+                const error = new Error(`proxy worker ${childPid} socket commit remained pending for ${socketAckTimeoutMs}ms`);
+                error.code = PROXY_SOCKET_COMMIT_TIMEOUT;
+                settleSocket(message.socketId, error);
+            }, socketAckTimeoutMs);
+            pending.timeout.unref?.();
             try {
                 child.send({
                     type: "proxy-worker:socket-commit",
@@ -135,11 +156,7 @@ export function spawnProxySocketWorker(options) {
             const socketId = `${generation}:${++nextSocketId}`;
             const timeout = setTimeout(() => {
                 const error = new Error(`proxy worker ${childPid} did not accept socket within ${socketAckTimeoutMs}ms`);
-                if (!pendingSockets.get(socketId)?.accepted) {
-                    // No commit was sent. The cancel message settles this offer without
-                    // terminating unrelated requests already owned by the worker.
-                    error.code = PROXY_SOCKET_OFFER_TIMEOUT;
-                }
+                error.code = PROXY_SOCKET_OFFER_TIMEOUT;
                 settleSocket(socketId, error);
             }, socketAckTimeoutMs);
             timeout.unref?.();

package/dist/proxy/rollingWorkerProtocol.d.ts

@@ -2,6 +2,12 @@ import type { ProxyWorkerControlMessage, ProxyWorkerStatusMessage } from "../typ
 export declare const PROXY_SOCKET_WORKER_ENV = "NEUROLINK_PROXY_SOCKET_WORKER";
 /** The worker has not been sent a commit and cannot have served this socket. */
 export declare const PROXY_SOCKET_OFFER_TIMEOUT = "PROXY_SOCKET_OFFER_TIMEOUT";
+/** Commit delivery is uncertain; close only this socket and never replay it. */
+export declare const PROXY_SOCKET_COMMIT_TIMEOUT = "PROXY_SOCKET_COMMIT_TIMEOUT";
 export declare const PROXY_ROLLING_SUPERVISOR_ENV = "NEUROLINK_PROXY_ROLLING_SUPERVISOR";
 export declare function isProxyWorkerControlMessage(value: unknown): value is ProxyWorkerControlMessage;
+/**
+ * Validate worker status and bounded process identity before the
+ * supervisor trusts IPC evidence.
+ */
 export declare function isProxyWorkerStatusMessage(value: unknown): value is ProxyWorkerStatusMessage;

package/dist/proxy/rollingWorkerProtocol.js

@@ -1,6 +1,8 @@
 export const PROXY_SOCKET_WORKER_ENV = "NEUROLINK_PROXY_SOCKET_WORKER";
 /** The worker has not been sent a commit and cannot have served this socket. */
 export const PROXY_SOCKET_OFFER_TIMEOUT = "PROXY_SOCKET_OFFER_TIMEOUT";
+/** Commit delivery is uncertain; close only this socket and never replay it. */
+export const PROXY_SOCKET_COMMIT_TIMEOUT = "PROXY_SOCKET_COMMIT_TIMEOUT";
 export const PROXY_ROLLING_SUPERVISOR_ENV = "NEUROLINK_PROXY_ROLLING_SUPERVISOR";
 export function isProxyWorkerControlMessage(value) {
     if (!value || typeof value !== "object") {
@@ -19,6 +21,10 @@ export function isProxyWorkerControlMessage(value) {
         message.type === "proxy-worker:activate" ||
         message.type === "proxy-worker:shutdown");
 }
+/**
+ * Validate worker status and bounded process identity before the
+ * supervisor trusts IPC evidence.
+ */
 export function isProxyWorkerStatusMessage(value) {
     if (!value || typeof value !== "object") {
         return false;
@@ -31,7 +37,12 @@ export function isProxyWorkerStatusMessage(value) {
         return false;
     }
     if (message.type === "proxy-worker:ready") {
-        return typeof message.version === "string" && message.version.length > 0;
+        return (typeof message.version === "string" &&
+            message.version.length > 0 &&
+            (message.processInstanceId === undefined ||
+                (typeof message.processInstanceId === "string" &&
+                    message.processInstanceId.length > 0 &&
+                    message.processInstanceId.length <= 256)));
     }
     if (message.type === "proxy-worker:activated" ||
         message.type === "proxy-worker:drained") {

package/dist/proxy/rollingWorkerSupervisor.d.ts

@@ -27,22 +27,50 @@ export declare class RollingWorkerSupervisor {
     snapshot(): RollingWorkerSupervisorSnapshot;
     start(expectedVersion: string): Promise<RollingWorkerSupervisorSnapshot>;
     replace(expectedVersion: string): Promise<RollingWorkerSupervisorSnapshot>;
+    /**
+     * Admit a paused socket to the active generation or the bounded
+     * readiness queue.
+     */
     acceptSocket(socket: TransferableProxySocket): void;
+    /**
+     * Retain a socket only within the queue capacity and deadline, recording
+     * classified rejection.
+     */
     private queueSocket;
     close(): Promise<void>;
     private closeWorkers;
     private requestWorkerShutdown;
     private forceTerminateWorkers;
     private notifyShutdownWaiters;
+    /**
+     * Validate candidate readiness and activation while preserving an
+     * independent listener for actual exit.
+     */
     private spawnCandidate;
     private flushQueuedSockets;
     private transferSocket;
     private maybeDrainWorker;
+    /**
+     * Cancel the affected handoff and request bounded replacement without
+     * killing unrelated streams.
+     */
     private handleTransferFailure;
+    /**
+     * Record a classified admission rejection before releasing the
+     * parent-owned socket.
+     */
     private rejectSocket;
     private describeTransferError;
     private extractLifecycleFailureDetails;
+    /**
+     * Retain the latest failure and its observed process evidence in the
+     * incident journal.
+     */
     private recordFailure;
+    /**
+     * Publish an independent incident record and retain only a bounded
+     * recent summary.
+     */
     private recordEvent;
     private scheduleTransferState;
     private publishState;