@juspay/neurolink 9.92.3 → 9.93.1

package/dist/cli/commands/proxy.d.ts

@@ -10,7 +10,8 @@
  * (generate/stream), with an optional ModelRouter for model remapping.
  */
 import type { CommandModule } from "yargs";
-import type { AccountAllowlist, LoadedProxyConfig, ModelRouterInterface, ProxyGuardArgs, ProxyNeurolinkRuntime, ProxyStartArgs, ProxyStartStrategy, ProxyStatusArgs, ProxyTelemetryArgs } from "../../lib/types/index.js";
+import type { Hono } from "hono";
+import type { AccountAllowlist, LoadedProxyConfig, ModelRouterInterface, ProxyGuardArgs, ProxyNeurolinkRuntime, ProxyStartArgs, ProxyStartStrategy, ProxyStatusArgs, ProxyTelemetryArgs, ProxyReadinessState } from "../../lib/types/index.js";
 import { ProxyRuntimeConfigStore } from "../../lib/proxy/runtimeConfig.js";
 export declare function mapClaudeErrorTypeToStatus(errorType?: string): number;
 export declare function createProxyStartApp(params: {
@@ -24,9 +25,10 @@ export declare function createProxyStartApp(params: {
     primaryAccountKey: string | undefined;
     accountAllowlist: AccountAllowlist | undefined;
     runtimeConfigStore?: ProxyRuntimeConfigStore;
+    updateControlToken?: string;
 }): Promise<{
-    app: import("hono").Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
-    readiness: import("../../lib/types/proxy.js").ProxyReadinessState;
+    app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+    readiness: ProxyReadinessState;
 }>;
 export declare const proxyStartCommand: CommandModule<object, ProxyStartArgs>;
 export declare const proxyStatusCommand: CommandModule<object, ProxyStatusArgs>;

package/dist/cli/commands/proxy.js

@@ -14,16 +14,19 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import chalk from "chalk";
 import ora from "ora";
-import { buildProxyHealthResponse, createProxyReadinessState, markProxyReady, waitForProxyReadiness, } from "../../lib/proxy/proxyHealth.js";
+import { buildProxyHealthResponse, createProxyReadinessState, markProxyDrainingForUpdate, markProxyReady, resumeProxyConnections, waitForProxyReadiness, } from "../../lib/proxy/proxyHealth.js";
 import { logger } from "../../lib/utils/logger.js";
+import { withTimeout } from "../../lib/utils/async/withTimeout.js";
 import { formatUptime, isProcessRunning, StateFileManager, } from "../utils/serverUtils.js";
 import { configureProxyKeepAliveDispatcher } from "../../lib/proxy/proxyDispatcher.js";
 import { ProxyRuntimeConfigStore } from "../../lib/proxy/runtimeConfig.js";
 import { anthropicAccountKeysEqual, createAccountAllowlist, ENV_ANTHROPIC_ACCOUNT_KEY, isAccountAllowed, LEGACY_ANTHROPIC_ACCOUNT_KEY, normalizeAnthropicAccountKey, shouldLoadFallbackCredential, } from "../../lib/proxy/accountSelection.js";
 import { beginProxyRequest, getProxyActivitySnapshot, trackProxyResponse, } from "../../lib/proxy/proxyActivity.js";
+import { flushProxyLifecycleEvents, getProxyLifecycleLoggerSnapshot, hashProxyLifecycleSessionId, logProxyLifecycleEvent, } from "../../lib/proxy/proxyLifecycle.js";
 import { describeInstallFailure, getGlobalInstallArgs, resolveGlobalInstaller, validateInstalledVersion, } from "../../lib/proxy/globalInstaller.js";
 import { startUpdaterWorkerSupervisor } from "../../lib/proxy/updaterSupervisor.js";
-import { abandonPendingUpdate, isVersionSuppressed, loadUpdateState, recordCheck, recordSuccessfulUpdate, recordUpdateFailure, recordUpdateInstalled, suppressVersion, } from "../../lib/proxy/updateState.js";
+import { waitForProxyUpdateWindow } from "../../lib/proxy/updateCoordinator.js";
+import { abandonPendingUpdate, clearUpdateDeferral, isVersionSuppressed, loadUpdateState, recordCheck, recordSuccessfulUpdate, recordUpdateDeferred, recordUpdateFailure, recordUpdateInstalled, suppressVersion, } from "../../lib/proxy/updateState.js";
 import { loadProxyEnvFile, resolveProxyEnvFile, } from "../../lib/proxy/proxyEnv.js";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
@@ -31,6 +34,9 @@ import packageJson from "../../../package.json" with { type: "json" };
 const _require = createRequire(import.meta.url);
 const PROXY_VERSION = packageJson.version;
 const PROXY_TELEMETRY_SCRIPT_PATH = fileURLToPath(new URL("../../../scripts/observability/manage-local-openobserve.sh", import.meta.url));
+const PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS = 5_000;
+const PROXY_UPDATE_CONTROL_TOKEN = process.env.NEUROLINK_PROXY_UPDATE_CONTROL_TOKEN?.trim() ||
+    crypto.randomUUID();
 // =============================================================================
 // STATE MANAGEMENT
 // =============================================================================
@@ -367,16 +373,52 @@ async function getProxyRuntimeActivity(host, port, timeoutMs = 3_000) {
         return null;
     }
 }
-function isSafeUpdateWindow(activity, quietThresholdMs, nowMs = Date.now()) {
-    if (activity.activeRequests > 0) {
-        return false;
+async function setProxyUpdateDrain(host, port, draining) {
+    const confirmState = async () => {
+        try {
+            const response = await fetch(`http://${host}:${port}/status`, {
+                signal: AbortSignal.timeout(3_000),
+            });
+            if (!response.ok) {
+                return false;
+            }
+            const payload = (await response.json());
+            return payload.health?.drainingForUpdate === draining;
+        }
+        catch {
+            return false;
+        }
+    };
+    try {
+        const response = await fetch(`http://${host}:${port}/internal/update-control`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-neurolink-update-token": PROXY_UPDATE_CONTROL_TOKEN,
+            },
+            body: JSON.stringify({ action: draining ? "drain" : "resume" }),
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (!response.ok) {
+            return confirmState();
+        }
+        const payload = (await response.json());
+        return payload.draining === draining;
+    }
+    catch {
+        return confirmState();
     }
-    if (!activity.lastActivityAt) {
-        return true;
+}
+async function resumeProxyUpdateDrain(host, port, attempts = 3) {
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        if (await setProxyUpdateDrain(host, port, false)) {
+            return true;
+        }
+        if (attempt < attempts) {
+            await sleep(1_000);
+        }
     }
-    const lastActivityMs = Date.parse(activity.lastActivityAt);
-    return (Number.isFinite(lastActivityMs) &&
-        nowMs - lastActivityMs >= quietThresholdMs);
+    return false;
 }
 // ---------------------------------------------------------------------------
 // Stable entrypoint for launchd
@@ -553,7 +595,10 @@ function spawnProxyUpdater(host, port, parentPid) {
         const child = spawn(process.execPath, args, {
             detached: true,
             stdio: ["ignore", logFd, logFd],
-            env: process.env,
+            env: {
+                ...process.env,
+                NEUROLINK_PROXY_UPDATE_CONTROL_TOKEN: PROXY_UPDATE_CONTROL_TOKEN,
+            },
         });
         child.once("error", (error) => {
             logger.always(`[proxy] updater worker error pid=${child.pid ?? "unknown"}: ${error.message}`);
@@ -643,6 +688,20 @@ export function mapClaudeErrorTypeToStatus(errorType) {
             return 502;
     }
 }
+function getProxyRuntimeErrorCode(error) {
+    let current = error;
+    for (let depth = 0; depth < 3; depth += 1) {
+        if (!current || typeof current !== "object") {
+            return undefined;
+        }
+        const code = current.code;
+        if (typeof code === "string") {
+            return code;
+        }
+        current = current.cause;
+    }
+    return undefined;
+}
 async function ensureProxyStartAllowed(spinner) {
     const ignoreLaunchd = process.env.NEUROLINK_PROXY_IGNORE_LAUNCHD === "1" ||
         process.env.NEUROLINK_PROXY_IGNORE_LAUNCHD === "true";
@@ -710,6 +769,128 @@ async function createProxyNeurolinkRuntime(logsDir) {
     cleanupLogs(7, 500);
     return { neurolink, cleanupLogs };
 }
+function registerProxyRequestTracking(app, requestMetadata, readiness) {
+    app.use("/v1/*", async (c, next) => {
+        const startedMonotonicMs = performance.now();
+        const contentLengthHeader = c.req.raw.headers.get("content-length");
+        const rawContentLength = contentLengthHeader === null ? Number.NaN : Number(contentLengthHeader);
+        const requestBytes = Number.isFinite(rawContentLength) && rawContentLength >= 0
+            ? rawContentLength
+            : undefined;
+        const sessionId = c.req.raw.headers.get("x-neurolink-session-id") ??
+            c.req.raw.headers.get("x-claude-code-session-id") ??
+            undefined;
+        const sessionHash = hashProxyLifecycleSessionId(sessionId);
+        const metadata = {
+            requestId: crypto.randomUUID(),
+            method: c.req.method,
+            path: c.req.path,
+            startedAt: Date.now(),
+            model: "-",
+            stream: false,
+            toolCount: 0,
+            rejectForUpdate: readiness.drainingForUpdate,
+        };
+        requestMetadata.set(c.req.raw, metadata);
+        const finishActivity = metadata.rejectForUpdate
+            ? () => undefined
+            : beginProxyRequest();
+        const finish = () => {
+            finishActivity();
+            requestMetadata.delete(c.req.raw);
+        };
+        // The route adapter populates model/stream/toolCount after parsing. Omit
+        // them at acceptance instead of publishing misleading placeholder values;
+        // subsequent events carry the parsed metadata under the same request ID.
+        logProxyLifecycleEvent({
+            event: "request_accepted",
+            requestId: metadata.requestId,
+            method: metadata.method,
+            path: metadata.path,
+            sessionHash,
+            requestBytes,
+            elapsedMs: 0,
+            monotonicMs: startedMonotonicMs,
+        });
+        try {
+            await next();
+            const responseStatus = c.res.status;
+            logProxyLifecycleEvent({
+                event: "response_headers",
+                requestId: metadata.requestId,
+                method: metadata.method,
+                path: metadata.path,
+                model: metadata.model,
+                stream: metadata.stream,
+                toolCount: metadata.toolCount,
+                sessionHash,
+                requestBytes,
+                responseStatus,
+                elapsedMs: performance.now() - startedMonotonicMs,
+            });
+            c.res = trackProxyResponse(c.res, finish, {
+                onFirstChunk: ({ observedBodyBytes, responseChunks }) => {
+                    logProxyLifecycleEvent({
+                        event: "response_first_chunk",
+                        requestId: metadata.requestId,
+                        method: metadata.method,
+                        path: metadata.path,
+                        model: metadata.model,
+                        stream: metadata.stream,
+                        toolCount: metadata.toolCount,
+                        sessionHash,
+                        requestBytes,
+                        responseStatus,
+                        observedBodyBytes,
+                        responseChunks,
+                        elapsedMs: performance.now() - startedMonotonicMs,
+                    });
+                },
+                onTerminal: ({ outcome, observedBodyBytes, responseChunks }) => {
+                    logProxyLifecycleEvent({
+                        event: "request_terminal",
+                        requestId: metadata.requestId,
+                        method: metadata.method,
+                        path: metadata.path,
+                        model: metadata.model,
+                        stream: metadata.stream,
+                        toolCount: metadata.toolCount,
+                        sessionHash,
+                        requestBytes,
+                        responseStatus,
+                        observedBodyBytes,
+                        responseChunks,
+                        elapsedMs: performance.now() - startedMonotonicMs,
+                        terminalOutcome: outcome,
+                        errorType: metadata.terminalErrorType,
+                        errorCode: metadata.terminalErrorCode,
+                    });
+                },
+            });
+        }
+        catch (error) {
+            // Keep metadata available to app.onError, which records the client-facing
+            // failure with the same request ID before deleting the WeakMap entry.
+            finishActivity();
+            logProxyLifecycleEvent({
+                event: "request_terminal",
+                requestId: metadata.requestId,
+                method: metadata.method,
+                path: metadata.path,
+                model: metadata.model,
+                stream: metadata.stream,
+                toolCount: metadata.toolCount,
+                sessionHash,
+                requestBytes,
+                elapsedMs: performance.now() - startedMonotonicMs,
+                terminalOutcome: "handler_error",
+                errorType: error instanceof Error ? error.name : "unknown_error",
+                errorCode: getProxyRuntimeErrorCode(error),
+            });
+            throw error;
+        }
+    });
+}
 export async function createProxyStartApp(params) {
     const { createClaudeProxyRoutes } = await import("../../lib/server/routes/claudeProxyRoutes.js");
     const { createOpenAIProxyRoutes } = await import("../../lib/server/routes/openaiProxyRoutes.js");
@@ -719,7 +900,9 @@ export async function createProxyStartApp(params) {
     const app = new Hono();
     const readiness = createProxyReadinessState();
     const requestMetadata = new WeakMap();
-    const recordRuntimeError = async (metadata, status, errorType, errorMessage, clientMessage = errorMessage, clientErrorType = errorType) => {
+    const recordRuntimeError = async (metadata, status, errorType, errorMessage, options) => {
+        const clientMessage = options?.clientMessage ?? errorMessage;
+        const clientErrorType = options?.clientErrorType ?? errorType;
         recordFinalError(status);
         await Promise.all([
             logRequest({
@@ -736,6 +919,7 @@ export async function createProxyStartApp(params) {
                 responseTimeMs: Date.now() - metadata.startedAt,
                 errorType,
                 errorMessage,
+                ...(options?.errorCode ? { errorCode: options.errorCode } : {}),
             }),
             logBodyCapture({
                 timestamp: new Date().toISOString(),
@@ -769,7 +953,13 @@ export async function createProxyStartApp(params) {
             stream: false,
             toolCount: 0,
         };
-        await recordRuntimeError(metadata, 502, "unhandled_proxy_error", errMsg, "Proxy internal error", "api_error");
+        metadata.terminalErrorType = "unhandled_proxy_error";
+        metadata.terminalErrorCode = getProxyRuntimeErrorCode(err);
+        await recordRuntimeError(metadata, 502, "unhandled_proxy_error", errMsg, {
+            clientMessage: "Proxy internal error",
+            clientErrorType: "api_error",
+            errorCode: metadata.terminalErrorCode,
+        });
         requestMetadata.delete(c.req.raw);
         return c.json({
             type: "error",
@@ -779,31 +969,34 @@ export async function createProxyStartApp(params) {
             },
         }, 502);
     });
-    app.use("/v1/*", async (c, next) => {
-        const metadata = {
-            requestId: crypto.randomUUID(),
-            method: c.req.method,
-            path: c.req.path,
-            startedAt: Date.now(),
-            model: "-",
-            stream: false,
-            toolCount: 0,
-        };
-        requestMetadata.set(c.req.raw, metadata);
-        const finishActivity = beginProxyRequest();
-        const finish = () => {
-            finishActivity();
-            requestMetadata.delete(c.req.raw);
-        };
-        try {
-            await next();
-            c.res = trackProxyResponse(c.res, finish);
+    app.post("/internal/update-control", async (c) => {
+        const suppliedToken = c.req.header("x-neurolink-update-token");
+        const expectedToken = params.updateControlToken ?? PROXY_UPDATE_CONTROL_TOKEN;
+        if (!suppliedToken || suppliedToken !== expectedToken) {
+            return c.json({ error: "not_found" }, 404);
+        }
+        const payload = await c.req
+            .json()
+            .catch(() => ({ action: undefined }));
+        if (payload.action === "drain") {
+            if (!markProxyDrainingForUpdate(readiness)) {
+                return c.json({ error: "proxy_not_ready" }, 409);
+            }
         }
-        catch (error) {
-            finishActivity();
-            throw error;
+        else if (payload.action === "resume") {
+            if (!resumeProxyConnections(readiness)) {
+                return c.json({ error: "proxy_not_ready" }, 409);
+            }
         }
+        else {
+            return c.json({ error: "invalid_action" }, 400);
+        }
+        return c.json({
+            draining: readiness.drainingForUpdate,
+            acceptingConnections: readiness.acceptingConnections,
+        });
     });
+    registerProxyRequestTracking(app, requestMetadata, readiness);
     const runtimeConfigStore = params.runtimeConfigStore;
     const runtimeConfigProvider = runtimeConfigStore
         ? () => runtimeConfigStore.getSnapshot()
@@ -819,6 +1012,24 @@ export async function createProxyStartApp(params) {
     for (const route of allProxyRoutes) {
         const method = route.method.toLowerCase();
         app[method](route.path, async (c) => {
+            const metadata = requestMetadata.get(c.req.raw);
+            if (metadata?.rejectForUpdate) {
+                if (metadata) {
+                    metadata.terminalErrorType = "proxy_draining";
+                    await recordRuntimeError(metadata, 503, "proxy_draining", "Proxy is draining for an automatic update", {
+                        clientMessage: "Proxy is restarting; retry shortly",
+                        clientErrorType: "overloaded_error",
+                    });
+                }
+                c.header("Retry-After", "2");
+                return c.json({
+                    type: "error",
+                    error: {
+                        type: "overloaded_error",
+                        message: "Proxy is restarting; retry shortly",
+                    },
+                }, 503);
+            }
             const emptyBody = {};
             let body;
             let rawBody;
@@ -849,7 +1060,6 @@ export async function createProxyStartApp(params) {
             const toolCount = Array.isArray(bodyRec?.tools)
                 ? bodyRec.tools.length
                 : 0;
-            const metadata = requestMetadata.get(c.req.raw);
             if (metadata) {
                 metadata.model = String(model);
                 metadata.stream = stream === "stream";
@@ -1042,6 +1252,9 @@ export async function createProxyStartApp(params) {
                     lastActivityAt: activity.lastActivityAt?.toISOString() ?? null,
                 };
             })(),
+            observability: {
+                lifecycle: getProxyLifecycleLoggerSnapshot(),
+            },
             autoUpdate: {
                 enabled: isProxyAutoUpdateEnabled(),
                 updaterPid: runtimeState?.updaterPid ?? null,
@@ -1051,6 +1264,7 @@ export async function createProxyStartApp(params) {
                 liveVersion: PROXY_VERSION,
                 latestVersion: updateState?.lastCheckVersion || null,
                 pendingRestartVersion: updateState?.pendingRestartVersion ?? null,
+                deferredUpdate: updateState?.deferredUpdate ?? null,
                 lastCheckAt: updateState?.lastCheckAt ?? null,
                 lastUpdateAt: updateState?.lastUpdateAt ?? null,
                 lastUpdateVersion: updateState?.lastUpdateVersion ?? null,
@@ -1339,6 +1553,12 @@ function registerProxyShutdownHandlers(params) {
             exitCode = 1;
             logger.error(`[proxy] failed to drain server during shutdown: ${error instanceof Error ? error.message : String(error)}`);
         }
+        try {
+            await withTimeout(flushProxyLifecycleEvents(), PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS, "Timed out flushing proxy lifecycle metadata during shutdown");
+        }
+        catch (error) {
+            logger.debug(`[proxy] lifecycle metadata flush failed during shutdown: ${error instanceof Error ? error.message : String(error)}`);
+        }
         try {
             const { flushOpenTelemetry, shutdownOpenTelemetry } = await import("../../lib/services/server/ai/observability/instrumentation.js");
             await flushOpenTelemetry();
@@ -1848,6 +2068,7 @@ export const proxyStatusCommand = {
                 updaterRunning: false,
                 latestVersion: updateState?.lastCheckVersion || null,
                 pendingRestartVersion: updateState?.pendingRestartVersion ?? null,
+                deferredUpdate: updateState?.deferredUpdate ?? null,
                 lastUpdateFailure: updateState?.lastFailure ?? null,
             };
             if (state && isProcessRunning(state.pid)) {
@@ -1927,6 +2148,12 @@ export const proxyStatusCommand = {
                 if (status.pendingRestartVersion) {
                     logger.always(`  ${chalk.bold("Pending:")}    ${chalk.yellow(`v${status.pendingRestartVersion} installed; restart pending`)}`);
                 }
+                if (status.deferredUpdate) {
+                    const active = status.deferredUpdate.activeRequests === null
+                        ? "unknown activity"
+                        : `${status.deferredUpdate.activeRequests} active request(s)`;
+                    logger.always(`  ${chalk.bold("Deferred:")}   ${chalk.yellow(`v${status.deferredUpdate.version} ${status.deferredUpdate.reason} (${active})`)}`);
+                }
                 if (status.latestVersion) {
                     logger.always(`  ${chalk.bold("Latest:")}     ${chalk.cyan(`v${status.latestVersion}`)}`);
                 }
@@ -2109,6 +2336,10 @@ export const proxyGuardCommand = {
         // foreground fail-open guard remains cleanup-only.
         const UPDATE_CHECK_INTERVAL_MS = 2 * 60 * 60 * 1000; // 2 hours
         const QUIET_THRESHOLD_MS = 120 * 1000; // 2 minutes of silence
+        const NATURAL_WINDOW_WAIT_MS = 10 * 60 * 1000; // prefer no admission pause
+        const UPDATE_DRAIN_TIMEOUT_MS = 30 * 60 * 1000; // preserve long streams
+        const UPDATE_RETRY_DELAY_MS = 5 * 60 * 1000;
+        const UPDATE_ACTIVITY_POLL_MS = 10 * 1000;
         const UPDATE_TIMEOUT_MS = 30 * 1000; // 30 seconds to come healthy
         // Get running version from /health endpoint (with timeout to avoid hanging)
         let runningVersion = PROXY_VERSION; // fallback
@@ -2131,6 +2362,7 @@ export const proxyGuardCommand = {
         let guardStopping = false;
         let updateCheckTimeout;
         let updateCheckInterval;
+        let updateRetryTimeout;
         const stopUpdateChecks = () => {
             guardStopping = true;
             if (updateCheckTimeout) {
@@ -2141,6 +2373,10 @@ export const proxyGuardCommand = {
                 clearInterval(updateCheckInterval);
                 updateCheckInterval = undefined;
             }
+            if (updateRetryTimeout) {
+                clearTimeout(updateRetryTimeout);
+                updateRetryTimeout = undefined;
+            }
         };
         /** Keep state-write failures observable without terminating the updater. */
         const persistUpdaterState = (operation, action) => {
@@ -2159,41 +2395,93 @@ export const proxyGuardCommand = {
             }
             updateInProgress = true;
             let updateVersion = runningVersion;
+            let drainActive = false;
             try {
                 // Lazy-load update modules so they're only imported at check time
                 const { checkForUpdate } = await import("../../lib/proxy/updateChecker.js");
                 // 1. Check for update
-                const result = await checkForUpdate(runningVersion);
+                let result = await checkForUpdate(runningVersion);
                 updateVersion = result.latestVersion;
                 persistUpdaterState("record update check", () => recordCheck(result.latestVersion));
                 if (!result.updateAvailable) {
+                    persistUpdaterState("clear update deferral", () => clearUpdateDeferral());
                     return;
                 }
-                const pendingRestart = loadUpdateState()?.pendingRestartVersion === result.latestVersion;
-                if (isVersionSuppressed(result.latestVersion) && !pendingRestart) {
+                const initiallyPendingRestart = loadUpdateState()?.pendingRestartVersion === result.latestVersion;
+                if (isVersionSuppressed(result.latestVersion) &&
+                    !initiallyPendingRestart) {
                     logger.debug(`[guard] version ${result.latestVersion} is suppressed, skipping`);
                     return;
                 }
                 logger.always(`[updater] update available: ${runningVersion} → ${result.latestVersion}`);
-                // 2. Wait for an exact runtime-idle window. Never force an update while
-                // a request or stream is active; the next worker cycle can try again.
-                const quietPollMs = 10_000; // check every 10s
-                while (!guardStopping) {
-                    if (getProcessStatus(parentPid) === "not_running") {
-                        logger.always(`[updater] parent process died while waiting for idle traffic`);
-                        return;
+                // 2. Prefer a naturally quiet period. Sustained traffic is handled by
+                // a bounded graceful drain so update checks cannot wait forever.
+                let lastDeferralSignature = "";
+                const waitForWindow = async (quietWaitMs) => {
+                    const window = await waitForProxyUpdateWindow({
+                        quietThresholdMs: QUIET_THRESHOLD_MS,
+                        quietWaitMs,
+                        drainWaitMs: UPDATE_DRAIN_TIMEOUT_MS,
+                        pollIntervalMs: UPDATE_ACTIVITY_POLL_MS,
+                        getActivity: () => getProxyRuntimeActivity(host, port),
+                        setDraining: async (draining) => {
+                            const changed = await setProxyUpdateDrain(host, port, draining);
+                            if (changed) {
+                                logger.always(`[updater] ${draining ? "draining new inference requests" : "inference admission resumed"}`);
+                            }
+                            return changed;
+                        },
+                        isStopping: () => guardStopping,
+                        isParentAlive: () => getProcessStatus(parentPid) !== "not_running",
+                        onPhase: (phase, activity) => {
+                            const reason = phase === "waiting_for_quiet" && !activity
+                                ? "activity_unavailable"
+                                : phase;
+                            const signature = `${reason}:${activity?.activeRequests ?? "unknown"}`;
+                            if (signature !== lastDeferralSignature) {
+                                lastDeferralSignature = signature;
+                                persistUpdaterState("record update deferral", () => recordUpdateDeferred(result.latestVersion, reason, activity?.activeRequests ?? null));
+                            }
+                            logger.debug(`[updater] ${reason} (${activity?.activeRequests ?? "unknown"} active requests)`);
+                        },
+                    });
+                    drainActive = drainActive || window.draining;
+                    return window;
+                };
+                let updateWindow = await waitForWindow(NATURAL_WINDOW_WAIT_MS);
+                if (!updateWindow.ready) {
+                    if (updateWindow.reason === "drain_failed") {
+                        persistUpdaterState("record unavailable update drain", () => recordUpdateDeferred(result.latestVersion, "drain_unavailable", null));
                     }
-                    const activity = await getProxyRuntimeActivity(host, port);
-                    if (activity && isSafeUpdateWindow(activity, QUIET_THRESHOLD_MS)) {
-                        logger.always(`[updater] traffic idle, proceeding with update`);
-                        break;
+                    scheduleUpdateRetry();
+                    return;
+                }
+                // Close the small race between observing zero activity and package
+                // mutation by holding admission closed through install and restart.
+                if (!drainActive) {
+                    updateWindow = await waitForWindow(0);
+                    if (!updateWindow.ready) {
+                        scheduleUpdateRetry();
+                        return;
                     }
-                    logger.debug(`[updater] waiting for idle traffic (${activity?.activeRequests ?? "unknown"} active requests)`);
-                    await new Promise((r) => setTimeout(r, quietPollMs));
                 }
-                if (guardStopping) {
+                // Refresh after waiting so a long deferral can never install a stale
+                // target while a newer release is already available.
+                const refreshedResult = await checkForUpdate(runningVersion);
+                result = refreshedResult;
+                updateVersion = result.latestVersion;
+                persistUpdaterState("record refreshed update check", () => recordCheck(result.latestVersion));
+                if (!result.updateAvailable) {
+                    persistUpdaterState("clear update deferral", () => clearUpdateDeferral());
                     return;
                 }
+                const pendingRestart = loadUpdateState()?.pendingRestartVersion === result.latestVersion;
+                if (isVersionSuppressed(result.latestVersion) && !pendingRestart) {
+                    logger.debug(`[guard] refreshed version ${result.latestVersion} is suppressed, skipping`);
+                    return;
+                }
+                persistUpdaterState("clear update deferral", () => clearUpdateDeferral());
+                logger.always(`[updater] safe update window acquired for v${result.latestVersion}`);
                 // 3. Install update (validate version string before passing to shell)
                 if (!/^\d+\.\d+\.\d+$/.test(result.latestVersion)) {
                     const message = `invalid version format: ${result.latestVersion}`;
@@ -2266,22 +2554,8 @@ export const proxyGuardCommand = {
                 if (guardStopping || getProcessStatus(parentPid) === "not_running") {
                     return;
                 }
-                // Installation can overlap new traffic. Re-establish a full idle window
-                // before restart so no accepted request or long stream is interrupted.
-                while (!guardStopping) {
-                    if (getProcessStatus(parentPid) === "not_running") {
-                        return;
-                    }
-                    const activity = await getProxyRuntimeActivity(host, port);
-                    if (activity && isSafeUpdateWindow(activity, QUIET_THRESHOLD_MS)) {
-                        break;
-                    }
-                    logger.debug(`[updater] update installed; deferring restart (${activity?.activeRequests ?? "unknown"} active requests)`);
-                    await sleep(10_000);
-                }
-                if (guardStopping) {
-                    return;
-                }
+                // Admission has remained closed since active requests reached zero, so
+                // restart cannot interrupt an accepted request or long-lived stream.
                 // Signal the health loop to not exit when it detects
                 // the parent PID is gone — we're intentionally restarting.
                 updateRestartInProgress = true;
@@ -2302,6 +2576,7 @@ export const proxyGuardCommand = {
                     persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "restart", msg));
                     return;
                 }
+                drainActive = false;
                 // 5. Wait for healthy restart
                 let healthy = false;
                 const restartStart = Date.now();
@@ -2343,9 +2618,25 @@ export const proxyGuardCommand = {
                 persistUpdaterState("record update failure", () => recordUpdateFailure(updateVersion, "check", message));
             }
             finally {
+                if (drainActive && !updateRestartInProgress) {
+                    const resumed = await resumeProxyUpdateDrain(host, port);
+                    if (!resumed && getProcessStatus(parentPid) !== "not_running") {
+                        logger.always(`[updater] WARNING: failed to resume inference admission after deferred update`);
+                    }
+                }
                 updateInProgress = false;
             }
         };
+        const scheduleUpdateRetry = () => {
+            if (guardStopping || updateRetryTimeout) {
+                return;
+            }
+            updateRetryTimeout = setTimeout(() => {
+                updateRetryTimeout = undefined;
+                void runUpdateCheck();
+            }, UPDATE_RETRY_DELAY_MS);
+            updateRetryTimeout.unref?.();
+        };
         // Run first check after a short delay, then on interval
         if (canAutoUpdate) {
             updateCheckTimeout = setTimeout(runUpdateCheck, 30_000);

package/dist/cli/commands/proxyAnalyze.d.ts

@@ -0,0 +1,3 @@
+import type { CommandModule } from "yargs";
+import type { ProxyAnalyzeArgs } from "../../lib/types/index.js";
+export declare const proxyAnalyzeCommand: CommandModule<object, ProxyAnalyzeArgs>;