@juspay/neurolink 9.87.3 → 9.87.4

package/dist/cli/commands/proxy.js

@@ -19,6 +19,8 @@ import { logger } from "../../lib/utils/logger.js";
 import { formatUptime, isProcessRunning, StateFileManager, } from "../utils/serverUtils.js";
 import { configureProxyKeepAliveDispatcher } from "../../lib/proxy/proxyDispatcher.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 { describeInstallFailure, getGlobalInstallArgs, resolveGlobalInstaller, } from "../../lib/proxy/globalInstaller.js";
 import { loadProxyEnvFile, resolveProxyEnvFile, } from "../../lib/proxy/proxyEnv.js";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
@@ -137,7 +139,7 @@ function isLaunchdManagedProcess() {
     return process.platform === "darwin" && process.ppid === 1;
 }
 function isProxyAutoUpdateEnabled(value = process.env.NEUROLINK_PROXY_AUTO_UPDATE) {
-    return ["1", "on", "true"].includes((value ?? "").trim().toLowerCase());
+    return !["0", "off", "false"].includes((value ?? "").trim().toLowerCase());
 }
 /** Keys we manage in Claude Code's settings.env */
 const PROXY_MANAGED_KEYS = ["ANTHROPIC_BASE_URL", "ENABLE_TOOL_SEARCH"];
@@ -338,6 +340,41 @@ async function isProxyHealthy(host, port, timeoutMs) {
         return false;
     }
 }
