@juspay/neurolink 9.88.9 → 9.88.11

package/dist/cli/commands/proxy.js

@@ -20,7 +20,9 @@ import { formatUptime, isProcessRunning, StateFileManager, } from "../utils/serv
 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 { describeInstallFailure, getGlobalInstallArgs, resolveGlobalInstaller, validateInstalledVersion, } from "../../lib/proxy/globalInstaller.js";
+import { startUpdaterWorkerSupervisor } from "../../lib/proxy/updaterSupervisor.js";
+import { abandonPendingUpdate, isVersionSuppressed, loadUpdateState, recordCheck, recordSuccessfulUpdate, recordUpdateFailure, recordUpdateInstalled, suppressVersion, } from "../../lib/proxy/updateState.js";
 import { loadProxyEnvFile, resolveProxyEnvFile, } from "../../lib/proxy/proxyEnv.js";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
@@ -552,6 +554,12 @@ function spawnProxyUpdater(host, port, parentPid) {
             stdio: ["ignore", logFd, logFd],
             env: process.env,
         });
+        child.once("error", (error) => {
+            logger.always(`[proxy] updater worker error pid=${child.pid ?? "unknown"}: ${error.message}`);
+        });
+        child.once("exit", (code, signal) => {
+            logger.always(`[proxy] updater worker exited pid=${child.pid ?? "unknown"} code=${code ?? "none"} signal=${signal ?? "none"}`);
+        });
         child.unref();
         return child.pid;
     }
