@juspay/neurolink 9.93.0 → 9.93.2

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

@@ -11,7 +11,7 @@
  */
 import type { CommandModule } from "yargs";
 import type { Hono } from "hono";
-import type { AccountAllowlist, LoadedProxyConfig, ModelRouterInterface, ProxyGuardArgs, ProxyNeurolinkRuntime, ProxyStartArgs, ProxyStartStrategy, ProxyStatusArgs, ProxyTelemetryArgs } from "../../lib/types/index.js";
+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: {
@@ -25,9 +25,10 @@ export declare function createProxyStartApp(params: {
     primaryAccountKey: string | undefined;
     accountAllowlist: AccountAllowlist | undefined;
     runtimeConfigStore?: ProxyRuntimeConfigStore;
+    updateControlToken?: string;
 }): Promise<{
     app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
-    readiness: import("../../lib/types/proxy.js").ProxyReadinessState;
+    readiness: ProxyReadinessState;
 }>;
 export declare const proxyStartCommand: CommandModule<object, ProxyStartArgs>;
 export declare const proxyStatusCommand: CommandModule<object, ProxyStatusArgs>;

package/dist/cli/commands/proxy.js

@@ -14,8 +14,9 @@ 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 { sanitizeForLog } from "../../lib/utils/logSanitize.js";
 import { withTimeout } from "../../lib/utils/async/withTimeout.js";
 import { formatUptime, isProcessRunning, StateFileManager, } from "../utils/serverUtils.js";
 import { configureProxyKeepAliveDispatcher } from "../../lib/proxy/proxyDispatcher.js";
@@ -25,7 +26,9 @@ import { beginProxyRequest, getProxyActivitySnapshot, trackProxyResponse, } from
 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 { openProxyWorkerLog } from "../../lib/proxy/workerLog.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";
@@ -34,6 +37,8 @@ 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
 // =============================================================================
@@ -370,16 +375,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
@@ -499,18 +540,14 @@ function spawnFailOpenGuard(host, port, parentPid) {
         String(parentPid),
         "--quiet",
     ];
-    // Write guard stdout/stderr to a log file instead of discarding them.
-    const { openSync, closeSync, mkdirSync, existsSync } = _require("fs");
-    const guardLogDir = join(homedir(), ".neurolink", "logs");
-    if (!existsSync(guardLogDir)) {
-        mkdirSync(guardLogDir, { recursive: true });
-    }
-    const guardLogPath = join(guardLogDir, "proxy-guard.log");
-    const logFd = openSync(guardLogPath, "a");
+    const workerLog = openProxyWorkerLog("proxy-guard.log");
+    if (workerLog.error) {
+        logger.debug(`[proxy] guard logging disabled: ${workerLog.error}`);
+    }
     try {
         const child = spawn(process.execPath, args, {
             detached: true,
-            stdio: ["ignore", logFd, logFd],
+            stdio: ["ignore", workerLog.stdio, workerLog.stdio],
         });
         child.unref();
         return child.pid;
@@ -520,7 +557,7 @@ function spawnFailOpenGuard(host, port, parentPid) {
         return undefined;
     }
     finally {
-        closeSync(logFd); // parent closes its copy; child keeps the fd
+        workerLog.close();
     }
 }
 function spawnProxyUpdater(host, port, parentPid) {
@@ -546,17 +583,18 @@ function spawnProxyUpdater(host, port, parentPid) {
         "--updater-only",
         "--quiet",
     ];
-    const { openSync, closeSync, mkdirSync, existsSync } = _require("fs");
-    const logsDir = join(homedir(), ".neurolink", "logs");
-    if (!existsSync(logsDir)) {
-        mkdirSync(logsDir, { recursive: true });
+    const workerLog = openProxyWorkerLog("proxy-updater.log");
+    if (workerLog.error) {
+        logger.always(`[proxy] updater logging disabled: ${workerLog.error}`);
     }
-    const logFd = openSync(join(logsDir, "proxy-updater.log"), "a");
     try {
         const child = spawn(process.execPath, args, {
             detached: true,
-            stdio: ["ignore", logFd, logFd],
-            env: process.env,
+            stdio: ["ignore", workerLog.stdio, workerLog.stdio],
+            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}`);
@@ -572,7 +610,7 @@ function spawnProxyUpdater(host, port, parentPid) {
         return undefined;
     }
     finally {
-        closeSync(logFd);
+        workerLog.close();
     }
 }
 async function runProxyTelemetryManager(command) {
@@ -727,7 +765,7 @@ async function createProxyNeurolinkRuntime(logsDir) {
     cleanupLogs(7, 500);
     return { neurolink, cleanupLogs };
 }
-function registerProxyRequestTracking(app, requestMetadata) {
+function registerProxyRequestTracking(app, requestMetadata, readiness) {
     app.use("/v1/*", async (c, next) => {
         const startedMonotonicMs = performance.now();
         const contentLengthHeader = c.req.raw.headers.get("content-length");
@@ -747,9 +785,12 @@ function registerProxyRequestTracking(app, requestMetadata) {
             model: "-",
             stream: false,
             toolCount: 0,
+            rejectForUpdate: readiness.drainingForUpdate,
         };
         requestMetadata.set(c.req.raw, metadata);
-        const finishActivity = beginProxyRequest();
+        const finishActivity = metadata.rejectForUpdate
+            ? () => undefined
+            : beginProxyRequest();
         const finish = () => {
             finishActivity();
             requestMetadata.delete(c.req.raw);
@@ -924,7 +965,34 @@ export async function createProxyStartApp(params) {
             },
         }, 502);
     });
-    registerProxyRequestTracking(app, requestMetadata);
+    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);
+            }
+        }
+        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()
@@ -940,6 +1008,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;
@@ -970,13 +1056,13 @@ 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";
                 metadata.toolCount = toolCount;
             }
-            logger.always(`[proxy] ${c.req.method} ${c.req.path} → model=${model} ${stream} tools=${toolCount}`);
+            const logModel = sanitizeForLog(String(model));
+            logger.always(`[proxy] ${c.req.method} ${c.req.path} → model=${logModel} ${stream} tools=${toolCount}`);
             const ctx = {
                 requestId: metadata?.requestId ?? crypto.randomUUID(),
                 method: c.req.method,
@@ -1175,6 +1261,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,
@@ -1978,6 +2065,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)) {
@@ -2057,6 +2145,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}`)}`);
                 }
@@ -2239,6 +2333,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
@@ -2261,6 +2359,7 @@ export const proxyGuardCommand = {
         let guardStopping = false;
         let updateCheckTimeout;
         let updateCheckInterval;
+        let updateRetryTimeout;
         const stopUpdateChecks = () => {
             guardStopping = true;
             if (updateCheckTimeout) {
@@ -2271,6 +2370,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) => {
@@ -2289,41 +2392,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}`;
@@ -2396,22 +2551,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;
@@ -2432,6 +2573,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();
@@ -2473,9 +2615,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>;

package/dist/cli/commands/proxyAnalyze.js

@@ -0,0 +1,147 @@
+import chalk from "chalk";
+import { analyzeProxyLogs } from "../../lib/proxy/proxyAnalysis.js";
+import { logger } from "../../lib/utils/logger.js";
+function formatLatency(label, summary) {
+    const value = (amount) => amount === null ? "-" : amount.toFixed(1);
+    return `${label.padEnd(22)} ${String(summary.count).padStart(7)} ${value(summary.p50).padStart(9)} ${value(summary.p95).padStart(9)} ${value(summary.p99).padStart(9)} ${value(summary.max).padStart(9)}`;
+}
+function printAnalysis(report) {
+    logger.always("");
+    logger.always(chalk.bold.cyan("NeuroLink Proxy Analysis"));
+    logger.always(chalk.gray("=".repeat(50)));
+    logger.always(`  Since:       ${chalk.cyan(report.since)}`);
+    logger.always(`  Logs:        ${chalk.cyan(report.logsDir)}`);
+    logger.always(`  Files:       ${report.files.requests} request, ${report.files.attempts} attempt, ${report.files.lifecycle} lifecycle`);
+    logger.always("");
+    logger.always(chalk.bold("  Reliability"));
+    logger.always(report.coverage.finalRequests
+        ? `    Completed: ${report.requests.completed} (${chalk.green(`${report.requests.success} success`)}, ${chalk.red(`${report.requests.errors} errors`)})`
+        : chalk.yellow("    Completed: unavailable (no final request logs)"));
+    logger.always(report.coverage.attempts && report.coverage.finalRequests
+        ? `    Recovered after retry: ${report.requests.recoveredAfterRetry}`
+        : chalk.yellow("    Recovered after retry: unavailable"));
+    if (report.requests.errors > 0) {
+        logger.always(`    Final error types: ${JSON.stringify(report.requests.errorTypes)}`);
+    }
+    if (report.coverage.attempts) {
+        logger.always(`    Attempts: ${report.attempts.total}, ${report.attempts.errors} errors${report.attempts.errors > 0 ? ` ${JSON.stringify(report.attempts.errorTypes)}` : ""}`);
+    }
+    logger.always(report.coverage.lifecycle
+        ? `    Lifecycle: ${report.lifecycle.accepted} accepted, ${report.lifecycle.terminal} terminal, ${report.lifecycle.unsettled} unsettled`
+        : chalk.yellow("    Lifecycle: unavailable (no lifecycle metadata)"));
+    if (report.coverage.attempts) {
+        const finalRateLimits = report.coverage.finalRequests
+            ? `${report.requests.finalRateLimits} final`
+            : "final unavailable";
+        logger.always(`    Rate limits: ${report.rateLimits.attemptRateLimits} attempts (${report.rateLimits.quota} quota, ${report.rateLimits.transient} transient, ${report.rateLimits.unclassified} unclassified), ${finalRateLimits}`);
+    }
+    else if (report.coverage.finalRequests) {
+        logger.always(chalk.yellow(`    Rate limits: attempt classification unavailable; ${report.requests.finalRateLimits} final 429 response(s)`));
+    }
+    else {
+        logger.always(chalk.yellow("    Rate limits: unavailable"));
+    }
+    logger.always("");
+    logger.always(chalk.bold("  Latency (ms)"));
+    const latencyHeader = `${"METRIC".padEnd(22)} ${"COUNT".padStart(7)} ${"P50".padStart(9)} ${"P95".padStart(9)} ${"P99".padStart(9)} ${"MAX".padStart(9)}`;
+    logger.always(`    ${chalk.gray(latencyHeader)}`);
+    logger.always(`    ${chalk.gray("-".repeat(latencyHeader.length))}`);
+    for (const [label, summary] of [
+        ["Response headers", report.latencyMs.headers],
+        ["First chunk", report.latencyMs.firstChunk],
+        ["Terminal", report.latencyMs.terminal],
+        ["Final request log", report.latencyMs.finalRequest],
+        ["Account attempt", report.latencyMs.attempt],
+        ["Single-attempt delta", report.latencyMs.singleAttemptDelta],
+    ]) {
+        logger.always(`    ${formatLatency(label, summary)}`);
+    }
+    logger.always("");
+    logger.always(chalk.bold("  Cache"));
+    if (report.coverage.cacheUsage) {
+        logger.always(`    Usage records: ${report.cache.requestsWithUsage}, cache-read requests: ${report.cache.requestsWithCacheRead}, hit rate: ${report.cache.requestHitRate === null ? "-" : `${(report.cache.requestHitRate * 100).toFixed(1)}%`}`);
+        logger.always(`    Tokens: ${report.cache.cacheReadTokens} read, ${report.cache.cacheCreationTokens} created, ${report.cache.inputTokens} input`);
+    }
+    else {
+        logger.always(chalk.yellow("    Cache usage: unavailable"));
+    }
+    logger.always("");
+    logger.always(chalk.bold("  Data Quality"));
+    logger.always(`    ${report.dataQuality.linesRead} lines scanned, ${report.dataQuality.malformedLines} malformed, ${report.dataQuality.unsupportedLifecycleLines} unsupported lifecycle, ${report.dataQuality.lifecycleSequenceGaps} sequence gaps, ${report.dataQuality.lifecycleSequenceDuplicates} duplicates`);
+    if (report.accounts.length > 0) {
+        logger.always("");
+        logger.always(chalk.bold("  Accounts"));
+        const header = `${"ACCOUNT".padEnd(30)} ${"AUTH".padEnd(8)} ${"ATTEMPT".padStart(8)} ${"ATT ERR".padStart(7)} ${"FINAL".padStart(7)} ${"FIN ERR".padStart(7)} ${"QUOTA".padStart(7)} ${"TRANS".padStart(7)} ${"UNKNOWN".padStart(8)}`;
+        logger.always(`    ${chalk.gray(header)}`);
+        logger.always(`    ${chalk.gray("-".repeat(header.length))}`);
+        for (const account of report.accounts) {
+            const attempt = report.coverage.attempts ? String(account.attempts) : "-";
+            const attemptErrors = report.coverage.attempts
+                ? String(account.attemptErrors)
+                : "-";
+            const quota = report.coverage.attempts
+                ? String(account.quotaRateLimits)
+                : "-";
+            const transient = report.coverage.attempts
+                ? String(account.transientRateLimits)
+                : "-";
+            const unknown = report.coverage.attempts
+                ? String(account.unclassifiedRateLimits)
+                : "-";
+            const finalRequests = report.coverage.finalRequests
+                ? String(account.finalRequests)
+                : "-";
+            const finalErrors = report.coverage.finalRequests
+                ? String(account.finalErrors)
+                : "-";
+            logger.always(`    ${account.account.slice(0, 30).padEnd(30)} ${account.accountType.slice(0, 8).padEnd(8)} ${attempt.padStart(8)} ${attemptErrors.padStart(7)} ${finalRequests.padStart(7)} ${finalErrors.padStart(7)} ${quota.padStart(7)} ${transient.padStart(7)} ${unknown.padStart(8)}`);
+        }
+    }
+    logger.always("");
+}
+export const proxyAnalyzeCommand = {
+    command: "analyze",
+    describe: "Analyze local proxy reliability and latency logs",
+    builder: (yargs) => yargs
+        .option("logs-dir", {
+        type: "string",
+        alias: "logsDir",
+        description: "Proxy JSONL log directory",
+    })
+        .option("since", {
+        type: "string",
+        default: "24h",
+        description: "ISO timestamp or lookback such as 6h, 1d, or 1w",
+    })
+        .option("format", {
+        type: "string",
+        choices: ["text", "json"],
+        default: "text",
+        description: "Output format",
+    })
+        .option("quiet", {
+        type: "boolean",
+        alias: "q",
+        default: false,
+        description: "Suppress non-essential output",
+    })
+        .example("neurolink proxy analyze --since 24h", "Analyze the last 24 hours of proxy logs"),
+    handler: async (argv) => {
+        try {
+            const report = await analyzeProxyLogs({
+                logsDir: argv.logsDir,
+                since: argv.since,
+            });
+            if (argv.format === "json") {
+                logger.always(JSON.stringify(report, null, 2));
+                return;
+            }
+            printAnalysis(report);
+        }
+        catch (error) {
+            logger.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+            process.exitCode = 1;
+        }
+    },
+};
+//# sourceMappingURL=proxyAnalyze.js.map