+async function getProxyRuntimeActivity(host, port, timeoutMs = 3_000) {
+    try {
+        const response = await fetch(`http://${host}:${port}/status`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const payload = (await response.json());
+        const activeRequests = Number(payload.activity?.activeRequests);
+        if (!Number.isFinite(activeRequests) || activeRequests < 0) {
+            return null;
+        }
+        return {
+            activeRequests,
+            lastActivityAt: typeof payload.activity?.lastActivityAt === "string"
+                ? payload.activity.lastActivityAt
+                : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isSafeUpdateWindow(activity, quietThresholdMs, nowMs = Date.now()) {
+    if (activity.activeRequests > 0) {
+        return false;
+    }
+    if (!activity.lastActivityAt) {
+        return true;
+    }
+    const lastActivityMs = Date.parse(activity.lastActivityAt);
+    return (Number.isFinite(lastActivityMs) &&
+        nowMs - lastActivityMs >= quietThresholdMs);
+}
 // ---------------------------------------------------------------------------
 // Stable entrypoint for launchd
 // ---------------------------------------------------------------------------
@@ -437,113 +474,6 @@ exit 127
     writeFileSync(TRAMPOLINE_PATH, script, { mode: 0o755 });
     chmodSync(TRAMPOLINE_PATH, 0o755);
 }
-/**
- * Check whether a pnpm binary can install into the global store.
- *
- * Multiple pnpm major versions can coexist (e.g., standalone v8 + nvm v10).
- * They use different store layouts (`store/v10` vs `store/v10/v3`), so a
- * pnpm that passes `--version` may still fail `pnpm add -g` with
- * ERR_PNPM_UNEXPECTED_STORE. We detect this by running `pnpm root -g` and
- * checking whether the resolved global root directory actually exists on disk.
- */
-function canInstallGlobally(pnpmPath) {
-    try {
-        const { execFileSync } = _require("node:child_process");
-        const { existsSync } = _require("fs");
-        const globalRoot = execFileSync(pnpmPath, ["root", "-g"], {
-            encoding: "utf8",
-            timeout: 10_000,
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-        // If the global root exists, this pnpm version is compatible with
-        // the current store layout and can install packages there.
-        return !!globalRoot && existsSync(globalRoot);
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Resolve the `pnpm` binary defensively.
- *
- * Tries multiple candidates in order of preference. Each candidate must:
- * 1. Respond to `pnpm --version` (binary works)
- * 2. Have a compatible global store (`pnpm root -g` points to an existing dir)
- *
- * This defends against environments with multiple pnpm major versions
- * (e.g., standalone v8 + nvm v10) where the wrong one would fail with
- * ERR_PNPM_UNEXPECTED_STORE on `pnpm add -g`.
- *
- * Honors `NEUROLINK_PNPM_PATH` as an escape hatch.
- */
-function resolveFullPnpmPath() {
-    const candidates = [];
-    // 1. User override
-    if (process.env.NEUROLINK_PNPM_PATH) {
-        candidates.push(process.env.NEUROLINK_PNPM_PATH);
-    }
-    // 2. PNPM_HOME (pnpm's own env variable)
-    if (process.env.PNPM_HOME) {
-        candidates.push(join(process.env.PNPM_HOME, "pnpm"));
-    }
-    // 3. `which pnpm` — whatever is on PATH
-    try {
-        const { execFileSync } = _require("node:child_process");
-        const whichOut = execFileSync("which", ["pnpm"], {
-            encoding: "utf8",
-            timeout: 5_000,
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-        if (whichOut) {
-            candidates.push(whichOut);
-        }
-    }
-    catch {
-        // ignore
-    }
-    // 4. Common standalone installer locations
-    candidates.push(join(homedir(), ".local", "share", "pnpm", "pnpm"));
-    candidates.push(join(homedir(), "Library", "pnpm", "pnpm"));
-    // Dedupe while preserving order
-    const seen = new Set();
-    const unique = candidates.filter((p) => {
-        if (!p || seen.has(p)) {
-            return false;
-        }
-        seen.add(p);
-        return true;
-    });
-    // Probe each candidate: must pass --version AND have a compatible global store
-    const tried = unique.map((path) => {
-        const version = probeBinVersion(path);
-        const working = version !== undefined;
-        const globalStoreOk = working ? canInstallGlobally(path) : false;
-        return { path, version, working, globalStoreOk };
-    });
-    // Prefer a candidate that can actually install globally
-    const fullyWorking = tried.find((r) => r.working && r.globalStoreOk);
-    if (fullyWorking) {
-        return {
-            bin: fullyWorking.path,
-            resolved: true,
-            version: fullyWorking.version,
-            tried,
-        };
-    }
-    // Fall back to any candidate that at least responds to --version
-    // (better than nothing — the install may still fail, but will be
-    // caught and suppressed by the caller)
-    const anyWorking = tried.find((r) => r.working);
-    if (anyWorking) {
-        return {
-            bin: anyWorking.path,
-            resolved: true,
-            version: anyWorking.version,
-            tried,
-        };
-    }
-    return { bin: "pnpm", resolved: false, tried };
-}
 function spawnFailOpenGuard(host, port, parentPid) {
     // The guard runs the same version as this process, so process.argv[1]
     // (the currently-running script) is correct here — no stale-path risk.
@@ -587,6 +517,52 @@ function spawnFailOpenGuard(host, port, parentPid) {
         closeSync(logFd); // parent closes its copy; child keeps the fd
     }
 }
+function spawnProxyUpdater(host, port, parentPid) {
+    if (!isProxyAutoUpdateEnabled()) {
+        logger.always("[proxy] automatic updates disabled by environment");
+        return undefined;
+    }
+    const entryScript = process.argv[1];
+    if (!entryScript) {
+        logger.always("[proxy] updater disabled: CLI entry script is unavailable");
+        return undefined;
+    }
+    const args = [
+        entryScript,
+        "proxy",
+        "guard",
+        "--host",
+        host,
+        "--port",
+        String(port),
+        "--parent-pid",
+        String(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 logFd = openSync(join(logsDir, "proxy-updater.log"), "a");
+    try {
+        const child = spawn(process.execPath, args, {
+            detached: true,
+            stdio: ["ignore", logFd, logFd],
+            env: process.env,
+        });
+        child.unref();
+        return child.pid;
+    }
+    catch (error) {
+        logger.always(`[proxy] updater failed to start: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    finally {
+        closeSync(logFd);
+    }
+}
 async function runProxyTelemetryManager(command) {
     const { existsSync } = await import("fs");
     if (!existsSync(PROXY_TELEMETRY_SCRIPT_PATH)) {
@@ -826,26 +802,100 @@ async function resolveBootPrimaryAccountKey(primaryEmail) {
     }
     return key;
 }
-async function createProxyStartApp(params) {
+export async function createProxyStartApp(params) {
     const { createClaudeProxyRoutes } = await import("../../lib/server/routes/claudeProxyRoutes.js");
     const { createOpenAIProxyRoutes } = await import("../../lib/server/routes/openaiProxyRoutes.js");
+    const { logBodyCapture, logRequest } = await import("../../lib/proxy/requestLogger.js");
+    const { recordFinalError } = await import("../../lib/proxy/usageStats.js");
     const { Hono } = await import("hono");
     const app = new Hono();
     const readiness = createProxyReadinessState();
-    app.onError((err, c) => {
+    const requestMetadata = new WeakMap();
+    const recordRuntimeError = async (metadata, status, errorType, errorMessage, clientMessage = errorMessage, clientErrorType = errorType) => {
+        recordFinalError(status);
+        await Promise.all([
+            logRequest({
+                timestamp: new Date().toISOString(),
+                requestId: metadata.requestId,
+                method: metadata.method,
+                path: metadata.path,
+                model: metadata.model,
+                stream: metadata.stream,
+                toolCount: metadata.toolCount,
+                account: "",
+                accountType: "proxy-runtime",
+                responseStatus: status,
+                responseTimeMs: Date.now() - metadata.startedAt,
+                errorType,
+                errorMessage,
+            }),
+            logBodyCapture({
+                timestamp: new Date().toISOString(),
+                requestId: metadata.requestId,
+                model: metadata.model,
+                stream: metadata.stream,
+                phase: "client_response",
+                headers: { "content-type": "application/json" },
+                body: {
+                    type: "error",
+                    error: { type: clientErrorType, message: clientMessage },
+                },
+                contentType: "application/json",
+                responseStatus: status,
+                durationMs: Date.now() - metadata.startedAt,
+            }),
+        ]);
+    };
+    app.onError(async (err, c) => {
         const errMsg = err instanceof Error ? err.message : String(err);
         logger.always(`[proxy] unhandled error: ${errMsg}`);
         if (err instanceof Error && err.stack) {
-            logger.debug(`[proxy] stack: ${err.stack}`);
-        }
+            logger.always(`[proxy] unhandled stack: ${err.stack}`);
+        }
+        const metadata = requestMetadata.get(c.req.raw) ?? {
+            requestId: crypto.randomUUID(),
+            method: c.req.method,
+            path: c.req.path,
+            startedAt: Date.now(),
+            model: "-",
+            stream: false,
+            toolCount: 0,
+        };
+        await recordRuntimeError(metadata, 502, "unhandled_proxy_error", errMsg, "Proxy internal error", "api_error");
+        requestMetadata.delete(c.req.raw);
         return c.json({
             type: "error",
             error: {
                 type: "api_error",
-                message: `Proxy internal error: ${errMsg}`,
+                message: "Proxy internal error",
             },
         }, 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);
+        }
+        catch (error) {
+            finishActivity();
+            throw error;
+        }
+    });
     const routeGroup = createClaudeProxyRoutes(params.modelRouter, "", params.strategy, params.passthrough, params.primaryAccountKey, params.accountAllowlist);
     const openaiRouteGroup = createOpenAIProxyRoutes(params.modelRouter, "", params.port);
     const allProxyRoutes = [...routeGroup.routes, ...openaiRouteGroup.routes];
@@ -861,6 +911,10 @@ async function createProxyStartApp(params) {
                     body = rawBody ? JSON.parse(rawBody) : emptyBody;
                 }
                 catch {
+                    const metadata = requestMetadata.get(c.req.raw);
+                    if (metadata) {
+                        await recordRuntimeError(metadata, 400, "invalid_request_error", "Request body must be valid JSON");
+                    }
                     return c.json({
                         type: "error",
                         error: {
@@ -878,9 +932,15 @@ 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 ctx = {
-                requestId: crypto.randomUUID(),
+                requestId: metadata?.requestId ?? crypto.randomUUID(),
                 method: c.req.method,
                 path: c.req.path,
                 headers: Object.fromEntries(c.req.raw.headers.entries()),
@@ -973,6 +1033,7 @@ async function createProxyStartApp(params) {
         const { getStats } = await import("../../lib/proxy/usageStats.js");
         const { loadAccountCooldowns } = await import("../../lib/proxy/accountCooldown.js");
         const stats = getStats();
+        const runtimeState = loadProxyState();
         const cooldowns = await loadAccountCooldowns();
         const storedAccountKeys = new Set();
         try {
@@ -1031,6 +1092,20 @@ async function createProxyStartApp(params) {
                 }),
                 primaryAccount,
             },
+            activity: (() => {
+                const activity = getProxyActivitySnapshot();
+                return {
+                    activeRequests: activity.activeRequests,
+                    lastActivityAt: activity.lastActivityAt?.toISOString() ?? null,
+                };
+            })(),
+            autoUpdate: {
+                enabled: isProxyAutoUpdateEnabled(),
+                updaterPid: runtimeState?.updaterPid ?? null,
+                updaterRunning: runtimeState?.updaterPid
+                    ? isProcessRunning(runtimeState.updaterPid)
+                    : false,
+            },
             config: params.proxyConfig
                 ? {
                     hasRouting: !!params.proxyConfig.routing,
@@ -1354,6 +1429,9 @@ async function startProxyRuntime(params) {
         port: params.port,
     });
     markProxyReady(params.readiness);
+    const updaterPid = managedByLaunchd && !params.argv.dev
+        ? spawnProxyUpdater(readinessHost, params.port, process.pid)
+        : undefined;
     const fallbackChain = params.proxyConfig?.routing?.fallbackChain?.map((entry) => ({
         provider: entry.provider,
         model: entry.model,
@@ -1376,6 +1454,7 @@ async function startProxyRuntime(params) {
             ? [...params.accountAllowlist]
             : undefined,
         guardPid,
+        updaterPid,
         managedBy: managedByLaunchd ? "launchd" : "manual",
         passthrough: params.passthrough,
     });
@@ -1643,6 +1722,9 @@ export const proxyStatusCommand = {
                 envFile: null,
                 fallbackChain: null,
                 accountAllowlist: null,
+                autoUpdateEnabled: isProxyAutoUpdateEnabled(),
+                updaterPid: null,
+                updaterRunning: false,
             };
             if (state && isProcessRunning(state.pid)) {
                 status.running = true;
@@ -1657,6 +1739,10 @@ export const proxyStatusCommand = {
                 status.envFile = state.envFile ?? null;
                 status.fallbackChain = state.fallbackChain ?? null;
                 status.accountAllowlist = state.accountAllowlist ?? null;
+                status.updaterPid = state.updaterPid ?? null;
+                status.updaterRunning = state.updaterPid
+                    ? isProcessRunning(state.updaterPid)
+                    : false;
             }
             // Fetch live stats before rendering (JSON or text)
             let liveStats = null;
@@ -1689,6 +1775,7 @@ export const proxyStatusCommand = {
                 logger.always(`  ${chalk.bold("Mode:")}       ${chalk.cyan(status.mode ?? "full")}`);
                 logger.always(`  ${chalk.bold("Started:")}    ${chalk.cyan(status.startTime)}`);
                 logger.always(`  ${chalk.bold("Uptime:")}     ${chalk.cyan(formatUptime(status.uptime ?? 0))}`);
+                logger.always(`  ${chalk.bold("Auto-update:")} ${status.autoUpdateEnabled ? chalk.green(status.updaterRunning ? `enabled (PID ${status.updaterPid})` : "enabled (worker unavailable)") : chalk.yellow("disabled")}`);
                 if (status.envFile) {
                     logger.always(`  ${chalk.bold("Env File:")}   ${chalk.cyan(status.envFile)}`);
                 }
@@ -1836,6 +1923,11 @@ export const proxyGuardCommand = {
             type: "number",
             alias: "pollIntervalMs",
             default: 1_000,
+        })
+            .option("updater-only", {
+            type: "boolean",
+            alias: "updaterOnly",
+            default: false,
         })
             .option("quiet", {
             type: "boolean",
@@ -1852,11 +1944,12 @@ export const proxyGuardCommand = {
             : 0;
         const failureThreshold = Math.max(1, Number(argv.failureThreshold ?? 5));
         const pollIntervalMs = Math.max(250, Number(argv.pollIntervalMs ?? 1_000));
+        const updaterOnly = argv.updaterOnly === true;
         if (!Number.isFinite(parentPid) || parentPid <= 0) {
             return;
         }
-        // Automatic package mutation is disabled by default. Operators must opt in
-        // explicitly, and launchd-managed proxy processes do not spawn this guard.
+        // Package mutation belongs to the dedicated launchd updater worker. The
+        // 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 UPDATE_TIMEOUT_MS = 30 * 1000; // 30 seconds to come healthy
@@ -1874,7 +1967,8 @@ export const proxyGuardCommand = {
         }
         // Auto-update only works on macOS with launchd. On other platforms,
         // there's no restart mechanism, so skip the update loop entirely.
-        const canAutoUpdate = isProxyAutoUpdateEnabled() &&
+        const canAutoUpdate = updaterOnly &&
+            isProxyAutoUpdateEnabled() &&
             process.platform === "darwin" &&
             (await isLaunchdManaging());
         let guardStopping = false;
@@ -1901,7 +1995,6 @@ export const proxyGuardCommand = {
             try {
                 // Lazy-load update modules so they're only imported at check time
                 const { checkForUpdate } = await import("../../lib/proxy/updateChecker.js");
-                const { checkTrafficQuiet } = await import("../../lib/proxy/quietDetector.js");
                 const { recordCheck, isVersionSuppressed, suppressVersion, recordSuccessfulUpdate, } = await import("../../lib/proxy/updateState.js");
                 // 1. Check for update
                 const result = await checkForUpdate(runningVersion);
@@ -1913,141 +2006,111 @@ export const proxyGuardCommand = {
                     logger.debug(`[guard] version ${result.latestVersion} is suppressed, skipping`);
                     return;
                 }
-                logger.always(`[guard] update available: ${runningVersion} → ${result.latestVersion}`);
-                // 2. Best-effort quiet wait — try for a brief window, but proceed
-                //    regardless. The install (pnpm add -g) is non-disruptive; only the
-                //    restart causes a ~1-3s blip. Blocking updates for hours/days because
-                //    traffic never goes silent is worse than a brief interruption.
-                const maxQuietWaitMs = 5 * 60 * 1000; // 5 minutes max, then proceed
+                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
-                const quietStart = Date.now();
-                while (Date.now() - quietStart < maxQuietWaitMs) {
+                while (!guardStopping) {
                     if (getProcessStatus(parentPid) === "not_running") {
-                        logger.always(`[guard] parent process died during quiet-wait, aborting update`);
+                        logger.always(`[updater] parent process died while waiting for idle traffic`);
                         return;
                     }
-                    const quietStatus = checkTrafficQuiet(QUIET_THRESHOLD_MS);
-                    if (quietStatus.isQuiet) {
-                        logger.always(`[guard] traffic quiet, proceeding with update`);
+                    const activity = await getProxyRuntimeActivity(host, port);
+                    if (activity && isSafeUpdateWindow(activity, QUIET_THRESHOLD_MS)) {
+                        logger.always(`[updater] traffic idle, proceeding with update`);
                         break;
                     }
-                    logger.debug(`[guard] traffic active (last activity ${Math.round(quietStatus.silenceDurationMs / 1000)}s ago), waiting...`);
+                    logger.debug(`[updater] waiting for idle traffic (${activity?.activeRequests ?? "unknown"} active requests)`);
                     await new Promise((r) => setTimeout(r, quietPollMs));
                 }
-                // Proceed with install regardless — don't block updates indefinitely.
-                // The install itself (pnpm add -g) doesn't affect the running process.
-                // Only the restart afterwards causes a brief interruption.
-                const finalQuiet = checkTrafficQuiet(QUIET_THRESHOLD_MS);
-                if (!finalQuiet.isQuiet) {
-                    logger.always(`[guard] traffic still active after ${Math.round(maxQuietWaitMs / 1000)}s wait, proceeding with update anyway (restart will briefly interrupt in-flight requests)`);
+                if (guardStopping) {
+                    return;
                 }
                 // 3. Install update (validate version string before passing to shell)
                 if (!/^\d+\.\d+\.\d+$/.test(result.latestVersion)) {
                     logger.always(`[guard] WARNING: invalid version format "${result.latestVersion}", skipping`);
                     return;
                 }
-                // Resolve pnpm to a deterministic path, validating that it actually
-                // runs (some environments have broken shims on PATH).
-                const pnpmResolution = resolveFullPnpmPath();
-                // Log the full candidate list so operators can see why a particular
-                // pnpm was chosen (or why none worked).
-                logger.always(`[guard] pnpm candidates: ${pnpmResolution.tried
-                    .map((c) => `${c.path}(${c.working ? `v${c.version}` : "BROKEN"})`)
+                const installerResolution = resolveGlobalInstaller({
+                    entryScript: process.argv[1],
+                });
+                logger.always(`[updater] package-manager candidates: ${installerResolution.tried
+                    .map((candidate) => `${candidate.kind}:${candidate.bin}(${candidate.installable ? `v${candidate.version}` : (candidate.reason ?? "unusable")})`)
                     .join(", ")}`);
-                if (!pnpmResolution.resolved) {
-                    // Environmental problem, not version-specific — skip this cycle
-                    // without suppressing the version (so we retry on the next tick
-                    // once the user fixes pnpm).
-                    logger.always(`[guard] WARNING: no working pnpm found; skipping update cycle. Install pnpm or set NEUROLINK_PNPM_PATH.`);
+                const installer = installerResolution.installer;
+                if (!installer) {
+                    logger.always(`[updater] WARNING: no package manager has a writable global root and executable directory; skipping this cycle`);
                     return;
                 }
-                logger.always(`[guard] traffic quiet, installing @juspay/neurolink@${result.latestVersion} via ${pnpmResolution.bin} (pnpm v${pnpmResolution.version})...`);
+                logger.always(`[updater] installing @juspay/neurolink@${result.latestVersion} via ${installer.kind} ${installer.bin} (v${installer.version})`);
                 if (guardStopping || getProcessStatus(parentPid) === "not_running") {
                     return;
                 }
                 const { execFileSync } = await import("node:child_process");
                 try {
-                    execFileSync(pnpmResolution.bin, ["add", "-g", `@juspay/neurolink@${result.latestVersion}`], {
+                    execFileSync(installer.bin, getGlobalInstallArgs(installer.kind, `@juspay/neurolink@${result.latestVersion}`), {
                         timeout: 120_000,
                         stdio: "pipe",
                     });
                 }
                 catch (installErr) {
-                    // Capture stderr for actionable diagnostics
-                    const stderr = installErr &&
-                        typeof installErr === "object" &&
-                        "stderr" in installErr
-                        ? String(installErr.stderr).slice(0, 500)
-                        : "";
-                    const msg = installErr instanceof Error
-                        ? installErr.message
-                        : String(installErr);
-                    logger.always(`[guard] WARNING: pnpm install failed: ${msg}${stderr ? `\n  stderr: ${stderr}` : ""}`);
-                    suppressVersion(result.latestVersion, `install_failed: ${msg.slice(0, 200)}${stderr ? ` | stderr: ${stderr.slice(0, 200)}` : ""}`);
+                    const detail = describeInstallFailure(installErr);
+                    logger.always(`[updater] WARNING: global install failed:\n${detail}`);
                     return;
                 }
-                // 4. Rewrite the launchd plist so it picks up the (possibly new)
-                //    stable bin path, then restart via launchctl.
+                // 4. Refresh and validate the stable trampoline. The plist already
+                // points at this path, so it must not be unloaded or rewritten here.
                 try {
-                    const { writeFileSync, existsSync: fsExists, mkdirSync: fsMkdir, } = await import("fs");
-                    if (!fsExists(PLIST_DIR)) {
-                        fsMkdir(PLIST_DIR, { recursive: true });
-                    }
-                    // Rewrite the trampoline and plist so the restarted service
-                    // resolves the newly installed binary via PATH.
                     writeTrampoline();
                     // Validate the trampoline actually resolves to the NEW version
                     // before asking launchd to restart. If the install somehow left
                     // PATH still pointing at the old version, don't kickstart.
                     const probed = probeBinVersion(TRAMPOLINE_PATH);
                     if (!probed) {
-                        logger.always(`[guard] WARNING: trampoline does not resolve to a working neurolink after install; skipping restart.`);
+                        logger.always(`[updater] WARNING: trampoline does not resolve to a working neurolink after install; skipping restart`);
                         suppressVersion(result.latestVersion, `trampoline_broken_after_install: ${TRAMPOLINE_PATH} --version failed`);
                         return;
                     }
                     if (probed !== result.latestVersion) {
-                        // The trampoline resolves to a DIFFERENT version than what we
-                        // just installed. This means `pnpm add -g` installed into a
-                        // store that PATH doesn't reach (store mismatch), or PATH still
-                        // shadows with an older shim. Restarting would run the wrong
-                        // version — abort.
-                        logger.always(`[guard] ABORT: trampoline resolves to v${probed} but installed v${result.latestVersion}.`);
-                        logger.always(`[guard]   pnpm used: ${pnpmResolution.bin} (v${pnpmResolution.version})`);
-                        logger.always(`[guard]   This usually means pnpm's global store doesn't match the PATH-visible neurolink.`);
-                        logger.always(`[guard]   Fix: run 'pnpm add -g @juspay/neurolink' with the SAME pnpm whose bin dir is on PATH.`);
-                        suppressVersion(result.latestVersion, `version_mismatch: trampoline=${probed} expected=${result.latestVersion} pnpm=${pnpmResolution.bin}(v${pnpmResolution.version})`);
+                        logger.always(`[updater] ABORT: trampoline resolves to v${probed} but installed v${result.latestVersion}`);
+                        logger.always(`[updater] installer used: ${installer.kind} ${installer.bin} (v${installer.version})`);
+                        suppressVersion(result.latestVersion, `version_mismatch: trampoline=${probed} expected=${result.latestVersion} installer=${installer.kind}:${installer.bin}(v${installer.version})`);
                         return;
                     }
-                    const existingArgs = parseExistingPlistArgs();
-                    const updatedPlist = buildPlist(port, host, existingArgs.envFile, existingArgs.configFile);
-                    writeFileSync(PLIST_PATH, updatedPlist, "utf-8");
-                    logger.always(`[guard] trampoline (resolves to v${probed}) + plist rewritten at ${PLIST_PATH}`);
+                    logger.always(`[updater] trampoline validated at v${probed}`);
                 }
-                catch (plistErr) {
-                    logger.always(`[guard] WARNING: failed to rewrite plist (restart may use stale path): ${plistErr instanceof Error ? plistErr.message : String(plistErr)}`);
-                    // Continue with restart anyway — the stable bin symlink may still be correct
+                catch (trampolineError) {
+                    logger.always(`[updater] WARNING: failed to refresh trampoline; refusing restart: ${trampolineError instanceof Error
+                        ? trampolineError.message
+                        : String(trampolineError)}`);
+                    return;
                 }
                 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;
+                }
                 // Signal the health loop to not exit when it detects
                 // the parent PID is gone — we're intentionally restarting.
                 updateRestartInProgress = true;
-                logger.always(`[guard] restarting proxy via launchctl bootout/bootstrap...`);
+                logger.always(`[updater] restarting proxy via launchctl kickstart`);
                 const uid = process.getuid?.() ?? 501;
                 try {
-                    // bootout unloads the in-memory job definition. This is required
-                    // because a forced kickstart reuses the cached plist and ignores any
-                    // on-disk changes (like the trampoline rewrite above).
-                    try {
-                        execFileSync("launchctl", ["bootout", `gui/${uid}/${PLIST_LABEL}`], { timeout: 10_000, stdio: "pipe" });
-                    }
-                    catch {
-                        // Job may not be loaded (first install, or already unloaded)
-                    }
-                    // bootstrap loads the plist fresh from disk, picking up the
-                    // new trampoline-based ProgramArguments.
-                    execFileSync("launchctl", ["bootstrap", `gui/${uid}`, PLIST_PATH], {
+                    execFileSync("launchctl", ["kickstart", "-k", `gui/${uid}/${PLIST_LABEL}`], {
                         timeout: 10_000,
                         stdio: "pipe",
                     });
@@ -2057,8 +2120,7 @@ export const proxyGuardCommand = {
                     const msg = restartErr instanceof Error
                         ? restartErr.message
                         : String(restartErr);
-                    logger.always(`[guard] WARNING: launchctl bootstrap failed: ${msg}`);
-                    suppressVersion(result.latestVersion, `restart_failed: ${msg.slice(0, 200)}`);
+                    logger.always(`[updater] WARNING: launchctl kickstart failed: ${msg}`);
                     return;
                 }
                 // 5. Wait for healthy restart
@@ -2083,19 +2145,19 @@ export const proxyGuardCommand = {
                     }
                 }
                 if (healthy) {
-                    logger.always(`[guard] update successful: now running ${result.latestVersion}`);
+                    logger.always(`[updater] update successful: now running ${result.latestVersion}`);
                     recordSuccessfulUpdate(result.latestVersion);
-                    // The new proxy will spawn its own guard. Exit this one.
+                    // The replacement proxy starts a worker running the new version.
                     process.exit(0);
                 }
                 else {
-                    logger.always(`[guard] WARNING: proxy unhealthy after update to ${result.latestVersion}`);
+                    logger.always(`[updater] WARNING: proxy unhealthy after update to ${result.latestVersion}`);
                     suppressVersion(result.latestVersion, "unhealthy_after_restart");
                     updateRestartInProgress = false;
                 }
             }
             catch (err) {
-                logger.always(`[guard] update check error: ${err instanceof Error ? err.message : String(err)}`);
+                logger.always(`[updater] update check error: ${err instanceof Error ? err.message : String(err)}`);
             }
             finally {
                 updateInProgress = false;
@@ -2127,7 +2189,9 @@ export const proxyGuardCommand = {
                 }
                 break;
             }
-            if (!healthy && consecutiveUnhealthy >= failureThreshold) {
+            if (!updateRestartInProgress &&
+                !healthy &&
+                consecutiveUnhealthy >= failureThreshold) {
                 // A detached guard cannot safely decide that a live process should be
                 // replaced. Leave recovery to the foreground operator or launchd.
                 if (!argv.quiet) {
@@ -2144,6 +2208,9 @@ export const proxyGuardCommand = {
             parentStatus = getProcessStatus(parentPid);
         }
         stopUpdateChecks();
+        if (updaterOnly) {
+            return;
+        }
         const guardHost = host === "0.0.0.0" ? "localhost" : host;
         const expectedBaseUrl = `http://${guardHost}:${port}`;
         // The parent is confirmed gone and no replacement is healthy. Foreground
@@ -2335,36 +2402,6 @@ function buildLaunchdPath() {
     }
     return [...segments].join(":");
 }
-/**
- * Parse the existing launchd plist to extract --env-file and --config values.
- * Used by the auto-updater to rewrite the plist with the same configuration.
- */
-function parseExistingPlistArgs() {
-    try {
-        const { readFileSync, existsSync: fsExists } = _require("fs");
-        if (!fsExists(PLIST_PATH)) {
-            return {};
-        }
-        const xml = readFileSync(PLIST_PATH, "utf-8");
-        // Extract --env-file value: <string>--env-file</string>\n    <string>VALUE</string>
-        const envMatch = xml.match(/<string>--env-file<\/string>\s*<string>([^<]+)<\/string>/);
-        const configMatch = xml.match(/<string>--config<\/string>\s*<string>([^<]+)<\/string>/);
-        // Unescape XML entities so buildPlist() doesn't double-escape them.
-        const unescapeXml = (value) => value
-            ?.replace(/&apos;/g, "'")
-            .replace(/&quot;/g, '"')
-            .replace(/&gt;/g, ">")
-            .replace(/&lt;/g, "<")
-            .replace(/&amp;/g, "&");
-        return {
-            envFile: unescapeXml(envMatch?.[1]),
-            configFile: unescapeXml(configMatch?.[1]),
-        };
-    }
-    catch {
-        return {};
-    }
-}
 function buildPlist(port, host, envFile, configFile) {
     // The plist invokes the trampoline script (a tiny shell wrapper at
     // ~/.neurolink/bin/neurolink-proxy) which re-resolves the real