@@ -1034,6 +1042,7 @@ export async function createProxyStartApp(params) {
         const { loadAccountCooldowns } = await import("../../lib/proxy/accountCooldown.js");
         const stats = getStats();
         const runtimeState = loadProxyState();
+        const updateState = loadUpdateState();
         const cooldowns = await loadAccountCooldowns();
         const storedAccountKeys = new Set();
         try {
@@ -1066,10 +1075,13 @@ export async function createProxyStartApp(params) {
             health,
             stats: {
                 totalAttempts: stats.totalAttempts,
+                totalAttemptErrors: stats.totalAttemptErrors,
                 totalRequests: stats.totalRequests,
                 totalSuccess: stats.totalSuccess,
                 totalErrors: stats.totalErrors,
                 totalRateLimits: stats.totalRateLimits,
+                totalTransientRateLimits: stats.totalTransientRateLimits,
+                totalQuotaRateLimits: stats.totalQuotaRateLimits,
                 accounts: Object.values(stats.accounts).map((account) => {
                     const normalizedKey = normalizeAnthropicAccountKey(account.label);
                     const accountKey = storedAccountKeys.has(normalizedKey)
@@ -1083,10 +1095,13 @@ export async function createProxyStartApp(params) {
                         label: account.label,
                         type: account.type,
                         attempts: account.attemptCount,
-                        requests: account.attemptCount,
+                        requests: account.successCount + account.errorCount,
                         success: account.successCount,
                         errors: account.errorCount,
+                        attemptErrors: account.attemptErrorCount,
                         rateLimits: account.rateLimitCount,
+                        transientRateLimits: account.transientRateLimitCount,
+                        quotaRateLimits: account.quotaRateLimitCount,
                         cooling: (cooldowns[accountKey]?.coolingUntil ?? 0) > now,
                     };
                 }),
@@ -1105,6 +1120,19 @@ export async function createProxyStartApp(params) {
                 updaterRunning: runtimeState?.updaterPid
                     ? isProcessRunning(runtimeState.updaterPid)
                     : false,
+                liveVersion: PROXY_VERSION,
+                latestVersion: updateState?.lastCheckVersion || null,
+                pendingRestartVersion: updateState?.pendingRestartVersion ?? null,
+                lastCheckAt: updateState?.lastCheckAt ?? null,
+                lastUpdateAt: updateState?.lastUpdateAt ?? null,
+                lastUpdateVersion: updateState?.lastUpdateVersion ?? null,
+                lastFailure: updateState?.lastFailure
+                    ? {
+                        at: updateState.lastFailure.at,
+                        version: updateState.lastFailure.version,
+                        stage: updateState.lastFailure.stage,
+                    }
+                    : null,
             },
             config: params.proxyConfig
                 ? {
@@ -1356,6 +1384,7 @@ function registerProxyShutdownHandlers(params) {
         shutdownStarted = true;
         clearInterval(params.refreshInterval);
         clearInterval(params.logCleanupInterval);
+        params.updaterSupervisor?.stop();
         logger.always(`\nShutting down proxy (${signal})...`);
         let exitCode = signal === "SIGINT" ? 0 : 1;
         try {
@@ -1429,9 +1458,33 @@ async function startProxyRuntime(params) {
         port: params.port,
     });
     markProxyReady(params.readiness);
-    const updaterPid = managedByLaunchd && !params.argv.dev
-        ? spawnProxyUpdater(readinessHost, params.port, process.pid)
+    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)}`);
+    }
+    /** Mirror the supervised worker PID into the proxy state used by status. */
+    const updatePersistedUpdaterPid = (updaterPid) => {
+        const state = loadProxyState();
+        if (!state || state.pid !== process.pid) {
+            return;
+        }
+        saveProxyState({ ...state, updaterPid });
+    };
+    const updaterSupervisor = managedByLaunchd && !params.argv.dev
+        ? startUpdaterWorkerSupervisor({
+            spawnWorker: () => spawnProxyUpdater(readinessHost, params.port, process.pid),
+            isProcessRunning,
+            stopWorker: (pid) => process.kill(pid, "SIGTERM"),
+            onPidChange: updatePersistedUpdaterPid,
+            log: (message) => logger.always(message),
+        })
         : undefined;
+    const updaterPid = updaterSupervisor?.currentPid();
     const fallbackChain = params.proxyConfig?.routing?.fallbackChain?.map((entry) => ({
         provider: entry.provider,
         model: entry.model,
@@ -1507,6 +1560,7 @@ async function startProxyRuntime(params) {
         host: params.host,
         port: params.port,
         isDev,
+        updaterSupervisor,
         ...maintenance,
     });
 }
@@ -1668,18 +1722,51 @@ function printStatusStats(stats) {
         console.info(`    Attempts:    ${stats.totalAttempts}`);
     }
     console.info(`    Completed:   ${stats.totalRequests} total, ${stats.totalSuccess} success, ${stats.totalErrors} errors`);
-    console.info(`    Rate limits: ${stats.totalRateLimits}`);
+    if (stats.totalAttemptErrors !== undefined) {
+        console.info(`    Failed attempts: ${stats.totalAttemptErrors}`);
+    }
+    console.info(`    Rate-limited attempts: ${stats.totalRateLimits}` +
+        (stats.totalTransientRateLimits !== undefined &&
+            stats.totalQuotaRateLimits !== undefined
+            ? ` (${stats.totalTransientRateLimits} transient, ${stats.totalQuotaRateLimits} quota)`
+            : ""));
     if (stats.accounts?.length) {
         console.info(`\n  Accounts:`);
-        for (const a of stats.accounts) {
-            const acctStatus = a.cooling
-                ? chalk.red("cooling")
-                : chalk.green("active");
-            const attempts = a.attempts ?? a.requests ?? 0;
-            const success = a.success ?? 0;
-            const errors = a.errors ?? 0;
-            const rateLimits = a.rateLimits ?? 0;
-            console.info(`    ${a.label.padEnd(20)} ${a.type.padEnd(8)} ${String(attempts).padEnd(6)} attempts  ${String(success).padEnd(6)} success  ${String(errors).padEnd(6)} errors  ${String(rateLimits).padEnd(6)} rl  ${acctStatus}`);
+        const headers = [
+            "ACCOUNT",
+            "AUTH",
+            "ATTEMPTS",
+            "SUCCESS",
+            "ERRORS",
+            "RL",
+            "STATUS",
+        ];
+        const rows = stats.accounts.map((account) => [
+            account.label,
+            account.type,
+            String(account.attempts ?? account.requests ?? 0),
+            String(account.success ?? 0),
+            String(account.errors ?? 0),
+            String(account.rateLimits ?? 0),
+            account.cooling ? "cooling" : "active",
+        ]);
+        const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => row[index].length)));
+        const numericColumns = new Set([2, 3, 4, 5]);
+        /** Align text columns left and numeric account counters right. */
+        const formatRow = (cells) => cells
+            .map((cell, index) => numericColumns.has(index)
+            ? cell.padStart(widths[index])
+            : cell.padEnd(widths[index]))
+            .join("  ");
+        console.info(`    ${chalk.gray(formatRow(headers))}`);
+        console.info(`    ${chalk.gray(widths.map((width) => "-".repeat(width)).join("  "))}`);
+        for (const row of rows) {
+            const status = row[6];
+            const formatted = formatRow(row);
+            const statusStart = formatted.length - widths[6];
+            const prefix = formatted.slice(0, statusStart);
+            const paddedStatus = formatted.slice(statusStart);
+            console.info(`    ${chalk.cyan(prefix.slice(0, widths[0]))}${prefix.slice(widths[0])}${status === "cooling" ? chalk.red(paddedStatus) : chalk.green(paddedStatus)}`);
         }
     }
 }
@@ -1709,6 +1796,7 @@ export const proxyStatusCommand = {
     handler: async (argv) => {
         try {
             const state = loadProxyState();
+            const updateState = loadUpdateState();
             const status = {
                 running: false,
                 pid: null,
@@ -1725,6 +1813,9 @@ export const proxyStatusCommand = {
                 autoUpdateEnabled: isProxyAutoUpdateEnabled(),
                 updaterPid: null,
                 updaterRunning: false,
+                latestVersion: updateState?.lastCheckVersion || null,
+                pendingRestartVersion: updateState?.pendingRestartVersion ?? null,
+                lastUpdateFailure: updateState?.lastFailure ?? null,
             };
             if (state && isProcessRunning(state.pid)) {
                 status.running = true;
@@ -1776,6 +1867,15 @@ export const proxyStatusCommand = {
                 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.pendingRestartVersion) {
+                    logger.always(`  ${chalk.bold("Pending:")}    ${chalk.yellow(`v${status.pendingRestartVersion} installed; restart pending`)}`);
+                }
+                if (status.latestVersion) {
+                    logger.always(`  ${chalk.bold("Latest:")}     ${chalk.cyan(`v${status.latestVersion}`)}`);
+                }
+                if (status.lastUpdateFailure) {
+                    logger.always(`  ${chalk.bold("Update error:")} ${chalk.red(`${status.lastUpdateFailure.stage}: ${status.lastUpdateFailure.message}`)}`);
+                }
                 if (status.envFile) {
                     logger.always(`  ${chalk.bold("Env File:")}   ${chalk.cyan(status.envFile)}`);
                 }
@@ -1985,6 +2085,15 @@ export const proxyGuardCommand = {
                 updateCheckInterval = undefined;
             }
         };
+        /** Keep state-write failures observable without terminating the updater. */
+        const persistUpdaterState = (operation, action) => {
+            try {
+                action();
+            }
+            catch (error) {
+                logger.always(`[updater] WARNING: failed to ${operation}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        };
         let updateInProgress = false;
         let updateRestartInProgress = false;
         const runUpdateCheck = async () => {
@@ -1992,17 +2101,19 @@ export const proxyGuardCommand = {
                 return;
             }
             updateInProgress = true;
+            let updateVersion = runningVersion;
             try {
                 // Lazy-load update modules so they're only imported at check time
                 const { checkForUpdate } = await import("../../lib/proxy/updateChecker.js");
-                const { recordCheck, isVersionSuppressed, suppressVersion, recordSuccessfulUpdate, } = await import("../../lib/proxy/updateState.js");
                 // 1. Check for update
                 const result = await checkForUpdate(runningVersion);
-                recordCheck(result.latestVersion);
+                updateVersion = result.latestVersion;
+                persistUpdaterState("record update check", () => recordCheck(result.latestVersion));
                 if (!result.updateAvailable) {
                     return;
                 }
-                if (isVersionSuppressed(result.latestVersion)) {
+                const pendingRestart = loadUpdateState()?.pendingRestartVersion === result.latestVersion;
+                if (isVersionSuppressed(result.latestVersion) && !pendingRestart) {
                     logger.debug(`[guard] version ${result.latestVersion} is suppressed, skipping`);
                     return;
                 }
@@ -2028,61 +2139,71 @@ export const proxyGuardCommand = {
                 }
                 // 3. Install update (validate version string before passing to shell)
                 if (!/^\d+\.\d+\.\d+$/.test(result.latestVersion)) {
+                    const message = `invalid version format: ${result.latestVersion}`;
                     logger.always(`[guard] WARNING: invalid version format "${result.latestVersion}", skipping`);
-                    return;
-                }
-                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(", ")}`);
-                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(`[updater] installing @juspay/neurolink@${result.latestVersion} via ${installer.kind} ${installer.bin} (v${installer.version})`);
-                if (guardStopping || getProcessStatus(parentPid) === "not_running") {
+                    persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "check", message));
                     return;
                 }
                 const { execFileSync } = await import("node:child_process");
-                try {
-                    execFileSync(installer.bin, getGlobalInstallArgs(installer.kind, `@juspay/neurolink@${result.latestVersion}`), {
-                        timeout: 120_000,
-                        stdio: "pipe",
+                if (!pendingRestart) {
+                    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(", ")}`);
+                    const installer = installerResolution.installer;
+                    if (!installer) {
+                        const message = "no package manager has a writable global root and executable directory";
+                        logger.always(`[updater] WARNING: ${message}; skipping this cycle`);
+                        persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "install", message));
+                        return;
+                    }
+                    logger.always(`[updater] installing @juspay/neurolink@${result.latestVersion} via ${installer.kind} ${installer.bin} (v${installer.version})`);
+                    if (guardStopping || getProcessStatus(parentPid) === "not_running") {
+                        return;
+                    }
+                    try {
+                        execFileSync(installer.bin, getGlobalInstallArgs(installer.kind, `@juspay/neurolink@${result.latestVersion}`), {
+                            timeout: 120_000,
+                            stdio: "pipe",
+                        });
+                    }
+                    catch (installErr) {
+                        const detail = describeInstallFailure(installErr);
+                        logger.always(`[updater] WARNING: global install failed:\n${detail}`);
+                        persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "install", detail));
+                        return;
+                    }
                 }
