@juspay/neurolink 9.88.10 → 9.88.12

package/dist/lib/proxy/updaterSupervisor.js

@@ -0,0 +1,58 @@
+/** Keep the launchd updater worker alive while its owning proxy is running. */
+export function startUpdaterWorkerSupervisor(options) {
+    let stopped = false;
+    let pid;
+    /** Return the healthy worker PID or replace an unavailable worker. */
+    const checkNow = () => {
+        if (stopped) {
+            return pid;
+        }
+        if (pid !== undefined && options.isProcessRunning(pid)) {
+            return pid;
+        }
+        const previousPid = pid;
+        try {
+            pid = options.spawnWorker();
+        }
+        catch (error) {
+            pid = undefined;
+            options.log?.(`[proxy] updater worker spawn failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        options.onPidChange?.(pid);
+        if (pid !== undefined) {
+            options.log?.(previousPid === undefined
+                ? `[proxy] updater worker started pid=${pid}`
+                : `[proxy] updater worker restarted oldPid=${previousPid} newPid=${pid}`);
+        }
+        else {
+            options.log?.("[proxy] updater worker unavailable; retrying later");
+        }
+        return pid;
+    };
+    checkNow();
+    const interval = setInterval(checkNow, options.intervalMs ?? 30_000);
+    interval.unref?.();
+    return {
+        currentPid: () => pid,
+        checkNow,
+        stop: () => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            clearInterval(interval);
+            const activePid = pid;
+            if (activePid !== undefined && options.isProcessRunning(activePid)) {
+                try {
+                    options.stopWorker(activePid);
+                }
+                catch (error) {
+                    options.log?.(`[proxy] updater worker stop failed pid=${activePid}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            pid = undefined;
+            options.onPidChange?.(undefined);
+        },
+    };
+}
+//# sourceMappingURL=updaterSupervisor.js.map

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

@@ -6,7 +6,7 @@
 import type { AccountStats, ProxyStats } from "../types/index.js";
 export declare function recordAttempt(accountLabel: string, accountType: string): void;
 export declare function recordFinalSuccess(accountLabel?: string, accountType?: string): void;
-export declare function recordAttemptError(accountLabel: string, accountType: string, status: number): void;
+export declare function recordAttemptError(accountLabel: string, accountType: string, status: number, rateLimitKind?: "transient" | "quota"): void;
 export declare function recordFinalError(_status: number, accountLabel?: string, accountType?: string): void;
 export declare function getStats(): ProxyStats;
 export declare function getAccountStats(label: string): AccountStats | undefined;

package/dist/lib/proxy/usageStats.js

@@ -6,10 +6,13 @@
 const stats = {
     startedAt: Date.now(),
     totalAttempts: 0,
+    totalAttemptErrors: 0,
     totalRequests: 0,
     totalSuccess: 0,
     totalErrors: 0,
     totalRateLimits: 0,
+    totalTransientRateLimits: 0,
+    totalQuotaRateLimits: 0,
     accounts: {},
 };
 export function recordAttempt(accountLabel, accountType) {
@@ -26,13 +29,22 @@ export function recordFinalSuccess(accountLabel, accountType) {
         acct.successCount++;
     }
 }
-export function recordAttemptError(accountLabel, accountType, status) {
+export function recordAttemptError(accountLabel, accountType, status, rateLimitKind) {
     const acct = ensureAccount(accountLabel, accountType);
-    acct.errorCount++;
+    stats.totalAttemptErrors++;
+    acct.attemptErrorCount++;
     acct.lastErrorAt = Date.now();
     if (status === 429) {
         stats.totalRateLimits++;
         acct.rateLimitCount++;
+        if (rateLimitKind === "transient") {
+            stats.totalTransientRateLimits++;
+            acct.transientRateLimitCount++;
+        }
+        else if (rateLimitKind === "quota") {
+            stats.totalQuotaRateLimits++;
+            acct.quotaRateLimitCount++;
+        }
     }
 }
 export function recordFinalError(_status, accountLabel, accountType) {
@@ -58,10 +70,13 @@ export function getAccountStats(label) {
 export function resetStats() {
     stats.startedAt = Date.now();
     stats.totalAttempts = 0;
+    stats.totalAttemptErrors = 0;
     stats.totalRequests = 0;
     stats.totalSuccess = 0;
     stats.totalErrors = 0;
     stats.totalRateLimits = 0;
+    stats.totalTransientRateLimits = 0;
+    stats.totalQuotaRateLimits = 0;
     stats.accounts = {};
 }
 function ensureAccount(label, type) {
@@ -70,9 +85,12 @@ function ensureAccount(label, type) {
             label,
             type,
             attemptCount: 0,
+            attemptErrorCount: 0,
             successCount: 0,
             errorCount: 0,
             rateLimitCount: 0,
+            transientRateLimitCount: 0,
+            quotaRateLimitCount: 0,
             lastAttemptAt: 0,
         };
     }

package/dist/lib/server/routes/claudeProxyRoutes.d.ts

@@ -167,19 +167,11 @@ declare function handleAnthropicAuthRetry(args: {
     };
     enabledAccounts: ProxyPassthroughAccount[];
     orderedAccounts: ProxyPassthroughAccount[];
-    response: Response;
     tracer?: ProxyTracer;
     requestStartTime: number;
-    fetchStartMs: number;
-    attemptNumber: number;
-    finalBodyStr: string;
+    allocateAttemptNumber: () => number;
     upstreamSpan?: import("@opentelemetry/api").Span;
-    logAttempt: (status: number, errorType?: string, errorMessage?: string, extra?: {
-        inputTokens?: number;
-        outputTokens?: number;
-        cacheCreationTokens?: number;
-        cacheReadTokens?: number;
-    }) => void;
+    logAttempt: AnthropicAttemptLogger;
     logProxyBody: ProxyBodyCaptureLogger;
     logFinalRequest: (status: number, accountLabel: string, accountType: string, errorType?: string, errorMessage?: string, extra?: {
         inputTokens?: number;

package/dist/lib/server/routes/claudeProxyRoutes.js

@@ -2825,8 +2825,11 @@ async function handleAnthropicSuccessfulRetryResponse(args) {
     return retryJson;
 }
 async function handleAnthropicAuthRetry(args) {
-    const { ctx, body, account, accountState, headers, buildUpstreamBody, enabledAccounts, orderedAccounts, response: _response, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, logFinalRequest, lastError, authFailureMessage, sawRateLimit, sawTransientFailure, sawNetworkError, } = args;
+    const { ctx, body, account, accountState, headers, buildUpstreamBody, enabledAccounts, orderedAccounts, tracer, requestStartTime, allocateAttemptNumber, upstreamSpan, logAttempt, logProxyBody, logFinalRequest, lastError, authFailureMessage, sawRateLimit, sawTransientFailure, sawNetworkError, } = args;
     recordAttemptError(account.label, account.type, 401);
+    logAttempt(401, "authentication_error", "received 401 from Anthropic", {
+        retryable: true,
+    });
     let currentLastError = lastError;
     let currentAuthFailureMessage = authFailureMessage;
     let currentSawRateLimit = sawRateLimit;
@@ -2858,11 +2861,29 @@ async function handleAnthropicAuthRetry(args) {
         }
         await clearAuthCooldownAfterRefresh(account, accountState);
         headers.authorization = `Bearer ${account.token}`;
+        const retryAttemptNumber = allocateAttemptNumber();
+        recordAttempt(account.label, account.type);
+        const retryLogAttempt = (status, errorType, errorMessage, extra) => logAttempt(status, errorType, errorMessage, {
+            ...extra,
+            attempt: retryAttemptNumber,
+        });
+        const retryBodyStr = buildUpstreamBody(account.token).bodyStr;
+        const retryFetchStartMs = Date.now();
+        logProxyBody({
+            phase: "upstream_request",
+            headers,
+            body: retryBodyStr,
+            bodySize: Buffer.byteLength(retryBodyStr, "utf8"),
+            contentType: headers["content-type"] ?? "application/json",
+            account: account.label,
+            accountType: account.type,
+            attempt: retryAttemptNumber,
+        });
         try {
             const retryResp = await fetch("https://api.anthropic.com/v1/messages?beta=true", {
                 method: "POST",
                 headers,
-                body: buildUpstreamBody(account.token).bodyStr,
+                body: retryBodyStr,
                 signal: AbortSignal.timeout(UPSTREAM_FETCH_TIMEOUT_MS),
             });
             if (retryResp.ok) {
@@ -2877,9 +2898,9 @@ async function handleAnthropicAuthRetry(args) {
                     retryResp,
                     tracer,
                     requestStartTime,
-                    fetchStartMs,
-                    attemptNumber,
-                    finalBodyStr,
+                    fetchStartMs: retryFetchStartMs,
+                    attemptNumber: retryAttemptNumber,
+                    finalBodyStr: retryBodyStr,
                     upstreamSpan: currentUpstreamSpan,
                     logProxyBody,
                     logFinalRequest,
@@ -2919,9 +2940,9 @@ async function handleAnthropicAuthRetry(args) {
                 contentType: retryRespHeaders["content-type"] ?? "application/json",
                 account: account.label,
                 accountType: account.type,
-                attempt: attemptNumber,
+                attempt: retryAttemptNumber,
                 responseStatus: retryStatus,
-                durationMs: Date.now() - fetchStartMs,
+                durationMs: Date.now() - retryFetchStartMs,
             });
             authRetryError = `retry ${authRetry + 1}/${MAX_AUTH_RETRIES} failed with status ${retryStatus}`;
             currentLastError = retryBody;
@@ -2929,7 +2950,7 @@ async function handleAnthropicAuthRetry(args) {
             if (retryStatus === 429 &&
                 isAntiAbuseConstruction429(retryRespHeaders, retryBody)) {
                 logger.always(`[proxy] ← 429 account=${account.label} anti-abuse/construction rejection after OAuth refresh — returning non-retryable request error`);
-                logAttempt(429, "construction_rejection", retryBody);
+                retryLogAttempt(429, "construction_rejection", retryBody);
                 tracer?.setError("construction_rejection", retryBody.slice(0, 500));
                 currentUpstreamSpan?.end();
                 return {
@@ -2938,7 +2959,7 @@ async function handleAnthropicAuthRetry(args) {
                         account,
                         tracer,
                         requestStartTime,
-                        attemptNumber,
+                        attemptNumber: retryAttemptNumber,
                         logProxyBody,
                         logFinalRequest,
                     }),
@@ -2951,7 +2972,6 @@ async function handleAnthropicAuthRetry(args) {
                     upstreamSpan: undefined,
                 };
             }
-            recordAttemptError(account.label, account.type, retryStatus);
             // Construction rejections return through the terminal 400 path above.
             // Every 429 reaching this branch is a genuine rate limit and must cool
             // the account according to its reset window before rotating.
@@ -2965,6 +2985,13 @@ async function handleAnthropicAuthRetry(args) {
                     accountState.quota = retryQuota429;
                 }
                 const retryPlan = planCooldownFor429(retryQuota429, parseRetryAfterMs(retryRespHeaders["retry-after"] ?? null), nowRetry, getUnifiedRateLimitStatus(retryRespHeaders));
+                const rateLimitKind = retryPlan.reason === "transient" ? "transient" : "quota";
+                recordAttemptError(account.label, account.type, retryStatus, rateLimitKind);
+                retryLogAttempt(429, "rate_limit_error", retryBody, {
+                    retryable: true,
+                    rateLimitKind,
+                    cooldownReason: retryPlan.reason,
+                });
                 if (!accountState.coolingUntil ||
                     retryPlan.coolingUntil > accountState.coolingUntil) {
                     accountState.coolingUntil = retryPlan.coolingUntil;
@@ -2982,16 +3009,20 @@ async function handleAnthropicAuthRetry(args) {
                 break;
             }
             if (retryStatus === 401 || retryStatus === 402 || retryStatus === 403) {
+                recordAttemptError(account.label, account.type, retryStatus);
+                retryLogAttempt(retryStatus, "authentication_error", summarizeErrorMessage(retryBody), { retryable: true });
                 if (authRetry < MAX_AUTH_RETRIES - 1) {
                     await sleep(1000);
                 }
                 continue;
             }
             if (isTransientHttpFailure(retryStatus, retryBody)) {
+                recordAttemptError(account.label, account.type, retryStatus);
+                retryLogAttempt(retryStatus, "api_error", summarizeErrorMessage(retryBody), { retryable: true });
                 currentSawTransientFailure = true;
                 break;
             }
-            logAttempt(retryStatus, "api_error", summarizeErrorMessage(retryBody));
+            retryLogAttempt(retryStatus, "api_error", summarizeErrorMessage(retryBody));
             recordFinalError(retryStatus, account.label, account.type);
             try {
                 logFinalRequest(retryStatus, account.label, account.type, "api_error", summarizeErrorMessage(retryBody));
@@ -3028,6 +3059,7 @@ async function handleAnthropicAuthRetry(args) {
                 : String(retryFetchErr);
             authRetryError = `network error on retry ${authRetry + 1}: ${message}`;
             currentLastError = authRetryError;
+            retryLogAttempt(502, "network_error", message, { retryable: true });
             logger.debug(`[proxy] ${authRetryError}`);
             break;
         }
@@ -3036,7 +3068,6 @@ async function handleAnthropicAuthRetry(args) {
         // No persistent cooldown — just move to next account for this request.
         currentLastError = authRetryError;
         logger.always(`[proxy] ⚠ account=${account.label} auth retries exhausted, rotating to next account`);
-        logAttempt(401, "authentication_error", authRetryError);
         tracer?.setError("authentication_error", authRetryError);
         tracer?.recordRetry(account.label, "auth_exhausted");
         currentUpstreamSpan?.end();
@@ -3225,11 +3256,17 @@ async function handleAnthropicNonOkResponse(args) {
         };
     }
     if (isTransientHttpFailure(response.status, errBody)) {
-        recordAttemptError(account.label, account.type, response.status);
+        recordAttemptError(account.label, account.type, response.status, response.status === 429 ? "transient" : undefined);
         currentSawTransientFailure = true;
         logger.always(`[proxy] ← ${response.status} account=${account.label} (transient)`);
         currentLastError = errBody;
-        logAttempt(response.status, "api_error", summarizeErrorMessage(errBody));
+        logAttempt(response.status, "api_error", summarizeErrorMessage(errBody), response.status === 429
+            ? {
+                retryable: true,
+                rateLimitKind: "transient",
+                cooldownReason: "transient",
+            }
+            : undefined);
         tracer?.setError("transient_error", summarizeErrorMessage(errBody));
         tracer?.recordRetry(account.label, "transient");
         return {
@@ -3385,7 +3422,7 @@ function createAnthropicAttemptLogger(args) {
         logRequestAttempt({
             timestamp: new Date().toISOString(),
             requestId: ctx.requestId,
-            attempt: attemptNumber,
+            attempt: extra?.attempt ?? attemptNumber,
             method: ctx.method,
             path: ctx.path,
             model: body.model,
@@ -3409,6 +3446,11 @@ function createAnthropicAttemptLogger(args) {
             ...(extra?.cacheReadTokens !== undefined
                 ? { cacheReadTokens: extra.cacheReadTokens }
                 : {}),
+            ...(extra?.retryable !== undefined ? { retryable: extra.retryable } : {}),
+            ...(extra?.rateLimitKind ? { rateLimitKind: extra.rateLimitKind } : {}),
+            ...(extra?.cooldownReason
+                ? { cooldownReason: extra.cooldownReason }
+                : {}),
             ...(traceCtx
                 ? { traceId: traceCtx.traceId, spanId: traceCtx.spanId }
                 : {}),
@@ -3677,7 +3719,6 @@ async function fetchAnthropicAccountResponse(args) {
             };
         }
         sawRateLimit = true;
-        recordAttemptError(account.label, account.type, 429);
         // Parse the unified-window quota headers (present on real rate-limit 429s)
         // and derive a reset-aware cooldown plan. This is the fix for "kept
         // hammering the 5h/7d-exhausted account instead of switching": on an
@@ -3687,12 +3728,18 @@ async function fetchAnthropicAccountResponse(args) {
         const quota = parseQuotaHeaders(errRespHeaders);
         const unifiedStatus = getUnifiedRateLimitStatus(errRespHeaders);
         const cooldownPlan = planCooldownFor429(quota, retryAfterMs, now, unifiedStatus);
+        const rateLimitKind = cooldownPlan.reason === "transient" ? "transient" : "quota";
+        recordAttemptError(account.label, account.type, 429, rateLimitKind);
         logger.always(`[proxy] ← 429 account=${account.label} reason=${cooldownPlan.reason} ` +
             `retry-after=${retryAfterMs}ms 5h-status=${errRespHeaders["anthropic-ratelimit-unified-5h-status"] ?? "unknown"} ` +
             `7d-status=${errRespHeaders["anthropic-ratelimit-unified-7d-status"] ?? "unknown"} ` +
             `unified-status=${unifiedStatus ?? "unknown"} ` +
             `→ ${cooldownPlan.rotateImmediately ? `rotate now, cool ${minutesUntil(cooldownPlan.coolingUntil, now)}m` : "retry same account (transient)"}`);
-        logAttempt(429, "rate_limit_error", String(lastError));
+        logAttempt(429, "rate_limit_error", String(lastError), {
+            retryable: true,
+            rateLimitKind,
+            cooldownReason: cooldownPlan.reason,
+        });
         tracer?.setError("rate_limit_error", String(lastError).slice(0, 500));
         tracer?.recordRetry(account.label, "rate_limit");
         currentUpstreamSpan?.end();
@@ -3940,12 +3987,12 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                     buildUpstreamBody: preparedAttempt.buildUpstreamBody,
                     enabledAccounts,
                     orderedAccounts,
-                    response,
                     tracer,
                     requestStartTime,
-                    fetchStartMs: preparedAttempt.fetchStartMs,
-                    attemptNumber: loopState.attemptNumber,
-                    finalBodyStr: preparedAttempt.finalBodyStr,
+                    allocateAttemptNumber: () => {
+                        loopState.attemptNumber += 1;
+                        return loopState.attemptNumber;
+                    },
                     upstreamSpan,
                     logAttempt,
                     logProxyBody,

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

@@ -459,6 +459,12 @@ export type RequestAttemptLogEntry = {
     responseTimeMs: number;
     errorType?: string;
     errorMessage?: string;
+    /** Whether this failed attempt may be retried without changing the request. */
+    retryable?: boolean;
+    /** Distinguishes short-lived admission throttles from exhausted quota windows. */
+    rateLimitKind?: "transient" | "quota";
+    /** Reset-aware cooldown reason selected for a rate-limited attempt. */
+    cooldownReason?: "transient" | "session" | "weekly" | "unified";
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationTokens?: number;
@@ -505,6 +511,11 @@ export type AnthropicAttemptLogger = (status: number, errorType?: string, errorM
     outputTokens?: number;
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
+    retryable?: boolean;
+    rateLimitKind?: "transient" | "quota";
+    cooldownReason?: "transient" | "session" | "weekly" | "unified";
+    /** Override used when one account selection performs an OAuth retry fetch. */
+    attempt?: number;
 }) => void;
 export type AnthropicLoopState = {
     lastError: unknown;
@@ -578,8 +589,9 @@ export type PreparedAnthropicAccountAttempt = {
 };
 /** How to cool an account after a genuine (non-anti-abuse) 429, derived from
  *  the response's quota headers + retry-after. */
+export type RateLimitCoolingReason = Exclude<AccountCoolingReason, "auth">;
 export type AccountCooldownPlan = {
-    reason: AccountCoolingReason;
+    reason: RateLimitCoolingReason;
     /** Epoch-ms until which the account should not be used. */
     coolingUntil: number;
     /** When true (unified/5h/7d rejected), rotate immediately — retrying the
@@ -619,19 +631,29 @@ export type AccountStats = {
     label: string;
     type: string;
     attemptCount: number;
+    /** Failed upstream attempts, including retries that later recovered. */
+    attemptErrorCount: number;
+    /** Final requests successfully completed by this account. */
     successCount: number;
+    /** Final requests that terminated as errors on this account. */
     errorCount: number;
+    /** All upstream attempts that returned 429. */
     rateLimitCount: number;
+    transientRateLimitCount: number;
+    quotaRateLimitCount: number;
     lastAttemptAt: number;
     lastErrorAt?: number;
 };
 export type ProxyStats = {
     startedAt: number;
     totalAttempts: number;
+    totalAttemptErrors: number;
     totalRequests: number;
     totalSuccess: number;
     totalErrors: number;
     totalRateLimits: number;
+    totalTransientRateLimits: number;
+    totalQuotaRateLimits: number;
     accounts: Record<string, AccountStats>;
 };
 export type RefreshableAccount = {
@@ -1093,6 +1115,21 @@ export type UpdateState = {
     suppressedVersions: Record<string, SuppressedVersion>;
     lastUpdateAt: string | null;
     lastUpdateVersion: string | null;
+    /** Installed by the updater but not yet confirmed as the running version. */
+    pendingRestartVersion: string | null;
+    /** Last updater failure, retained until a successful update or replacement. */
+    lastFailure: {
+        at: string;
+        version: string;
+        stage: "check" | "install" | "validation" | "restart" | "health";
+        message: string;
+    } | null;
+};
+/** Result of validating a newly installed CLI through the stable trampoline. */
+export type InstalledVersionValidation = {
+    version?: string;
+    attempts: number;
+    failure?: string;
 };
 /** Supported global package managers for proxy self-updates. */
 export type GlobalInstallerKind = "npm" | "pnpm";
@@ -1122,6 +1159,31 @@ export type ResolveGlobalInstallerOptions = {
     homeDir?: string;
     execFileSync?: GlobalInstallerExecFile;
 };
+/** Options for validating a newly installed CLI through its stable executable. */
+export type ValidateInstalledVersionOptions = {
+    binPath: string;
+    expectedVersion: string;
+    maxAttempts?: number;
+    delayMs?: number;
+    timeoutMs?: number;
+    execFileSync?: GlobalInstallerExecFile;
+    sleep?: (ms: number) => Promise<void>;
+};
+/** Dependencies and callbacks used to supervise the updater worker process. */
+export type UpdaterWorkerSupervisorOptions = {
+    spawnWorker: () => number | undefined;
+    isProcessRunning: (pid: number) => boolean;
+    stopWorker: (pid: number) => void;
+    onPidChange?: (pid: number | undefined) => void;
+    log?: (message: string) => void;
+    intervalMs?: number;
+};
+/** Handle used by the proxy process to inspect and stop updater supervision. */
+export type UpdaterWorkerSupervisor = {
+    currentPid: () => number | undefined;
+    checkNow: () => number | undefined;
+    stop: () => void;
+};
 /** Shape of the dynamically-imported js-yaml module. `dump` is optional —
  *  read-only consumers (proxy config loader) only need `load`; writers
  *  (CLI primary-account commands) check `dump` before calling. */
@@ -1203,10 +1265,13 @@ export type ProxyStartApp = {
 /** Stats shape consumed by the proxy status printer. */
 export type StatusStats = {
     totalAttempts?: number;
+    totalAttemptErrors?: number;
     totalRequests: number;
     totalSuccess: number;
     totalErrors: number;
     totalRateLimits: number;
+    totalTransientRateLimits?: number;
+    totalQuotaRateLimits?: number;
     accounts?: {
         label: string;
         type: string;
@@ -1214,7 +1279,10 @@ export type StatusStats = {
         requests?: number;
         success?: number;
         errors?: number;
+        attemptErrors?: number;
         rateLimits?: number;
+        transientRateLimits?: number;
+        quotaRateLimits?: number;
         cooling: boolean;
     }[];
 };

package/dist/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/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/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.
  *