@juspay/neurolink 9.93.1 → 9.94.0

package/dist/cli/commands/proxy.js

@@ -16,6 +16,7 @@ import chalk from "chalk";
 import ora from "ora";
 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,6 +26,11 @@ 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 { openProxyWorkerLog } from "../../lib/proxy/workerLog.js";
+import { startRollingProxyServer } from "../../lib/proxy/rollingProxyServer.js";
+import { spawnProxySocketWorker } from "../../lib/proxy/rollingWorkerProcess.js";
+import { PROXY_ROLLING_SUPERVISOR_ENV, PROXY_SOCKET_WORKER_ENV, } from "../../lib/proxy/rollingWorkerProtocol.js";
+import { attachSocketWorkerProcess } from "../../lib/proxy/socketWorkerRuntime.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";
@@ -41,12 +47,14 @@ const PROXY_UPDATE_CONTROL_TOKEN = process.env.NEUROLINK_PROXY_UPDATE_CONTROL_TO
 // STATE MANAGEMENT
 // =============================================================================
 let proxyStateManager = new StateFileManager("proxy-state.json");
+let proxySupervisorStateManager = new StateFileManager("proxy-supervisor-state.json");
 /**
  * Reinitialise the state manager with a custom base directory.
  * Called when --dev redirects writable paths to .neurolink-dev/.
  */
 function setProxyStateDir(baseDir) {
     proxyStateManager = new StateFileManager("proxy-state.json", baseDir);
+    proxySupervisorStateManager = new StateFileManager("proxy-supervisor-state.json", baseDir);
 }
 function saveProxyState(state) {
     proxyStateManager.save(state);
@@ -57,6 +65,15 @@ function loadProxyState() {
 function clearProxyState() {
     proxyStateManager.clear();
 }
+function saveProxySupervisorState(state) {
+    proxySupervisorStateManager.save(state);
+}
+function loadProxySupervisorState() {
+    return proxySupervisorStateManager.load();
+}
+function clearProxySupervisorState() {
+    proxySupervisorStateManager.clear();
+}
 const CLAUDE_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
 const PLIST_LABEL = "com.neurolink.proxy";
 const PLIST_DIR = join(homedir(), "Library", "LaunchAgents");
@@ -80,6 +97,67 @@ function getProcessStatus(pid) {
         return "not_running";
     }
 }
+/**
+ * Best-effort check that a pid actually belongs to a neurolink proxy process,
+ * so a stale/recycled supervisor pid is never mistaken for a live supervisor
+ * and signalled. Returns false when the process cannot be confirmed as ours.
+ */
+async function processLooksLikeProxySupervisor(pid) {
+    try {
+        const { execFileSync } = await import("node:child_process");
+        const args = execFileSync("ps", ["-p", String(pid), "-o", "args="], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return /neurolink/i.test(args);
+    }
+    catch {
+        // `ps` unavailable or the pid vanished — do not signal an unverified pid.
+        return false;
+    }
+}
+/**
+ * Ensure any supervisor recorded in state is actually stopped before its state
+ * record is cleared. A running supervisor still owns the listening socket;
+ * deleting its record would orphan it with no way to find it again. Returns
+ * false when a running supervisor could not be stopped, so callers can abort
+ * the uninstall instead of silently discarding the record.
+ */
+async function ensureSupervisorStoppedBeforeClear() {
+    const pid = loadProxySupervisorState()?.pid;
+    if (!pid || getProcessStatus(pid) === "not_running") {
+        return true;
+    }
+    // Guard against a stale/recycled pid: only signal a process that still looks
+    // like a neurolink proxy supervisor, so uninstall never terminates an
+    // unrelated, same-user process that inherited the recorded pid.
+    if (!(await processLooksLikeProxySupervisor(pid))) {
+        return true;
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch (error) {
+        if (error.code === "ESRCH") {
+            return true;
+        }
+        return false;
+    }
+    for (let attempt = 0; attempt < 25; attempt += 1) {
+        if (getProcessStatus(pid) === "not_running") {
+            return true;
+        }
+        await sleep(200);
+    }
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch {
+        /* already gone or not permitted */
+    }
+    await sleep(200);
+    return getProcessStatus(pid) === "not_running";
+}
 /** Resolve the primary-account info shown in /status. Reads the operator's
  *  configured email from proxy config and cross-checks it against the token
  *  store; falls back to the first enabled anthropic account when not set or
@@ -147,6 +225,16 @@ async function isLaunchdManaging() {
 function isLaunchdManagedProcess() {
     return process.platform === "darwin" && process.ppid === 1;
 }
+function isProxySocketWorkerProcess() {
+    return process.env[PROXY_SOCKET_WORKER_ENV] === "1";
+}
+function getProxyWorkerGeneration() {
+    const generation = Number(process.env.NEUROLINK_PROXY_WORKER_GENERATION);
+    if (!Number.isSafeInteger(generation) || generation <= 0) {
+        throw new Error("proxy socket worker generation is missing or invalid");
+    }
+    return generation;
+}
 function isProxyAutoUpdateEnabled(value = process.env.NEUROLINK_PROXY_AUTO_UPDATE) {
     return !["0", "off", "false"].includes((value ?? "").trim().toLowerCase());
 }
@@ -373,6 +461,75 @@ async function getProxyRuntimeActivity(host, port, timeoutMs = 3_000) {
         return null;
     }
 }
+async function getRollingActivationFailure(host, port, expectedVersion) {
+    try {
+        const response = await fetch(`http://${host}:${port}/status`, {
+            signal: AbortSignal.timeout(3_000),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const payload = (await response.json());
+        const failure = payload.autoUpdate?.rolling?.lastFailure;
+        if (failure?.version !== expectedVersion ||
+            typeof failure.phase !== "string" ||
+            typeof failure.message !== "string") {
+            return null;
+        }
+        return `${failure.phase}: ${failure.message}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the version the proxy currently reports healthy, or undefined. */
+async function fetchProxyHealthVersion(host, port) {
+    try {
+        const response = await fetch(`http://${host}:${port}/health`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (!response.ok) {
+            return undefined;
+        }
+        const data = (await response.json());
+        return data.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * After a failed rolling update, re-point the live supervisor at the reinstalled
+ * running version (mirroring the forward path: record the pending target, then
+ * signal SIGUSR2) and wait until the supervisor actually serves that version
+ * again. Returns false if it never reports the running version healthy in time.
+ */
+async function activateRollbackVersion(host, port, parentPid, runningVersion, timeoutMs) {
+    recordUpdateInstalled(runningVersion);
+    try {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            try {
+                process.kill(parentPid, "SIGUSR2");
+            }
+            catch {
+                // Supervisor may be mid-restart; its recovery loop also re-targets
+                // runningVersion once no worker is active.
+            }
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            if ((await fetchProxyHealthVersion(host, port)) === runningVersion) {
+                return true;
+            }
+            if (getProcessStatus(parentPid) === "not_running") {
+                return false;
+            }
+        }
+        return false;
+    }
+    finally {
+        abandonPendingUpdate(runningVersion);
+    }
+}
 async function setProxyUpdateDrain(host, port, draining) {
     const confirmState = async () => {
         try {
@@ -474,6 +631,31 @@ function writeTrampoline() {
 # Resolves a working neurolink binary on every launchd invocation so the
 # plist never gets pinned to a broken/stale shim.
 
+BAKED_NODE=${shEscape(bakedNode)}
+BAKED_SCRIPT=${shEscape(bakedScript)}
+
+# IPC workers must preserve the inherited Node channel until the final exec.
+# Do not launch a --version probe subprocess on that descriptor; the parent
+# validates the worker's exact package version before activation instead.
+if [ "\${NEUROLINK_PROXY_TRAMPOLINE_EXEC_ONLY:-0}" = "1" ]; then
+  if [ -n "\${NEUROLINK_BIN:-}" ] && [ -x "$NEUROLINK_BIN" ]; then
+    exec "$NEUROLINK_BIN" "$@"
+  fi
+  for cand in \
+      "$(command -v neurolink 2>/dev/null || true)" \
+      "\${PNPM_HOME:-}/neurolink" \
+      "$HOME/.local/share/pnpm/neurolink" \
+      "$HOME/Library/pnpm/neurolink" \
+      "/usr/local/bin/neurolink" \
+      "/opt/homebrew/bin/neurolink"; do
+    [ -n "$cand" ] && [ -x "$cand" ] && exec "$cand" "$@"
+  done
+  if [ -x "$BAKED_NODE" ] && [ -f "$BAKED_SCRIPT" ]; then
+    exec "$BAKED_NODE" "$BAKED_SCRIPT" "$@"
+  fi
+  exit 127
+fi
+
 # Probe a candidate: must be executable and respond to --version cleanly.
 _try() {
   [ -n "$1" ] && [ -x "$1" ] || return 1
@@ -505,8 +687,6 @@ done
 # 3. Baked-in fallback: the exact node + script that worked at install time.
 #    Always valid at install time; may become stale after package updates
 #    (but at that point the PATH candidates above should work).
-BAKED_NODE=${shEscape(bakedNode)}
-BAKED_SCRIPT=${shEscape(bakedScript)}
 if [ -x "$BAKED_NODE" ] && [ -f "$BAKED_SCRIPT" ]; then
   exec "$BAKED_NODE" "$BAKED_SCRIPT" "$@"
 fi
@@ -538,18 +718,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;
@@ -559,10 +735,10 @@ 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) {
+function spawnProxyUpdater(host, port, parentPid, rollingSupervisor = false) {
     if (!isProxyAutoUpdateEnabled()) {
         logger.always("[proxy] automatic updates disabled by environment");
         return undefined;
@@ -572,8 +748,9 @@ function spawnProxyUpdater(host, port, parentPid) {
         logger.always("[proxy] updater disabled: CLI entry script is unavailable");
         return undefined;
     }
+    const command = rollingSupervisor ? TRAMPOLINE_PATH : process.execPath;
     const args = [
-        entryScript,
+        ...(rollingSupervisor ? [] : [entryScript]),
         "proxy",
         "guard",
         "--host",
@@ -585,19 +762,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, {
+        const child = spawn(command, args, {
             detached: true,
-            stdio: ["ignore", logFd, logFd],
+            stdio: ["ignore", workerLog.stdio, workerLog.stdio],
             env: {
                 ...process.env,
                 NEUROLINK_PROXY_UPDATE_CONTROL_TOKEN: PROXY_UPDATE_CONTROL_TOKEN,
+                [PROXY_ROLLING_SUPERVISOR_ENV]: rollingSupervisor ? "1" : "0",
             },
         });
         child.once("error", (error) => {
@@ -614,7 +790,7 @@ function spawnProxyUpdater(host, port, parentPid) {
         return undefined;
     }
     finally {
-        closeSync(logFd);
+        workerLog.close();
     }
 }
 async function runProxyTelemetryManager(command) {
@@ -705,9 +881,29 @@ function getProxyRuntimeErrorCode(error) {
 async function ensureProxyStartAllowed(spinner) {
     const ignoreLaunchd = process.env.NEUROLINK_PROXY_IGNORE_LAUNCHD === "1" ||
         process.env.NEUROLINK_PROXY_IGNORE_LAUNCHD === "true";
+    const existingSupervisor = loadProxySupervisorState();
+    if (existingSupervisor) {
+        if (existingSupervisor.pid !== process.pid &&
+            isProcessRunning(existingSupervisor.pid) &&
+            !ignoreLaunchd) {
+            if (spinner) {
+                spinner.fail(chalk.red(`Proxy supervisor already running on port ${existingSupervisor.port} (PID: ${existingSupervisor.pid})`));
+            }
+            process.exit(process.ppid === 1 ? 0 : 1);
+        }
+        if (!isProcessRunning(existingSupervisor.pid)) {
+            clearProxySupervisorState();
+        }
+    }
     const existingState = loadProxyState();
     if (existingState) {
         if (isProcessRunning(existingState.pid)) {
+            // A newly relaunched stable supervisor may inherit state from an orphaned
+            // worker that is draining old connections but no longer owns a listener.
+            // launchd must be allowed to restore listener ownership in that case.
+            if (process.ppid === 1) {
+                return;
+            }
             // Test / dev escape hatch: when NEUROLINK_PROXY_IGNORE_LAUNCHD is set,
             // allow starting a second proxy on the test's requested port even if
             // a launchd-managed instance is using a different port (its state
@@ -1065,7 +1261,8 @@ export async function createProxyStartApp(params) {
                 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,
@@ -1180,6 +1377,7 @@ export async function createProxyStartApp(params) {
         const { loadAccountCooldowns } = await import("../../lib/proxy/accountCooldown.js");
         const stats = getStats();
         const runtimeState = loadProxyState();
+        const supervisorState = loadProxySupervisorState();
         const updateState = loadUpdateState();
         const cooldowns = await loadAccountCooldowns();
         const storedAccountKeys = new Set();
@@ -1199,6 +1397,7 @@ export async function createProxyStartApp(params) {
             version: PROXY_VERSION,
         });
         const primaryAccount = await resolveStatusPrimaryAccount(activeProxyConfig);
+        const activeUpdaterPid = supervisorState?.updaterPid ?? runtimeState?.updaterPid;
         return c.json({
             status: "running",
             ready: health.ready,
@@ -1257,9 +1456,11 @@ export async function createProxyStartApp(params) {
             },
             autoUpdate: {
                 enabled: isProxyAutoUpdateEnabled(),
-                updaterPid: runtimeState?.updaterPid ?? null,
-                updaterRunning: runtimeState?.updaterPid
-                    ? isProcessRunning(runtimeState.updaterPid)
+                supervisorPid: supervisorState?.pid ?? null,
+                rolling: supervisorState?.rolling ?? null,
+                updaterPid: activeUpdaterPid ?? null,
+                updaterRunning: activeUpdaterPid
+                    ? isProcessRunning(activeUpdaterPid)
                     : false,
                 liveVersion: PROXY_VERSION,
                 latestVersion: updateState?.lastCheckVersion || null,
@@ -1535,7 +1736,7 @@ function registerProxyShutdownHandlers(params) {
             }
         });
     };
-    const shutdown = async (signal) => {
+    const shutdown = async (signal, options) => {
         if (shutdownStarted) {
             return;
         }
@@ -1545,13 +1746,15 @@ function registerProxyShutdownHandlers(params) {
         params.updaterSupervisor?.stop();
         params.stopRuntimeConfig?.();
         logger.always(`\nShutting down proxy (${signal})...`);
-        let exitCode = signal === "SIGINT" ? 0 : 1;
-        try {
-            await closeServer();
-        }
-        catch (error) {
-            exitCode = 1;
-            logger.error(`[proxy] failed to drain server during shutdown: ${error instanceof Error ? error.message : String(error)}`);
+        let exitCode = signal === "SIGINT" || signal === "ROLLING_DRAIN" ? 0 : 1;
+        if (!options?.skipServerClose) {
+            try {
+                await closeServer();
+            }
+            catch (error) {
+                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");
@@ -1584,7 +1787,10 @@ function registerProxyShutdownHandlers(params) {
             }
         }
         try {
-            clearProxyState();
+            const state = loadProxyState();
+            if (state?.pid === process.pid) {
+                clearProxyState();
+            }
         }
         catch (error) {
             exitCode = 1;
@@ -1596,21 +1802,30 @@ function registerProxyShutdownHandlers(params) {
         logger.error(`[proxy] unexpected shutdown failure: ${error instanceof Error ? error.message : String(error)}`);
         process.exit(1);
     };
-    process.on("SIGTERM", () => {
-        void shutdown("SIGTERM").catch(forceExitAfterShutdownFailure);
-    });
-    process.on("SIGINT", () => {
-        void shutdown("SIGINT").catch(forceExitAfterShutdownFailure);
-    });
+    if (params.registerSignals ?? true) {
+        process.on("SIGTERM", () => {
+            void shutdown("SIGTERM").catch(forceExitAfterShutdownFailure);
+        });
+        process.on("SIGINT", () => {
+            void shutdown("SIGINT").catch(forceExitAfterShutdownFailure);
+        });
+    }
+    return shutdown;
 }
 async function startProxyRuntime(params) {
-    const { serve } = await import("@hono/node-server");
-    const server = serve({
-        fetch: params.app.fetch,
-        port: params.port,
-        hostname: params.host,
-    });
-    const managedByLaunchd = isLaunchdManagedProcess();
+    const socketWorker = isProxySocketWorkerProcess();
+    const { createAdaptorServer, serve } = await import("@hono/node-server");
+    const server = socketWorker
+        ? createAdaptorServer({
+            fetch: params.app.fetch,
+            hostname: params.host,
+        })
+        : serve({
+            fetch: params.app.fetch,
+            port: params.port,
+            hostname: params.host,
+        });
+    const managedByLaunchd = isLaunchdManagedProcess() || socketWorker;
     // launchd already owns restart supervision. A second detached supervisor can
     // outlive its parent and terminate a healthy replacement, so the guard is
     // reserved for foreground mode where it only cleans stale client settings.
@@ -1618,19 +1833,31 @@ async function startProxyRuntime(params) {
         ? undefined
         : spawnFailOpenGuard(params.host, params.port, process.pid);
     const readinessHost = params.host === "0.0.0.0" ? "127.0.0.1" : params.host;
-    await waitForProxyReadiness({
-        host: readinessHost,
-        port: params.port,
-    });
+    if (!socketWorker) {
+        await waitForProxyReadiness({
+            host: readinessHost,
+            port: params.port,
+        });
+    }
     markProxyReady(params.readiness);
-    try {
-        const { reconcileRunningUpdate } = await import("../../lib/proxy/updateState.js");
-        if (reconcileRunningUpdate(PROXY_VERSION)) {
-            logger.always(`[proxy] confirmed pending update is now running at v${PROXY_VERSION}`);
+    let updateReconciled = false;
+    const reconcileActivatedUpdate = async () => {
+        if (updateReconciled) {
+            return;
         }
-    }
-    catch (error) {
-        logger.always(`[proxy] WARNING: failed to reconcile update state: ${error instanceof Error ? error.message : String(error)}`);
+        updateReconciled = true;
+        try {
+            const { reconcileRunningUpdate } = await import("../../lib/proxy/updateState.js");
+            if (reconcileRunningUpdate(PROXY_VERSION)) {
+                logger.always(`[proxy] confirmed pending update is now running at v${PROXY_VERSION}`);
+            }
+        }
+        catch (error) {
+            logger.always(`[proxy] WARNING: failed to reconcile update state: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    if (!socketWorker) {
+        await reconcileActivatedUpdate();
     }
     /** Mirror the supervised worker PID into the proxy state used by status. */
     const updatePersistedUpdaterPid = (updaterPid) => {
@@ -1640,7 +1867,7 @@ async function startProxyRuntime(params) {
         }
         saveProxyState({ ...state, updaterPid });
     };
-    const updaterSupervisor = managedByLaunchd && !params.argv.dev
+    const updaterSupervisor = managedByLaunchd && !params.argv.dev && !socketWorker
         ? startUpdaterWorkerSupervisor({
             spawnWorker: () => spawnProxyUpdater(readinessHost, params.port, process.pid),
             isProcessRunning,
@@ -1668,32 +1895,41 @@ async function startProxyRuntime(params) {
         model: entry.model,
     }));
     const initialConfigStatus = params.runtimeConfigStore?.getStatus();
-    saveProxyState({
-        pid: process.pid,
-        port: params.port,
-        host: params.host,
-        strategy: activeStrategy,
-        startTime: new Date().toISOString(),
-        ready: true,
-        readyAt: params.readiness.readyAtMs
-            ? new Date(params.readiness.readyAtMs).toISOString()
-            : undefined,
-        healthPath: "/health",
-        statusPath: "/status",
-        envFile: params.loadedEnvFile,
-        fallbackChain,
-        accountAllowlist: activeAccountAllowlist
-            ? [...activeAccountAllowlist]
-            : undefined,
-        guardPid,
-        updaterPid,
-        managedBy: managedByLaunchd ? "launchd" : "manual",
-        passthrough: activePassthrough,
-        configGeneration: initialRuntimeConfig?.generation,
-        configLoadedAt: initialRuntimeConfig?.loadedAt,
-        lastConfigReloadError: initialConfigStatus?.lastReloadError,
-        configFile: initialConfigStatus?.configPath,
-    });
+    const persistInitialProxyState = () => {
+        const supervisorState = socketWorker ? loadProxySupervisorState() : null;
+        saveProxyState({
+            pid: process.pid,
+            port: params.port,
+            host: params.host,
+            strategy: activeStrategy,
+            startTime: new Date().toISOString(),
+            ready: true,
+            readyAt: params.readiness.readyAtMs
+                ? new Date(params.readiness.readyAtMs).toISOString()
+                : undefined,
+            healthPath: "/health",
+            statusPath: "/status",
+            envFile: params.loadedEnvFile,
+            fallbackChain,
+            accountAllowlist: activeAccountAllowlist
+                ? [...activeAccountAllowlist]
+                : undefined,
+            guardPid,
+            updaterPid: socketWorker ? supervisorState?.updaterPid : updaterPid,
+            supervisorPid: socketWorker
+                ? (supervisorState?.pid ?? process.ppid)
+                : undefined,
+            managedBy: managedByLaunchd ? "launchd" : "manual",
+            passthrough: activePassthrough,
+            configGeneration: initialRuntimeConfig?.generation,
+            configLoadedAt: initialRuntimeConfig?.loadedAt,
+            lastConfigReloadError: initialConfigStatus?.lastReloadError,
+            configFile: initialConfigStatus?.configPath,
+        });
+    };
+    if (!socketWorker) {
+        persistInitialProxyState();
+    }
     const persistRuntimeConfig = (snapshot) => {
         const state = loadProxyState();
         if (!state || state.pid !== process.pid) {
@@ -1781,20 +2017,152 @@ async function startProxyRuntime(params) {
     const maintenance = startProxyBackgroundMaintenance(params.cleanupLogs, () => params.runtimeConfigStore
         ? params.runtimeConfigStore.getSnapshot().accountAllowlist
         : params.accountAllowlist);
-    registerProxyShutdownHandlers({
+    const shutdown = registerProxyShutdownHandlers({
         server,
         host: params.host,
         port: params.port,
         isDev,
         updaterSupervisor,
         stopRuntimeConfig,
+        registerSignals: !socketWorker,
         ...maintenance,
     });
+    if (socketWorker) {
+        attachSocketWorkerProcess(server, {
+            generation: getProxyWorkerGeneration(),
+            version: PROXY_VERSION,
+            onActivated: () => {
+                persistInitialProxyState();
+                void reconcileActivatedUpdate();
+            },
+            onDrained: () => {
+                void shutdown("ROLLING_DRAIN", { skipServerClose: true });
+            },
+        });
+    }
+}
+async function runLaunchdProxySupervisor(argv, spinner) {
+    await ensureProxyStartAllowed(spinner);
+    const entryScript = process.argv[1];
+    if (!entryScript) {
+        throw new Error("proxy supervisor cannot resolve the CLI entry script");
+    }
+    const host = argv.host ?? "127.0.0.1";
+    const port = argv.port ?? 55669;
+    const workerArgs = process.argv.slice(2);
+    const supervisorStartedAt = new Date().toISOString();
+    let currentUpdaterPid;
+    const rollingServer = await startRollingProxyServer({
+        host,
+        port,
+        initialVersion: PROXY_VERSION,
+        spawnWorker: (generation, expectedVersion) => spawnProxySocketWorker({
+            generation,
+            expectedVersion,
+            command: TRAMPOLINE_PATH,
+            args: workerArgs,
+            env: {
+                NEUROLINK_PROXY_UPDATE_CONTROL_TOKEN: PROXY_UPDATE_CONTROL_TOKEN,
+                NEUROLINK_PROXY_TRAMPOLINE_EXEC_ONLY: "1",
+            },
+        }),
+        onStateChange: (snapshot) => {
+            saveProxySupervisorState({
+                pid: process.pid,
+                host,
+                port,
+                startTime: supervisorStartedAt,
+                updaterPid: currentUpdaterPid,
+                rolling: snapshot,
+            });
+        },
+        log: (message) => logger.always(message),
+    });
+    let rollingReplacement = null;
+    const activatePendingUpdate = () => {
+        if (rollingReplacement) {
+            return;
+        }
+        let pendingVersion;
+        try {
+            pendingVersion = loadUpdateState()?.pendingRestartVersion ?? undefined;
+        }
+        catch (error) {
+            logger.always(`[proxy-supervisor] failed to read pending update state: ${error instanceof Error ? error.message : String(error)}`);
+            return;
+        }
+        if (!pendingVersion || !/^\d+\.\d+\.\d+$/.test(pendingVersion)) {
+            logger.always("[proxy-supervisor] ignored update activation without a valid pending version");
+            return;
+        }
+        logger.always(`[proxy-supervisor] preparing rolling activation for v${pendingVersion}`);
+        rollingReplacement = rollingServer
+            .replace(pendingVersion)
+            .then(() => {
+            logger.always(`[proxy-supervisor] rolling activation complete version=${pendingVersion}`);
+        })
+            .catch((error) => {
+            logger.always(`[proxy-supervisor] rolling activation failed version=${pendingVersion}: ${error instanceof Error ? error.message : String(error)}`);
+        })
+            .finally(() => {
+            rollingReplacement = null;
+        });
+    };
+    process.on("SIGUSR2", activatePendingUpdate);
+    const readinessHost = host === "0.0.0.0" ? "127.0.0.1" : host;
+    const updatePersistedUpdaterPid = (updaterPid) => {
+        currentUpdaterPid = updaterPid;
+        const state = loadProxySupervisorState();
+        if (!state || state.pid !== process.pid) {
+            return;
+        }
+        saveProxySupervisorState({ ...state, updaterPid });
+    };
+    const updaterSupervisor = startUpdaterWorkerSupervisor({
+        spawnWorker: () => spawnProxyUpdater(readinessHost, rollingServer.address.port, process.pid, true),
+        isProcessRunning,
+        stopWorker: (pid) => process.kill(pid, "SIGTERM"),
+        onPidChange: updatePersistedUpdaterPid,
+        log: (message) => logger.always(message),
+    });
+    updatePersistedUpdaterPid(updaterSupervisor.currentPid());
+    if (spinner) {
+        spinner.succeed(chalk.green("Claude proxy supervisor started successfully"));
+    }
+    logger.always(`[proxy-supervisor] listening on ${host}:${rollingServer.address.port} workerPid=${rollingServer.snapshot().active?.pid ?? "unknown"} version=${PROXY_VERSION}`);
+    let stopping = false;
+    const shutdown = async (signal) => {
+        if (stopping) {
+            return;
+        }
+        stopping = true;
+        logger.always(`[proxy-supervisor] shutting down (${signal})`);
+        process.off("SIGUSR2", activatePendingUpdate);
+        updaterSupervisor.stop();
+        await rollingServer.close();
+        const supervisorState = loadProxySupervisorState();
+        if (supervisorState?.pid === process.pid) {
+            clearProxySupervisorState();
+        }
+        process.exit(0);
+    };
+    process.once("SIGTERM", () => {
+        void shutdown("SIGTERM");
+    });
+    process.once("SIGINT", () => {
+        void shutdown("SIGINT");
+    });
+    await new Promise(() => undefined);
 }
 async function startProxyCommandHandler(argv) {
     const spinner = argv.quiet ? null : ora("Starting Claude proxy...").start();
     const isDev = argv.dev ?? false;
+    const socketWorker = isProxySocketWorkerProcess();
     try {
+        if (!isDev && isLaunchdManagedProcess() && !socketWorker) {
+            await runLaunchdProxySupervisor(argv, spinner);
+            return;
+        }
         // In dev mode: redirect writable state to .neurolink-dev/ and skip singleton check
         let devPaths;
         if (isDev) {
@@ -1811,7 +2179,7 @@ async function startProxyCommandHandler(argv) {
                 mkdirSync(devPaths.stateDir, { recursive: true, mode: 0o700 });
             }
         }
-        if (!isDev) {
+        if (!isDev && !socketWorker) {
             await ensureProxyStartAllowed(spinner);
         }
         const baseEnv = { ...process.env };
@@ -2046,6 +2414,7 @@ export const proxyStatusCommand = {
     handler: async (argv) => {
         try {
             const state = loadProxyState();
+            const supervisorState = loadProxySupervisorState();
             const updateState = loadUpdateState();
             const status = {
                 running: false,
@@ -2064,6 +2433,10 @@ export const proxyStatusCommand = {
                 configLoadedAt: null,
                 lastConfigReloadError: null,
                 autoUpdateEnabled: isProxyAutoUpdateEnabled(),
+                workerVersion: null,
+                supervisorPid: null,
+                supervisorRunning: false,
+                rolling: null,
                 updaterPid: null,
                 updaterRunning: false,
                 latestVersion: updateState?.lastCheckVersion || null,
@@ -2071,25 +2444,52 @@ export const proxyStatusCommand = {
                 deferredUpdate: updateState?.deferredUpdate ?? null,
                 lastUpdateFailure: updateState?.lastFailure ?? null,
             };
-            if (state && isProcessRunning(state.pid)) {
+            const workerRunning = state ? isProcessRunning(state.pid) : false;
+            const supervisorPid = supervisorState?.pid ?? state?.supervisorPid;
+            const supervisorRunning = supervisorPid
+                ? isProcessRunning(supervisorPid)
+                : false;
+            const servingWorker = workerRunning &&
+                (supervisorPid
+                    ? supervisorRunning &&
+                        (!supervisorState ||
+                            supervisorState.rolling.active?.pid === state?.pid)
+                    : true);
+            if ((state || supervisorState) && (servingWorker || supervisorRunning)) {
+                const activeHost = state?.host ?? supervisorState?.host ?? null;
+                const activePort = state?.port ?? supervisorState?.port ?? null;
                 status.running = true;
-                status.pid = state.pid;
-                status.port = state.port;
-                status.host = state.host;
-                status.mode = state.passthrough ? "passthrough" : "full";
-                status.strategy = state.strategy;
-                status.startTime = state.startTime;
-                status.uptime = Date.now() - new Date(state.startTime).getTime();
-                status.url = `http://${state.host === "0.0.0.0" ? "localhost" : state.host}:${state.port}`;
-                status.envFile = state.envFile ?? null;
-                status.fallbackChain = state.fallbackChain ?? null;
-                status.accountAllowlist = state.accountAllowlist ?? null;
-                status.configGeneration = state.configGeneration ?? null;
-                status.configLoadedAt = state.configLoadedAt ?? null;
-                status.lastConfigReloadError = state.lastConfigReloadError ?? null;
-                status.updaterPid = state.updaterPid ?? null;
-                status.updaterRunning = state.updaterPid
-                    ? isProcessRunning(state.updaterPid)
+                status.pid = servingWorker && state ? state.pid : null;
+                status.port = activePort;
+                status.host = activeHost;
+                status.mode = state
+                    ? state.passthrough
+                        ? "passthrough"
+                        : "full"
+                    : null;
+                status.strategy = state?.strategy ?? null;
+                status.startTime =
+                    state?.startTime ?? supervisorState?.startTime ?? null;
+                status.uptime = status.startTime
+                    ? Date.now() - new Date(status.startTime).getTime()
+                    : null;
+                status.url =
+                    activeHost && activePort
+                        ? `http://${activeHost === "0.0.0.0" ? "localhost" : activeHost}:${activePort}`
+                        : null;
+                status.envFile = state?.envFile ?? null;
+                status.fallbackChain = state?.fallbackChain ?? null;
+                status.accountAllowlist = state?.accountAllowlist ?? null;
+                status.configGeneration = state?.configGeneration ?? null;
+                status.configLoadedAt = state?.configLoadedAt ?? null;
+                status.lastConfigReloadError = state?.lastConfigReloadError ?? null;
+                status.supervisorPid = supervisorPid ?? null;
+                status.supervisorRunning = supervisorRunning;
+                status.rolling = supervisorState?.rolling ?? null;
+                status.updaterPid =
+                    supervisorState?.updaterPid ?? state?.updaterPid ?? null;
+                status.updaterRunning = status.updaterPid
+                    ? isProcessRunning(status.updaterPid)
                     : false;
             }
             // Fetch live stats before rendering (JSON or text)
@@ -2097,11 +2497,17 @@ export const proxyStatusCommand = {
             let liveConfig = null;
             if (status.running && status.url) {
                 try {
-                    const statusResp = await fetch(`${status.url}/status`);
+                    const statusResp = await fetch(`${status.url}/status`, {
+                        signal: AbortSignal.timeout(2_000),
+                    });
                     if (statusResp.ok) {
                         const statusData = (await statusResp.json());
                         liveStats = statusData.stats;
                         liveConfig = statusData.config;
+                        status.workerVersion =
+                            typeof statusData.version === "string"
+                                ? statusData.version
+                                : null;
                         if (typeof liveConfig?.generation === "number") {
                             status.configGeneration = liveConfig.generation;
                         }
@@ -2128,8 +2534,15 @@ export const proxyStatusCommand = {
             logger.always(chalk.gray("=".repeat(50)));
             logger.always("");
             if (status.running) {
-                logger.always(`  ${chalk.bold("Status:")}     ${chalk.green("RUNNING")}`);
-                logger.always(`  ${chalk.bold("PID:")}        ${chalk.cyan(status.pid)}`);
+                const serving = status.pid !== null;
+                logger.always(`  ${chalk.bold("Status:")}     ${serving ? chalk.green("RUNNING") : chalk.yellow("RECOVERING")}`);
+                logger.always(`  ${chalk.bold("Worker PID:")} ${serving ? chalk.cyan(status.pid) : chalk.yellow("unavailable")}`);
+                if (status.supervisorPid) {
+                    logger.always(`  ${chalk.bold("Supervisor:")} ${status.supervisorRunning ? chalk.cyan(status.supervisorPid) : chalk.red(`${status.supervisorPid} (not running)`)}`);
+                }
+                if (status.workerVersion) {
+                    logger.always(`  ${chalk.bold("Version:")}    ${chalk.cyan(`v${status.workerVersion}`)}`);
+                }
                 logger.always(`  ${chalk.bold("URL:")}        ${chalk.cyan(status.url)}`);
                 logger.always(`  ${chalk.bold("Strategy:")}   ${chalk.cyan(status.strategy)}`);
                 logger.always(`  ${chalk.bold("Mode:")}       ${chalk.cyan(status.mode ?? "full")}`);
@@ -2148,6 +2561,12 @@ export const proxyStatusCommand = {
                 if (status.pendingRestartVersion) {
                     logger.always(`  ${chalk.bold("Pending:")}    ${chalk.yellow(`v${status.pendingRestartVersion} installed; restart pending`)}`);
                 }
+                if (status.rolling?.candidate) {
+                    logger.always(`  ${chalk.bold("Handoff:")}    ${chalk.yellow(`preparing v${status.rolling.candidate.expectedVersion} (PID ${status.rolling.candidate.pid})`)}`);
+                }
+                else if (status.rolling?.draining.length) {
+                    logger.always(`  ${chalk.bold("Handoff:")}    ${chalk.cyan(`${status.rolling.draining.length} previous worker(s) draining`)}`);
+                }
                 if (status.deferredUpdate) {
                     const active = status.deferredUpdate.activeRequests === null
                         ? "unknown activity"
@@ -2181,7 +2600,9 @@ export const proxyStatusCommand = {
                 }
                 // Try to fetch live status from the running proxy
                 try {
-                    const response = await fetch(`${status.url}/health`);
+                    const response = await fetch(`${status.url}/health`, {
+                        signal: AbortSignal.timeout(2_000),
+                    });
                     if (response.ok) {
                         const liveStatus = (await response.json());
                         logger.always("");
@@ -2196,7 +2617,9 @@ export const proxyStatusCommand = {
                 // Try to get detailed stats
                 try {
                     const liveUrl = status.url;
-                    const statusResp = await fetch(`${liveUrl}/status`);
+                    const statusResp = await fetch(`${liveUrl}/status`, {
+                        signal: AbortSignal.timeout(2_000),
+                    });
                     if (statusResp.ok) {
                         const statusData = (await statusResp.json());
                         if (statusData.stats) {
@@ -2329,6 +2752,7 @@ export const proxyGuardCommand = {
         const failureThreshold = Math.max(1, Number(argv.failureThreshold ?? 5));
         const pollIntervalMs = Math.max(250, Number(argv.pollIntervalMs ?? 1_000));
         const updaterOnly = argv.updaterOnly === true;
+        const rollingSupervisor = process.env[PROXY_ROLLING_SUPERVISOR_ENV] === "1";
         if (!Number.isFinite(parentPid) || parentPid <= 0) {
             return;
         }
@@ -2414,56 +2838,62 @@ export const proxyGuardCommand = {
                     return;
                 }
                 logger.always(`[updater] update available: ${runningVersion} → ${result.latestVersion}`);
-                // 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));
-                    }
-                    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 (!rollingSupervisor) {
+                    // Legacy launchd services must become idle before their listener is
+                    // restarted. Rolling services keep the current worker serving while
+                    // the candidate package is installed and validated.
+                    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));
+                        }
                         scheduleUpdateRetry();
                         return;
                     }
+                    // Hold admission closed through install and restart after a quiet
+                    // observation, closing the race with a newly admitted request.
+                    if (!drainActive) {
+                        updateWindow = await waitForWindow(0);
+                        if (!updateWindow.ready) {
+                            scheduleUpdateRetry();
+                            return;
+                        }
+                    }
+                }
+                else {
+                    logger.always(`[updater] rolling supervisor will keep v${runningVersion} serving during installation`);
                 }
                 // Refresh after waiting so a long deferral can never install a stale
                 // target while a newer release is already available.
@@ -2481,7 +2911,7 @@ export const proxyGuardCommand = {
                     return;
                 }
                 persistUpdaterState("clear update deferral", () => clearUpdateDeferral());
-                logger.always(`[updater] safe update window acquired for v${result.latestVersion}`);
+                logger.always(`[updater] ${rollingSupervisor ? "rolling activation prepared" : "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}`;
@@ -2554,31 +2984,47 @@ export const proxyGuardCommand = {
                 if (guardStopping || getProcessStatus(parentPid) === "not_running") {
                     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;
-                logger.always(`[updater] restarting proxy via launchctl kickstart`);
-                const uid = process.getuid?.() ?? 501;
-                try {
-                    execFileSync("launchctl", ["kickstart", "-k", `gui/${uid}/${PLIST_LABEL}`], {
-                        timeout: 10_000,
-                        stdio: "pipe",
-                    });
+                if (rollingSupervisor) {
+                    logger.always(`[updater] requesting rolling activation of v${result.latestVersion}`);
+                    try {
+                        process.kill(parentPid, "SIGUSR2");
+                    }
+                    catch (activationError) {
+                        updateRestartInProgress = false;
+                        const message = activationError instanceof Error
+                            ? activationError.message
+                            : String(activationError);
+                        logger.always(`[updater] WARNING: rolling activation request failed: ${message}`);
+                        persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "restart", message));
+                        return;
+                    }
                 }
-                catch (restartErr) {
-                    updateRestartInProgress = false;
-                    const msg = restartErr instanceof Error
-                        ? restartErr.message
-                        : String(restartErr);
-                    logger.always(`[updater] WARNING: launchctl kickstart failed: ${msg}`);
-                    persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "restart", msg));
-                    return;
+                else {
+                    // Compatibility fallback for services installed before rolling
+                    // supervision was enabled.
+                    logger.always(`[updater] restarting proxy via launchctl kickstart`);
+                    const uid = process.getuid?.() ?? 501;
+                    try {
+                        execFileSync("launchctl", ["kickstart", "-k", `gui/${uid}/${PLIST_LABEL}`], {
+                            timeout: 10_000,
+                            stdio: "pipe",
+                        });
+                    }
+                    catch (restartErr) {
+                        updateRestartInProgress = false;
+                        const message = restartErr instanceof Error
+                            ? restartErr.message
+                            : String(restartErr);
+                        logger.always(`[updater] WARNING: launchctl kickstart failed: ${message}`);
+                        persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "restart", message));
+                        return;
+                    }
                 }
                 drainActive = false;
                 // 5. Wait for healthy restart
                 let healthy = false;
+                let rollingFailure = null;
                 const restartStart = Date.now();
                 while (Date.now() - restartStart < UPDATE_TIMEOUT_MS) {
                     await new Promise((r) => setTimeout(r, 2000));
@@ -2597,6 +3043,12 @@ export const proxyGuardCommand = {
                     catch {
                         /* retry */
                     }
+                    if (rollingSupervisor) {
+                        rollingFailure = await getRollingActivationFailure(host, port, result.latestVersion);
+                        if (rollingFailure) {
+                            break;
+                        }
+                    }
                 }
                 if (healthy) {
                     logger.always(`[updater] update successful: now running ${result.latestVersion}`);
@@ -2606,7 +3058,49 @@ export const proxyGuardCommand = {
                 }
                 else {
                     logger.always(`[updater] WARNING: proxy unhealthy after update to ${result.latestVersion}`);
-                    persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "health", `proxy did not report v${result.latestVersion} healthy within ${UPDATE_TIMEOUT_MS}ms`));
+                    let failureMessage = rollingFailure
+                        ? `rolling candidate failed: ${rollingFailure}`
+                        : `proxy did not report v${result.latestVersion} healthy within ${UPDATE_TIMEOUT_MS}ms`;
+                    if (rollingSupervisor) {
+                        try {
+                            const rollbackResolution = resolveGlobalInstaller({
+                                entryScript: process.argv[1],
+                            });
+                            const rollbackInstaller = rollbackResolution.installer;
+                            if (!rollbackInstaller) {
+                                throw new Error("no usable package manager is available for rollback");
+                            }
+                            logger.always(`[updater] rolling activation failed; restoring @juspay/neurolink@${runningVersion}`);
+                            execFileSync(rollbackInstaller.bin, getGlobalInstallArgs(rollbackInstaller.kind, `@juspay/neurolink@${runningVersion}`), { timeout: 120_000, stdio: "pipe" });
+                            writeTrampoline();
+                            const rollbackValidation = await validateInstalledVersion({
+                                binPath: TRAMPOLINE_PATH,
+                                expectedVersion: runningVersion,
+                            });
+                            if (rollbackValidation.version !== runningVersion) {
+                                throw new Error(`rollback trampoline reported v${rollbackValidation.version ?? "unknown"}; expected v${runningVersion}`);
+                            }
+                            // Reinstalling the old package is not enough: the supervisor was
+                            // told to activate result.latestVersion, so its recovery loop
+                            // keeps demanding the new version against the now-downgraded
+                            // installation and can never serve a worker again. Re-point the
+                            // supervisor at runningVersion and report success only once it
+                            // actually serves that version again.
+                            const rollbackActivated = await activateRollbackVersion(host, port, parentPid, runningVersion, UPDATE_TIMEOUT_MS);
+                            if (!rollbackActivated) {
+                                throw new Error(`supervisor did not report v${runningVersion} healthy within ${UPDATE_TIMEOUT_MS}ms after rollback`);
+                            }
+                            logger.always(`[updater] package rollback complete; v${runningVersion} active again`);
+                        }
+                        catch (rollbackError) {
+                            const rollbackMessage = rollbackError instanceof Error
+                                ? rollbackError.message
+                                : String(rollbackError);
+                            failureMessage += `; package rollback failed: ${rollbackMessage}`;
+                            logger.always(`[updater] WARNING: ${failureMessage}`);
+                        }
+                    }
+                    persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "health", failureMessage));
                     persistUpdaterState("abandon unhealthy pending update", () => abandonPendingUpdate(result.latestVersion));
                     persistUpdaterState("suppress unhealthy update", () => suppressVersion(result.latestVersion, "unhealthy_after_restart"));
                     updateRestartInProgress = false;
@@ -3058,28 +3552,6 @@ export const proxyInstallCommand = {
             console.info(chalk.red(`Failed to load service: ${e}`));
             process.exit(1);
         }
-        // Wait briefly for launchd to start the process, then persist state
-        await new Promise((resolve) => setTimeout(resolve, 2_000));
-        try {
-            const { execFileSync } = await import("node:child_process");
-            const uid = process.getuid?.() ?? 501;
-            const output = execFileSync("launchctl", ["print", `gui/${uid}/${PLIST_LABEL}`], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
-            const pidMatch = output.match(/pid\s*=\s*(\d+)/);
-            if (pidMatch) {
-                saveProxyState({
-                    pid: Number(pidMatch[1]),
-                    port,
-                    host,
-                    strategy: "fill-first",
-                    startTime: new Date().toISOString(),
-                    envFile,
-                    managedBy: "launchd",
-                });
-            }
-        }
-        catch {
-            /* non-fatal — state will be written by the proxy process itself */
-        }
         console.info("");
         console.info(chalk.bold("Proxy is now a persistent service:"));
         console.info(`  • Auto-starts on login`);
@@ -3102,6 +3574,12 @@ export const proxyUninstallCommand = {
         }
         const { existsSync, unlinkSync } = await import("fs");
         if (!existsSync(PLIST_PATH)) {
+            if (!(await ensureSupervisorStoppedBeforeClear())) {
+                console.info(chalk.red("A proxy supervisor is still running and could not be stopped; leaving its state intact. Stop it manually and retry."));
+                process.exit(1);
+            }
+            clearProxyState();
+            clearProxySupervisorState();
             console.info(chalk.yellow("No proxy service installed."));
             return;
         }
@@ -3113,7 +3591,16 @@ export const proxyUninstallCommand = {
         catch {
             /* may not be loaded */
         }
+        // Do not delete supervisor state while a supervisor still owns the
+        // listener: a swallowed unload failure (or a supervisor started outside
+        // launchd) would otherwise be orphaned.
+        if (!(await ensureSupervisorStoppedBeforeClear())) {
+            console.info(chalk.red("launchctl could not stop the running supervisor; aborting uninstall so its state is preserved. Stop it manually and retry."));
+            process.exit(1);
+        }
         unlinkSync(PLIST_PATH);
+        clearProxyState();
+        clearProxySupervisorState();
         console.info(chalk.green(`✓ Plist removed from ${PLIST_PATH}`));
         console.info(chalk.green(`✓ Proxy service uninstalled`));
     },