-                catch (installErr) {
-                    const detail = describeInstallFailure(installErr);
-                    logger.always(`[updater] WARNING: global install failed:\n${detail}`);
-                    return;
+                else {
+                    logger.always(`[updater] resuming pending restart for already-installed v${result.latestVersion}`);
                 }
                 // 4. Refresh and validate the stable trampoline. The plist already
                 // points at this path, so it must not be unloaded or rewritten here.
                 try {
                     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(`[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) {
-                        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})`);
+                    const validation = await validateInstalledVersion({
+                        binPath: TRAMPOLINE_PATH,
+                        expectedVersion: result.latestVersion,
+                    });
+                    if (validation.version !== result.latestVersion) {
+                        const message = `trampoline validation failed after ${validation.attempts} attempts: ${validation.failure ?? "unknown failure"}`;
+                        logger.always(`[updater] WARNING: ${message}; restart deferred`);
+                        persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "validation", message));
+                        persistUpdaterState("abandon invalid pending update", () => abandonPendingUpdate(result.latestVersion));
                         return;
                     }
-                    logger.always(`[updater] trampoline validated at v${probed}`);
+                    persistUpdaterState("record installed update", () => recordUpdateInstalled(result.latestVersion));
+                    logger.always(`[updater] trampoline validated at v${validation.version} after ${validation.attempts} attempt(s)`);
                 }
                 catch (trampolineError) {
-                    logger.always(`[updater] WARNING: failed to refresh trampoline; refusing restart: ${trampolineError instanceof Error
+                    const message = trampolineError instanceof Error
                         ? trampolineError.message
-                        : String(trampolineError)}`);
+                        : String(trampolineError);
+                    logger.always(`[updater] WARNING: failed to refresh trampoline; refusing restart: ${message}`);
+                    persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "validation", message));
+                    persistUpdaterState("abandon invalid pending update", () => abandonPendingUpdate(result.latestVersion));
                     return;
                 }
                 if (guardStopping || getProcessStatus(parentPid) === "not_running") {
@@ -2121,6 +2242,7 @@ export const proxyGuardCommand = {
                         ? restartErr.message
                         : String(restartErr);
                     logger.always(`[updater] WARNING: launchctl kickstart failed: ${msg}`);
+                    persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "restart", msg));
                     return;
                 }
                 // 5. Wait for healthy restart
