@juspay/neurolink 12.20.0 → 12.20.2

package/dist/proxy/rollingWorkerProcess.js

@@ -9,6 +9,8 @@ import { isProxyWorkerStatusMessage, PROXY_SOCKET_WORKER_ENV, PROXY_SOCKET_OFFER
 export function spawnProxySocketWorker(options) {
     const socketAckTimeoutMs = Math.max(1, options.socketAckTimeoutMs ?? 30_000);
     let nextSocketId = 0;
+    let controlBeforeHandle = false;
+    let workerCommitAcknowledgement = false;
     const pendingSockets = new Map();
     const statusListeners = new Set();
     const pendingStatusMessages = [];
@@ -124,6 +126,26 @@ export function spawnProxySocketWorker(options) {
      * the commit phase.
      */
     const onInternalMessage = (message) => {
+        if (isProxyWorkerStatusMessage(message) &&
+            message.type === "proxy-worker:ready" &&
+            message.generation === options.generation &&
+            message.pid === childPid) {
+            controlBeforeHandle =
+                message.socketOfferProtocol === "control-before-handle";
+            workerCommitAcknowledgement =
+                message.socketCommitProtocol === "worker-ack";
+        }
+        if (isProxyWorkerStatusMessage(message) &&
+            message.type === "proxy-worker:socket-committed" &&
+            message.generation === options.generation &&
+            message.pid === childPid) {
+            const pending = pendingSockets.get(message.socketId);
+            if (!pending || !pending.accepted || !pending.descriptorSent) {
+                return;
+            }
+            settleSocket(message.socketId);
+            return;
+        }
         if (isProxyWorkerStatusMessage(message) &&
             message.type === "proxy-worker:socket-accepted" &&
             message.generation === options.generation &&
@@ -132,22 +154,56 @@ export function spawnProxySocketWorker(options) {
             if (!pending || pending.accepted) {
                 return;
             }
+            if (Date.now() >= pending.deadlineAt) {
+                const error = Object.assign(new Error("Socket admission deadline expired before commit"), {
+                    code: PROXY_SOCKET_OFFER_TIMEOUT,
+                    socketNeverTransferred: !pending.descriptorSent,
+                });
+                settleSocket(message.socketId, error);
+                return;
+            }
+            const commitBudgetMs = Math.min(socketAckTimeoutMs, pending.deadlineAt - Date.now());
+            const minimumCommitWindowMs = Math.min(socketAckTimeoutMs, 1_000);
+            if (commitBudgetMs < minimumCommitWindowMs) {
+                settleSocket(message.socketId, Object.assign(new Error("Socket admission deadline too close for commit"), {
+                    code: PROXY_SOCKET_OFFER_TIMEOUT,
+                    socketNeverTransferred: !pending.descriptorSent,
+                }));
+                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`);
+                const error = new Error(`proxy worker ${childPid} socket commit remained pending for ${commitBudgetMs}ms`);
                 error.code = PROXY_SOCKET_COMMIT_TIMEOUT;
                 settleSocket(message.socketId, error);
-            }, socketAckTimeoutMs);
+            }, commitBudgetMs);
             pending.timeout.unref?.();
             try {
-                child.send({
+                const commit = {
                     type: "proxy-worker:socket-commit",
                     generation: options.generation,
                     socketId: message.socketId,
-                }, (error) => settleSocket(message.socketId, error ?? undefined));
+                };
+                if (!pending.descriptorSent) {
+                    // Mark ambiguous before calling IPC: even a thrown/send callback error
+                    // cannot prove the descriptor was not delivered and consumed.
+                    pending.descriptorSent = true;
+                    child.send(commit, pending.socket, { keepOpen: true }, (error) => {
+                        if (error || !workerCommitAcknowledgement) {
+                            settleSocket(message.socketId, error ?? undefined);
+                        }
+                    });
+                }
+                else {
+                    child.send(commit, (error) => {
+                        if (error || !workerCommitAcknowledgement) {
+                            settleSocket(message.socketId, error ?? undefined);
+                        }
+                    });
+                }
             }
             catch (error) {
                 settleSocket(message.socketId, error instanceof Error ? error : new Error(String(error)));
@@ -208,8 +264,17 @@ export function spawnProxySocketWorker(options) {
     };
     return {
         pid: childPid,
+        socketTransferTimeoutMs: 2 * socketAckTimeoutMs,
         sendControl,
-        sendSocket: (generation, socket, callback) => {
+        sendSocket: (generation, socket, callback, deadlineAt = Date.now() + 2 * socketAckTimeoutMs) => {
+            if (Date.now() >= deadlineAt) {
+                const error = Object.assign(new Error("Socket admission deadline expired before offer"), {
+                    code: PROXY_SOCKET_OFFER_TIMEOUT,
+                    socketNeverTransferred: true,
+                });
+                callback(error);
+                return;
+            }
             if (budgetResponseFailure) {
                 callback(budgetResponseFailure);
                 return;
@@ -220,23 +285,35 @@ 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`);
-                error.code = PROXY_SOCKET_OFFER_TIMEOUT;
+                const error = Object.assign(new Error(`proxy worker ${childPid} did not accept socket within ${socketAckTimeoutMs}ms`), {
+                    code: PROXY_SOCKET_OFFER_TIMEOUT,
+                    socketNeverTransferred: pendingSockets.get(socketId)?.descriptorSent === false,
+                });
                 settleSocket(socketId, error);
-            }, socketAckTimeoutMs);
+            }, Math.max(0, Math.min(socketAckTimeoutMs, deadlineAt - Date.now())));
             timeout.unref?.();
             pendingSockets.set(socketId, {
                 socket,
                 callback,
                 timeout,
                 accepted: false,
+                deadlineAt,
+                descriptorSent: !controlBeforeHandle,
             });
             try {
-                child.send({ type: "proxy-worker:socket", generation, socketId }, socket, { keepOpen: true }, (error) => {
+                const onSent = (error) => {
                     if (error) {
                         settleSocket(socketId, error);
                     }
-                });
+                };
+                if (controlBeforeHandle) {
+                    child.send({ type: "proxy-worker:socket-offer", generation, socketId }, onSent);
+                }
+                else {
+                    // Old workers require descriptor-first offers. They may buffer input
+                    // before commit, so their timed-out offers are never safe to retry.
+                    child.send({ type: "proxy-worker:socket", generation, socketId }, socket, { keepOpen: true }, onSent);
+                }
             }
             catch (error) {
                 settleSocket(socketId, error instanceof Error ? error : new Error(String(error)));

package/dist/proxy/rollingWorkerProtocol.js

@@ -13,7 +13,8 @@ export function isProxyWorkerControlMessage(value) {
         Number(message.generation) <= 0) {
         return false;
     }
-    if (message.type === "proxy-worker:socket-commit" ||
+    if (message.type === "proxy-worker:socket-offer" ||
+        message.type === "proxy-worker:socket-commit" ||
         message.type === "proxy-worker:socket-cancel") {
         return typeof message.socketId === "string" && message.socketId.length > 0;
     }
@@ -48,7 +49,8 @@ export function isProxyWorkerStatusMessage(value) {
         message.type === "proxy-worker:drained") {
         return true;
     }
-    if (message.type === "proxy-worker:socket-accepted") {
+    if (message.type === "proxy-worker:socket-accepted" ||
+        message.type === "proxy-worker:socket-committed") {
         return typeof message.socketId === "string" && message.socketId.length > 0;
     }
     if (message.type === "proxy-worker:replacement-requested") {

package/dist/proxy/rollingWorkerSupervisor.js

@@ -4,6 +4,7 @@ const DEFAULT_READY_TIMEOUT_MS = 120_000;
 const DEFAULT_SOCKET_QUEUE_LIMIT = 1_024;
 const DEFAULT_SOCKET_QUEUE_TIMEOUT_MS = 30_000;
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
+const DEFAULT_SOCKET_TRANSFER_TIMEOUT_MS = 60_000;
 const MAX_RECENT_SUPERVISOR_EVENTS = 100;
 /**
  * Owns worker generations while the caller owns the public listening socket.
@@ -105,33 +106,44 @@ export class RollingWorkerSupervisor {
             this.rejectSocket(socket, undefined, undefined, "supervisor_closed");
             return;
         }
+        const admission = {
+            socket,
+            // Preserve the original offer + commit allowance. Queued sockets also
+            // retain their existing queue wait, but no retry ever renews this budget.
+            deadlineAt: Date.now() +
+                (this.active?.handle.socketTransferTimeoutMs ??
+                    DEFAULT_SOCKET_TRANSFER_TIMEOUT_MS),
+            retried: false,
+        };
         if (this.active &&
             this.queuedSockets.length === 0 &&
             this.active.pendingTransfers < this.options.maxPendingTransfers) {
-            this.transferSocket(this.active, socket);
+            this.transferSocket(this.active, admission);
             return;
         }
-        this.queueSocket(socket);
+        admission.deadlineAt += this.options.socketQueueTimeoutMs;
+        this.queueSocket(admission);
         this.flushQueuedSockets();
     }
     /**
      * Retain a socket only within the queue capacity and deadline, recording
      * classified rejection.
      */
-    queueSocket(socket) {
+    queueSocket(admission) {
+        const { socket } = admission;
         if (this.queuedSockets.length >= this.options.socketQueueLimit) {
             this.rejectSocket(socket, undefined, undefined, "queue_capacity");
             return;
         }
         const queued = {
-            socket,
+            ...admission,
             timeout: setTimeout(() => {
                 const index = this.queuedSockets.indexOf(queued);
                 if (index >= 0) {
                     this.queuedSockets.splice(index, 1);
                     this.rejectSocket(socket, undefined, undefined, "queue_timeout");
                 }
-            }, this.options.socketQueueTimeoutMs),
+            }, Math.max(0, Math.min(this.options.socketQueueTimeoutMs, admission.deadlineAt - Date.now()))),
         };
         queued.timeout.unref?.();
         this.queuedSockets.push(queued);
@@ -432,14 +444,19 @@ export class RollingWorkerSupervisor {
                     break;
                 }
                 clearTimeout(queued.timeout);
-                this.transferSocket(this.active, queued.socket);
+                this.transferSocket(this.active, queued);
             }
         }
         finally {
             this.flushingSockets = false;
         }
     }
-    transferSocket(worker, socket) {
+    transferSocket(worker, admission) {
+        const { socket } = admission;
+        if (Date.now() >= admission.deadlineAt) {
+            this.rejectSocket(socket, worker.generation, worker.version, "admission_timeout");
+            return;
+        }
         worker.pendingTransfers += 1;
         this.scheduleTransferState();
         let settled = false;
@@ -450,7 +467,7 @@ export class RollingWorkerSupervisor {
             settled = true;
             worker.pendingTransfers = Math.max(0, worker.pendingTransfers - 1);
             if (error) {
-                this.handleTransferFailure(worker, socket, error);
+                this.handleTransferFailure(worker, admission, error);
             }
             else if (this.active?.generation === worker.generation) {
                 this.consecutiveOfferTimeouts = 0;
@@ -460,7 +477,7 @@ export class RollingWorkerSupervisor {
             this.scheduleTransferState();
         };
         try {
-            worker.handle.sendSocket(worker.generation, socket, complete);
+            worker.handle.sendSocket(worker.generation, socket, complete, admission.deadlineAt);
         }
         catch (error) {
             complete(error instanceof Error ? error : new Error(String(error)));
@@ -487,7 +504,8 @@ export class RollingWorkerSupervisor {
      * Cancel the affected handoff and request bounded replacement without
      * killing unrelated streams.
      */
-    handleTransferFailure(worker, socket, error) {
+    handleTransferFailure(worker, admission, error) {
+        const { socket } = admission;
         this.failedTransfers += 1;
         const detail = this.describeTransferError(error);
         this.recordEvent({
@@ -540,6 +558,25 @@ export class RollingWorkerSupervisor {
         // A failed handoff is not evidence that every connection on this worker
         // failed. Cancel only the affected socket and activate a replacement before
         // draining existing streams. Actual exits are handled by onExit below.
+        const replacement = this.active;
+        if (cancelledOffer &&
+            error instanceof Error &&
+            "socketNeverTransferred" in error &&
+            error.socketNeverTransferred === true &&
+            !lifecycle.observedExit &&
+            !admission.retried &&
+            !this.closed &&
+            replacement &&
+            replacement.generation !== worker.generation &&
+            replacement.pendingTransfers < this.options.maxPendingTransfers &&
+            Date.now() < admission.deadlineAt) {
+            // Only negotiated control-only offers retain every byte on this parent.
+            // Legacy descriptor offers can buffer bytes before commit and never retry.
+            // The removed IPC entry also prevents a late acceptance issuing a commit.
+            // Every other failure is ambiguous and must never replay request bytes.
+            this.transferSocket(replacement, { ...admission, retried: true });
+            return;
+        }
         this.rejectSocket(socket, worker.generation, worker.version, "transfer_failure");
     }
     /**

package/dist/proxy/socketWorkerRuntime.js

@@ -1,4 +1,5 @@
 import { isProxyWorkerControlMessage } from "./rollingWorkerProtocol.js";
+const DEFAULT_FIRST_REQUEST_GRACE_MS = 30_000;
 function isTransferableProxySocket(handle) {
     if (!handle || typeof handle !== "object") {
         return false;
@@ -32,8 +33,33 @@ export function createSocketWorkerRuntime(server, options) {
     const sockets = new Set();
     const activeBySocket = new Map();
     const activeResponses = new Set();
+    const awaitingFirstRequest = new Set();
+    const firstRequestTimers = new Map();
+    const firstRequestGraceMs = Math.max(1, options?.firstRequestGraceMs ?? DEFAULT_FIRST_REQUEST_GRACE_MS);
     let draining = false;
     let drained = false;
+    const clearFirstRequestWait = (socket) => {
+        awaitingFirstRequest.delete(socket);
+        const timer = firstRequestTimers.get(socket);
+        if (timer) {
+            clearTimeout(timer);
+            firstRequestTimers.delete(socket);
+        }
+    };
+    const boundFirstRequestWait = (socket) => {
+        if (firstRequestTimers.has(socket)) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            firstRequestTimers.delete(socket);
+            awaitingFirstRequest.delete(socket);
+            if (draining && sockets.has(socket) && !activeBySocket.has(socket)) {
+                socket.end();
+            }
+        }, firstRequestGraceMs);
+        timer.unref?.();
+        firstRequestTimers.set(socket, timer);
+    };
     const maybeFinishDrain = () => {
         if (draining && !drained && sockets.size === 0) {
             drained = true;
@@ -42,6 +68,7 @@ export function createSocketWorkerRuntime(server, options) {
     };
     const requestStarted = (request, response) => {
         const socket = request.socket;
+        clearFirstRequestWait(socket);
         activeBySocket.set(socket, (activeBySocket.get(socket) ?? 0) + 1);
         activeResponses.add(response);
         if (draining) {
@@ -75,7 +102,9 @@ export function createSocketWorkerRuntime(server, options) {
             return;
         }
         sockets.add(socket);
+        awaitingFirstRequest.add(socket);
         socket.once("close", () => {
+            clearFirstRequestWait(socket);
             sockets.delete(socket);
             activeBySocket.delete(socket);
             maybeFinishDrain();
@@ -92,7 +121,15 @@ export function createSocketWorkerRuntime(server, options) {
             response.shouldKeepAlive = false;
         }
         for (const socket of sockets) {
-            if (!activeBySocket.has(socket)) {
+            if (awaitingFirstRequest.has(socket)) {
+                // IPC commit confirms descriptor delivery, not HTTP parser admission.
+                // Under host pressure a drain can otherwise end the socket before its
+                // first buffered request reaches the server. Preserve it for one
+                // bounded header-start window; the worker supervisor remains the outer
+                // hard shutdown bound.
+                boundFirstRequestWait(socket);
+            }
+            else if (!activeBySocket.has(socket)) {
                 socket.end();
             }
         }
@@ -103,6 +140,11 @@ export function createSocketWorkerRuntime(server, options) {
         drain,
         close: () => {
             server.off("request", requestStarted);
+            for (const timer of firstRequestTimers.values()) {
+                clearTimeout(timer);
+            }
+            firstRequestTimers.clear();
+            awaitingFirstRequest.clear();
             for (const socket of sockets) {
                 socket.destroy();
             }
@@ -174,6 +216,31 @@ export function attachSocketWorkerProcess(server, input) {
     };
     /** Apply supervisor messages while retaining ownership of pending and committed sockets. */
     const onMessage = (message, handle) => {
+        if (handle !== undefined &&
+            isProxyWorkerControlMessage(message) &&
+            message.type === "proxy-worker:socket-commit" &&
+            message.generation === input.generation) {
+            // New supervisors first offer only a socket ID. The descriptor arrives
+            // here at commit, so an abandoned offer cannot consume any client bytes.
+            if (!activated ||
+                gracefulDrain ||
+                !isTransferableProxySocket(handle) ||
+                pendingSockets.has(message.socketId) ||
+                committedSockets.has(message.socketId)) {
+                destroyTransferredHandle(handle);
+                return;
+            }
+            committedSockets.set(message.socketId, handle);
+            handle.once("close", () => committedSockets.delete(message.socketId));
+            runtime.acceptSocket(handle);
+            send({
+                type: "proxy-worker:socket-committed",
+                generation: input.generation,
+                pid: process.pid,
+                socketId: message.socketId,
+            });
+            return;
+        }
         if (message &&
             typeof message === "object" &&
             message.type === "proxy-worker:socket") {
@@ -245,7 +312,17 @@ export function attachSocketWorkerProcess(server, input) {
         }
         if (isProxyWorkerControlMessage(message) &&
             message.generation === input.generation) {
-            if (message.type === "proxy-worker:activate") {
+            if (message.type === "proxy-worker:socket-offer") {
+                if (activated && !gracefulDrain && process.connected) {
+                    send({
+                        type: "proxy-worker:socket-accepted",
+                        generation: input.generation,
+                        pid: process.pid,
+                        socketId: message.socketId,
+                    });
+                }
+            }
+            else if (message.type === "proxy-worker:activate") {
                 if (!activated) {
                     try {
                         input.onActivated?.();
@@ -280,6 +357,12 @@ export function attachSocketWorkerProcess(server, input) {
                     committedSockets.set(message.socketId, socket);
                     socket.once("close", () => committedSockets.delete(message.socketId));
                     runtime.acceptSocket(socket);
+                    send({
+                        type: "proxy-worker:socket-committed",
+                        generation: input.generation,
+                        pid: process.pid,
+                        socketId: message.socketId,
+                    });
                 }
                 else {
                     committedSockets.delete(message.socketId);
@@ -300,8 +383,9 @@ export function attachSocketWorkerProcess(server, input) {
     // Terminal shutdown path: the parent IPC channel is gone (disconnect) or the
     // process is being killed (SIGTERM/SIGINT). Unlike the graceful rolling drain
     // above, pending offers can no longer be committed, so they are destroyed and
-    // the drain runs immediately — a best-effort close is correct when the process
-    // is exiting. The zero-downtime guarantee applies to the rolling handoff
+    // the bounded runtime drain starts immediately. A committed socket may still
+    // use its first-request grace; the supervisor remains the outer hard shutdown
+    // bound. The zero-downtime guarantee applies to the rolling handoff
     // (control-message) path, not to process termination.
     const drain = () => {
         for (const socketId of [...pendingSockets.keys()]) {
@@ -320,6 +404,8 @@ export function attachSocketWorkerProcess(server, input) {
         pid: process.pid,
         version: input.version,
         processInstanceId: input.processInstanceId,
+        socketOfferProtocol: "control-before-handle",
+        socketCommitProtocol: "worker-ack",
     });
     return {
         ...runtime,

package/dist/proxy/updateChecker.d.ts

@@ -4,14 +4,14 @@
  * Queries the npm registry for the latest published version of
  * `@juspay/neurolink` and compares it against the currently running version.
  * Designed to be non-blocking and failure-tolerant — any error (network,
- * timeout, parse) silently returns `updateAvailable: false`.
+ * timeout, parse) returns an explicit failed check without inventing a release.
  */
 import type { UpdateCheckResult } from "../types/index.js";
 /**
  * Query npm for the latest version of `@juspay/neurolink` and compare it
  * against {@link currentVersion}.
  *
- * On **any** failure the function resolves (never rejects) with
- * `{ updateAvailable: false, latestVersion: currentVersion }`.
+ * Failure retains the legacy version fallback but marks it unverified. Callers
+ * must not persist it as a successful registry observation.
  */
 export declare function checkForUpdate(currentVersion: string): Promise<UpdateCheckResult>;

package/dist/proxy/updateChecker.js

@@ -4,7 +4,7 @@
  * Queries the npm registry for the latest published version of
  * `@juspay/neurolink` and compares it against the currently running version.
  * Designed to be non-blocking and failure-tolerant — any error (network,
- * timeout, parse) silently returns `updateAvailable: false`.
+ * timeout, parse) returns an explicit failed check without inventing a release.
  */
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
@@ -54,15 +54,17 @@ function isNewerVersion(current, latest) {
  * Query npm for the latest version of `@juspay/neurolink` and compare it
  * against {@link currentVersion}.
  *
- * On **any** failure the function resolves (never rejects) with
- * `{ updateAvailable: false, latestVersion: currentVersion }`.
+ * Failure retains the legacy version fallback but marks it unverified. Callers
+ * must not persist it as a successful registry observation.
  */
 export async function checkForUpdate(currentVersion) {
-    const fail = {
+    const fail = (checkError) => ({
         currentVersion,
         latestVersion: currentVersion,
         updateAvailable: false,
-    };
+        checkSucceeded: false,
+        checkError,
+    });
     try {
         logger.debug("[UpdateChecker] Checking for updates", { currentVersion });
         const { stdout } = await execFile("npm", ["view", "@juspay/neurolink", "version", "--json"], { timeout: NPM_VIEW_TIMEOUT_MS });
@@ -72,14 +74,14 @@ export async function checkForUpdate(currentVersion) {
             logger.warn("[UpdateChecker] Unexpected npm output type", {
                 type: typeof parsed,
             });
-            return fail;
+            return fail("Registry returned a non-string version");
         }
         const latestVersion = parsed.trim();
         if (!parseSemVer(latestVersion)) {
             logger.warn("[UpdateChecker] Failed to parse latest version", {
                 latestVersion,
             });
-            return fail;
+            return fail("Registry returned an invalid version");
         }
         const updateAvailable = isNewerVersion(currentVersion, latestVersion);
         logger.debug("[UpdateChecker] Version check complete", {
@@ -87,11 +89,16 @@ export async function checkForUpdate(currentVersion) {
             latestVersion,
             updateAvailable,
         });
-        return { currentVersion, latestVersion, updateAvailable };
+        return {
+            currentVersion,
+            latestVersion,
+            updateAvailable,
+            checkSucceeded: true,
+        };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         logger.warn("[UpdateChecker] Update check failed", { error: message });
-        return fail;
+        return fail("Registry version check failed; see updater diagnostics");
     }
 }

package/dist/proxy/updateCoordinator.d.ts

@@ -1,4 +1,11 @@
-import type { ProxyRuntimeActivity, ProxyUpdateWindowOptions, ProxyUpdateWindowResult } from "../types/index.js";
+import type { ProxyRuntimeActivity, ProxyServingWorkerIdentity, ProxyUpdateWindowOptions, ProxyUpdateWindowResult } from "../types/index.js";
+/**
+ * Parse serving identity conservatively from `/status`. A rolling status is
+ * trusted only when the worker-local fields agree with the supervisor snapshot.
+ */
+export declare function parseProxyServingWorkerIdentity(payload: unknown, rollingSupervisor: boolean): ProxyServingWorkerIdentity | null;
+/** A long-running update may mutate live selection only for its original worker. */
+export declare function isSameProxyServingWorker(expected: ProxyServingWorkerIdentity, current: ProxyServingWorkerIdentity | null | undefined): boolean;
 /**
  * A replacement updater starts from the newly installed package. The registry
  * then reports no newer version even when its launchd parent still runs the
@@ -18,6 +25,8 @@ export declare function isProxyRuntimeSettled(activity: ProxyRuntimeActivity): b
 export declare function parseProxyRuntimeActivity(payload: unknown): ProxyRuntimeActivity | null;
 /**
  * Prefer a naturally quiet window, then briefly drain new inference traffic.
+ * Automatic supervisor refresh uses allowBusyDrain=false: it fences admission
+ * only after a quiet observation and never waits for busy workers behind it.
  * Existing requests are never interrupted; a bounded drain failure is returned
  * to the caller so admission can be reopened and retried later.
  */