@@ -2146,18 +2268,22 @@ export const proxyGuardCommand = {
                 }
                 if (healthy) {
                     logger.always(`[updater] update successful: now running ${result.latestVersion}`);
-                    recordSuccessfulUpdate(result.latestVersion);
+                    persistUpdaterState("record successful update", () => recordSuccessfulUpdate(result.latestVersion));
                     // The replacement proxy starts a worker running the new version.
                     process.exit(0);
                 }
                 else {
                     logger.always(`[updater] WARNING: proxy unhealthy after update to ${result.latestVersion}`);
-                    suppressVersion(result.latestVersion, "unhealthy_after_restart");
+                    persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "health", `proxy did not report v${result.latestVersion} healthy within ${UPDATE_TIMEOUT_MS}ms`));
+                    persistUpdaterState("abandon unhealthy pending update", () => abandonPendingUpdate(result.latestVersion));
+                    persistUpdaterState("suppress unhealthy update", () => suppressVersion(result.latestVersion, "unhealthy_after_restart"));
                     updateRestartInProgress = false;
                 }
             }
             catch (err) {
-                logger.always(`[updater] update check error: ${err instanceof Error ? err.message : String(err)}`);
+                const message = err instanceof Error ? err.message : String(err);
+                logger.always(`[updater] update check error: ${message}`);
+                persistUpdaterState("record update failure", () => recordUpdateFailure(updateVersion, "check", message));
             }
             finally {
                 updateInProgress = false;
@@ -2175,12 +2301,21 @@ export const proxyGuardCommand = {
         while (true) {
             const healthy = await isProxyHealthy(host, port, 1_500);
             if (healthy) {
+                if (updaterOnly && consecutiveUnhealthy >= failureThreshold) {
+                    logger.always(`[updater] proxy health recovered after ${consecutiveUnhealthy} failed checks`);
+                }
                 consecutiveUnhealthy = 0;
             }
             else {
                 consecutiveUnhealthy += 1;
+                if (updaterOnly && consecutiveUnhealthy === failureThreshold) {
+                    logger.always(`[updater] proxy health unavailable after ${consecutiveUnhealthy} checks; worker remains active`);
+                }
             }
             if (parentStatus === "not_running" && !updateRestartInProgress) {
+                if (updaterOnly) {
+                    logger.always(`[updater] parent pid=${parentPid} exited; updater worker stopping`);
+                }
                 // Parent is gone (and we're not mid-update-restart).
                 // If endpoint is still healthy, another proxy took over.
                 if (healthy) {
@@ -2189,7 +2324,8 @@ export const proxyGuardCommand = {
                 }
                 break;
             }
-            if (!updateRestartInProgress &&
+            if (!updaterOnly &&
+                !updateRestartInProgress &&
                 !healthy &&
                 consecutiveUnhealthy >= failureThreshold) {
                 // A detached guard cannot safely decide that a live process should be

package/dist/lib/proxy/globalInstaller.d.ts

@@ -1,5 +1,11 @@
-import type { GlobalInstallerKind, GlobalInstallerResolution, ResolveGlobalInstallerOptions } from "../types/index.js";
+import type { GlobalInstallerKind, GlobalInstallerResolution, InstalledVersionValidation, ResolveGlobalInstallerOptions, ValidateInstalledVersionOptions } from "../types/index.js";
 /** Resolve a package manager that can update the installation currently running. */
 export declare function resolveGlobalInstaller(options?: ResolveGlobalInstallerOptions): GlobalInstallerResolution;
 export declare function getGlobalInstallArgs(kind: GlobalInstallerKind, packageSpec: string): string[];
+/**
+ * Validate a freshly installed CLI with retries. Global package replacement
+ * can leave executable shims briefly unavailable while filesystem metadata and
+ * cold module loading settle, so a single short probe is not authoritative.
+ */
+export declare function validateInstalledVersion(options: ValidateInstalledVersionOptions): Promise<InstalledVersionValidation>;
 export declare function describeInstallFailure(error: unknown): string;

package/dist/lib/proxy/globalInstaller.js

@@ -1,7 +1,7 @@
 import { execFileSync as nodeExecFileSync } from "node:child_process";
 import { accessSync, constants, existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 function runText(execFileSync, bin, args) {
     return String(execFileSync(bin, args, {
         encoding: "utf8",
@@ -136,6 +136,54 @@ export function getGlobalInstallArgs(kind, packageSpec) {
         ? ["add", "-g", packageSpec]
         : ["install", "--global", "--no-audit", "--no-fund", packageSpec];
 }
+/**
+ * Validate a freshly installed CLI with retries. Global package replacement
+ * can leave executable shims briefly unavailable while filesystem metadata and
+ * cold module loading settle, so a single short probe is not authoritative.
+ */
+export async function validateInstalledVersion(options) {
+    if (!isAbsolute(options.binPath)) {
+        return {
+            attempts: 0,
+            failure: `binPath must be absolute: ${options.binPath}`,
+        };
+    }
+    const execFileSync = options.execFileSync ?? nodeExecFileSync;
+    const sleepFn = options.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 5);
+    const delayMs = Math.max(0, options.delayMs ?? 2_000);
+    const timeoutMs = Math.max(1_000, options.timeoutMs ?? 10_000);
+    let lastVersion;
+    let lastFailure;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const output = String(execFileSync(options.binPath, ["--version"], {
+                encoding: "utf8",
+                timeout: timeoutMs,
+                stdio: ["ignore", "pipe", "pipe"],
+            })).trim();
+            lastVersion = output || undefined;
+            if (lastVersion === options.expectedVersion) {
+                return { version: lastVersion, attempts: attempt };
+            }
+            lastFailure = lastVersion
+                ? `resolved to v${lastVersion}; expected v${options.expectedVersion}`
+                : "version command returned empty output";
+        }
+        catch (error) {
+            lastFailure = describeInstallFailure(error);
+        }
+        if (attempt < maxAttempts) {
+            await sleepFn(delayMs);
+        }
+    }
+    return {
+        version: lastVersion,
+        attempts: maxAttempts,
+        failure: lastFailure ?? "version validation failed",
+    };
+}
 function capturedOutput(error, key) {
     if (!error || typeof error !== "object" || !(key in error)) {
         return "";

package/dist/lib/proxy/updateState.d.ts

@@ -48,6 +48,14 @@ export declare function suppressVersion(version: string, reason: string, stateFi
  * @param stateFilePath - Override path for testing
  */
 export declare function recordSuccessfulUpdate(version: string, stateFilePath?: string): void;
+/** Record that package installation completed but the live restart is pending. */
+export declare function recordUpdateInstalled(version: string, stateFilePath?: string): void;
+/** Abandon a matching installed version so the next cycle may reinstall it. */
+export declare function abandonPendingUpdate(version: string, stateFilePath?: string): boolean;
+/** Persist a stage-specific updater failure so status remains actionable. */
+export declare function recordUpdateFailure(version: string, stage: NonNullable<UpdateState["lastFailure"]>["stage"], message: string, stateFilePath?: string): void;
+/** Complete an updater-managed install after a manual or automatic restart. */
+export declare function reconcileRunningUpdate(runningVersion: string, stateFilePath?: string): boolean;
 /**
  * Record an update check: set lastCheckAt and lastCheckVersion, then persist.
  *

package/dist/lib/proxy/updateState.js

@@ -15,6 +15,13 @@ import { randomUUID } from "node:crypto";
 // ============================================
 const STATE_FILENAME = "update-state.json";
 const SUPPRESSION_TTL_MS = 86_400_000; // 24 hours
+const UPDATE_FAILURE_STAGES = new Set([
+    "check",
+    "install",
+    "validation",
+    "restart",
+    "health",
+]);
 // ============================================
 // Internal Helpers
 // ============================================
@@ -37,6 +44,18 @@ function ensureParentDir(filePath) {
         fs.mkdirSync(dir, { recursive: true });
     }
 }
+/** Reject malformed persisted failure metadata before it reaches status output. */
+function isValidLastFailure(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.at === "string" &&
+        typeof candidate.version === "string" &&
+        typeof candidate.stage === "string" &&
+        UPDATE_FAILURE_STAGES.has(candidate.stage) &&
+        typeof candidate.message === "string");
+}
 // ============================================
 // Exported Functions
 // ============================================
@@ -50,6 +69,8 @@ export function getDefaultUpdateState() {
         suppressedVersions: {},
         lastUpdateAt: null,
         lastUpdateVersion: null,
+        pendingRestartVersion: null,
+        lastFailure: null,
     };
 }
 /**
@@ -77,7 +98,18 @@ export function loadUpdateState(stateFilePath) {
             typeof parsed.lastCheckAt !== "string") {
             return getDefaultUpdateState();
         }
-        return parsed;
+        const candidate = parsed;
+        return {
+            ...getDefaultUpdateState(),
+            ...candidate,
+            suppressedVersions: candidate.suppressedVersions ?? {},
+            pendingRestartVersion: typeof candidate.pendingRestartVersion === "string"
+                ? candidate.pendingRestartVersion
+                : null,
+            lastFailure: isValidLastFailure(candidate.lastFailure)
+                ? candidate.lastFailure
+                : null,
+        };
     }
     catch {
         // Corrupt or unreadable JSON — return default state
@@ -152,8 +184,48 @@ export function recordSuccessfulUpdate(version, stateFilePath) {
     const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
     state.lastUpdateAt = new Date().toISOString();
     state.lastUpdateVersion = version;
+    state.pendingRestartVersion = null;
+    state.lastFailure = null;
+    delete state.suppressedVersions[version];
+    saveUpdateState(state, stateFilePath);
+}
+/** Record that package installation completed but the live restart is pending. */
+export function recordUpdateInstalled(version, stateFilePath) {
+    const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.pendingRestartVersion = version;
+    state.lastFailure = null;
     saveUpdateState(state, stateFilePath);
 }
+/** Abandon a matching installed version so the next cycle may reinstall it. */
+export function abandonPendingUpdate(version, stateFilePath) {
+    const state = loadUpdateState(stateFilePath);
+    if (!state || state.pendingRestartVersion !== version) {
+        return false;
+    }
+    state.pendingRestartVersion = null;
+    saveUpdateState(state, stateFilePath);
+    return true;
+}
+/** Persist a stage-specific updater failure so status remains actionable. */
+export function recordUpdateFailure(version, stage, message, stateFilePath) {
+    const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.lastFailure = {
+        at: new Date().toISOString(),
+        version,
+        stage,
+        message: message.trim().slice(0, 1_000),
+    };
+    saveUpdateState(state, stateFilePath);
+}
+/** Complete an updater-managed install after a manual or automatic restart. */
+export function reconcileRunningUpdate(runningVersion, stateFilePath) {
+    const state = loadUpdateState(stateFilePath);
+    if (!state || state.pendingRestartVersion !== runningVersion) {
+        return false;
+    }
+    recordSuccessfulUpdate(runningVersion, stateFilePath);
+    return true;
+}
 /**
  * Record an update check: set lastCheckAt and lastCheckVersion, then persist.
  *

package/dist/lib/proxy/updaterSupervisor.d.ts

@@ -0,0 +1,3 @@
+import type { UpdaterWorkerSupervisor, UpdaterWorkerSupervisorOptions } from "../types/index.js";
+/** Keep the launchd updater worker alive while its owning proxy is running. */
+export declare function startUpdaterWorkerSupervisor(options: UpdaterWorkerSupervisorOptions): UpdaterWorkerSupervisor;