@juspay/neurolink 10.8.10 → 10.8.12

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

@@ -11,8 +11,27 @@
  */
 import type { CommandModule } from "yargs";
 import type { Hono } from "hono";
-import type { AccountAllowlist, LoadedProxyConfig, ModelRouterInterface, ProxyGuardArgs, ProxyNeurolinkRuntime, ProxyStartArgs, ProxyStartStrategy, ProxyStatusArgs, ProxyTelemetryArgs, ProxyReadinessState } from "../../lib/types/index.js";
+import type { AccountAllowlist, LoadedProxyConfig, ModelRouterInterface, ProxyGuardArgs, ProxyNeurolinkRuntime, ProxyStartArgs, ProxyStartStrategy, ProxySupervisorState, ProxyStatusArgs, ProxyTelemetryArgs, ProxyReadinessState } from "../../lib/types/index.js";
 import { ProxyRuntimeConfigStore } from "../../lib/proxy/runtimeConfig.js";
+/**
+ * Drop a supervisor `version` that is not a string.
+ *
+ * `StateFileManager.load()` is a bare `JSON.parse(content) as T` — it validates
+ * nothing. A state file written by a different build, or half-written during a
+ * crash, can carry any JSON type here, and every status renderer interpolates
+ * the field straight into `v${...}`. Coercing at the single load boundary keeps
+ * a non-string from reaching the output as "v[object Object]".
+ */
+export declare function normalizeSupervisorState(state: ProxySupervisorState | null): ProxySupervisorState | null;
+/**
+ * Whether a rolling handoff can actually occur.
+ *
+ * A live supervisor PID alone is not enough: a supervisor from a build
+ * predating rolling state leaves `rolling` absent, and calling that a handoff
+ * makes both `/status` clients and the CLI wait for an activation that will
+ * never come. Gate on the capability, not on the process.
+ */
+export declare function isRollingHandoffCapable(state: ProxySupervisorState | null, isRunning?: (pid: number) => boolean): boolean;
 /**
  * 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

package/dist/cli/commands/proxy.js

@@ -81,8 +81,42 @@ function clearProxyState() {
 function saveProxySupervisorState(state) {
     proxySupervisorStateManager.save(state);
 }
+/**
+ * Drop a supervisor `version` that is not a string.
+ *
+ * `StateFileManager.load()` is a bare `JSON.parse(content) as T` — it validates
+ * nothing. A state file written by a different build, or half-written during a
+ * crash, can carry any JSON type here, and every status renderer interpolates
+ * the field straight into `v${...}`. Coercing at the single load boundary keeps
+ * a non-string from reaching the output as "v[object Object]".
+ */
+export function normalizeSupervisorState(state) {
+    if (!state) {
+        return null;
+    }
+    return typeof state.version === "string" || state.version === undefined
+        ? state
+        : { ...state, version: undefined };
+}
+/**
+ * Whether a rolling handoff can actually occur.
+ *
+ * A live supervisor PID alone is not enough: a supervisor from a build
+ * predating rolling state leaves `rolling` absent, and calling that a handoff
+ * makes both `/status` clients and the CLI wait for an activation that will
+ * never come. Gate on the capability, not on the process.
+ */
+export function isRollingHandoffCapable(state, isRunning = isProcessRunning) {
+    if (!state) {
+        return false;
+    }
+    // Structural, not just non-null: the same unvalidated `as T` load that lets
+    // `version` be an object lets `rolling` be a string.
+    const hasRollingState = typeof state.rolling === "object" && state.rolling !== null;
+    return isRunning(state.pid) && hasRollingState;
+}
 function loadProxySupervisorState() {
-    return proxySupervisorStateManager.load();
+    return normalizeSupervisorState(proxySupervisorStateManager.load());
 }
 function clearProxySupervisorState() {
     proxySupervisorStateManager.clear();
@@ -1556,6 +1590,7 @@ export async function createProxyStartApp(params) {
             : undefined;
         const runtimeState = loadProxyState();
         const supervisorState = loadProxySupervisorState();
+        const rollingSupervisorRunning = isRollingHandoffCapable(supervisorState);
         const updateState = loadUpdateState();
         const cooldowns = await loadAccountCooldowns();
         const storedAccountKeys = new Set();
@@ -1779,6 +1814,7 @@ export async function createProxyStartApp(params) {
             autoUpdate: {
                 enabled: isProxyAutoUpdateEnabled(),
                 supervisorPid: supervisorState?.pid ?? null,
+                supervisorVersion: supervisorState?.version ?? null,
                 rolling: supervisorState?.rolling ?? null,
                 updaterPid: activeUpdaterPid ?? null,
                 updaterRunning: activeUpdaterPid
@@ -1786,7 +1822,16 @@ export async function createProxyStartApp(params) {
                     : false,
                 liveVersion: PROXY_VERSION,
                 latestVersion: updateState?.lastCheckVersion || null,
+                lastDetectedVersion: updateState?.lastCheckVersion || null,
+                installedVersion: updateState?.installedVersion ??
+                    updateState?.lastUpdateVersion ??
+                    null,
+                activatedVersion: PROXY_VERSION,
+                pendingActivationVersion: updateState?.pendingRestartVersion ?? null,
                 pendingRestartVersion: updateState?.pendingRestartVersion ?? null,
+                activationMode: rollingSupervisorRunning
+                    ? "rolling-handoff"
+                    : "restart",
                 deferredUpdate: updateState?.deferredUpdate ?? null,
                 lastCheckAt: updateState?.lastCheckAt ?? null,
                 lastUpdateAt: updateState?.lastUpdateAt ?? null,
@@ -2426,6 +2471,7 @@ async function runLaunchdProxySupervisor(argv, spinner) {
                 host,
                 port,
                 startTime: supervisorStartedAt,
+                version: PROXY_VERSION,
                 updaterPid: currentUpdaterPid,
                 rolling: snapshot,
             });
@@ -2850,11 +2896,18 @@ export const proxyStatusCommand = {
                 autoUpdateEnabled: isProxyAutoUpdateEnabled(),
                 workerVersion: null,
                 supervisorPid: null,
+                supervisorVersion: supervisorState?.version ?? null,
                 supervisorRunning: false,
                 rolling: null,
                 updaterPid: null,
                 updaterRunning: false,
                 latestVersion: updateState?.lastCheckVersion || null,
+                lastDetectedVersion: updateState?.lastCheckVersion || null,
+                installedVersion: updateState?.installedVersion ??
+                    updateState?.lastUpdateVersion ??
+                    null,
+                activatedVersion: supervisorState?.rolling.active?.version ?? null,
+                pendingActivationVersion: updateState?.pendingRestartVersion ?? null,
                 pendingRestartVersion: updateState?.pendingRestartVersion ?? null,
                 deferredUpdate: updateState?.deferredUpdate ?? null,
                 lastUpdateFailure: updateState?.lastFailure ?? null,
@@ -2904,6 +2957,7 @@ export const proxyStatusCommand = {
                     servingState?.lastConfigReloadError ?? null;
                 status.supervisorPid = supervisorPid ?? null;
                 status.supervisorRunning = supervisorRunning;
+                status.supervisorVersion = supervisorState?.version ?? null;
                 status.rolling = supervisorState?.rolling ?? null;
                 status.updaterPid =
                     supervisorState?.updaterPid ?? servingState?.updaterPid ?? null;
@@ -2927,6 +2981,7 @@ export const proxyStatusCommand = {
                             typeof statusData.version === "string"
                                 ? statusData.version
                                 : null;
+                        status.activatedVersion = status.workerVersion;
                         if (typeof liveConfig?.generation === "number") {
                             status.configGeneration = liveConfig.generation;
                         }
@@ -2959,6 +3014,9 @@ export const proxyStatusCommand = {
                 if (status.supervisorPid) {
                     logger.always(`  ${chalk.bold("Supervisor:")} ${status.supervisorRunning ? chalk.cyan(status.supervisorPid) : chalk.red(`${status.supervisorPid} (not running)`)}`);
                 }
+                if (status.supervisorVersion) {
+                    logger.always(`  ${chalk.bold("Supervisor version:")} ${chalk.cyan(`v${status.supervisorVersion}`)}`);
+                }
                 if (status.workerVersion) {
                     logger.always(`  ${chalk.bold("Version:")}    ${chalk.cyan(`v${status.workerVersion}`)}`);
                 }
@@ -2977,8 +3035,14 @@ 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.pendingActivationVersion) {
+                    // A live supervisor PID alone does NOT mean rolling handoff is
+                    // available: a supervisor from a build predating rolling state leaves
+                    // `rolling` absent, and calling that a handoff tells the operator to
+                    // wait for an activation that will never come. Gate on the capability,
+                    // not on the process.
+                    const rollingCapable = status.supervisorRunning && status.rolling !== null;
+                    logger.always(`  ${chalk.bold(rollingCapable ? "Pending handoff:" : "Pending restart:")} ${chalk.yellow(`v${status.pendingActivationVersion} installed; ${rollingCapable ? "rolling activation pending" : "restart pending"}`)}`);
                 }
                 if (status.rolling?.candidate) {
                     logger.always(`  ${chalk.bold("Handoff:")}    ${chalk.yellow(`preparing v${status.rolling.candidate.expectedVersion} (PID ${status.rolling.candidate.pid})`)}`);
@@ -2995,6 +3059,12 @@ export const proxyStatusCommand = {
                 if (status.latestVersion) {
                     logger.always(`  ${chalk.bold("Latest:")}     ${chalk.cyan(`v${status.latestVersion}`)}`);
                 }
+                if (status.installedVersion) {
+                    logger.always(`  ${chalk.bold("Installed:")}  ${chalk.cyan(`v${status.installedVersion}`)}`);
+                }
+                if (status.activatedVersion) {
+                    logger.always(`  ${chalk.bold("Activated:")}  ${chalk.cyan(`v${status.activatedVersion}`)}`);
+                }
                 if (status.lastUpdateFailure) {
                     logger.always(`  ${chalk.bold("Update error:")} ${chalk.red(`${status.lastUpdateFailure.stage}: ${status.lastUpdateFailure.message}`)}`);
                 }

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

@@ -48,7 +48,7 @@ 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. */
+/** Record that the package was validated but live activation is still 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;

package/dist/lib/proxy/updateState.js

@@ -87,6 +87,7 @@ export function getDefaultUpdateState() {
         lastCheckAt: new Date(0).toISOString(),
         lastCheckVersion: "",
         suppressedVersions: {},
+        installedVersion: null,
         lastUpdateAt: null,
         lastUpdateVersion: null,
         pendingRestartVersion: null,
@@ -124,6 +125,20 @@ export function loadUpdateState(stateFilePath) {
             ...getDefaultUpdateState(),
             ...candidate,
             suppressedVersions: candidate.suppressedVersions ?? {},
+            // Backfill order matters for state files written before `installedVersion`
+            // existed. Back then `recordUpdateInstalled()` set ONLY
+            // `pendingRestartVersion`, leaving `lastUpdateVersion` on the previously
+            // activated build — so a validated-but-not-yet-running update lives in
+            // `pendingRestartVersion` and is the newer of the two. Reading
+            // `lastUpdateVersion` first would report the superseded version as
+            // installed and re-offer an update that is already on disk.
+            installedVersion: typeof candidate.installedVersion === "string"
+                ? candidate.installedVersion
+                : typeof candidate.pendingRestartVersion === "string"
+                    ? candidate.pendingRestartVersion
+                    : typeof candidate.lastUpdateVersion === "string"
+                        ? candidate.lastUpdateVersion
+                        : null,
             pendingRestartVersion: typeof candidate.pendingRestartVersion === "string"
                 ? candidate.pendingRestartVersion
                 : null,
@@ -208,15 +223,17 @@ export function recordSuccessfulUpdate(version, stateFilePath) {
     const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
     state.lastUpdateAt = new Date().toISOString();
     state.lastUpdateVersion = version;
+    state.installedVersion = version;
     state.pendingRestartVersion = null;
     state.deferredUpdate = null;
     state.lastFailure = null;
     delete state.suppressedVersions[version];
     saveUpdateState(state, stateFilePath);
 }
-/** Record that package installation completed but the live restart is pending. */
+/** Record that the package was validated but live activation is still pending. */
 export function recordUpdateInstalled(version, stateFilePath) {
     const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.installedVersion = version;
     state.pendingRestartVersion = version;
     state.lastFailure = null;
     saveUpdateState(state, stateFilePath);

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

@@ -297,6 +297,12 @@ export declare function createClaudeProxyRoutes(modelRouter?: ModelRouterInterfa
 declare function reconcileEligibleAccountRuntimeState(account: ProxyPassthroughAccount): void;
 export declare function getTransientSameAccountRetryDelayMs(retryNumber: number): number;
 declare function describeTransportError(error: unknown): string;
+/**
+ * Determine whether a POST can be retried without risking duplicate provider
+ * work. Only failures that prove connection establishment did not complete are
+ * safe; a reset, socket error, or response timeout can happen after dispatch.
+ */
+declare function isRetryableNetworkError(error: unknown): boolean;
 /**
  * Parse a Claude error payload when available.
  */
@@ -338,6 +344,7 @@ export declare const __testHooks: {
     maybeResetPrimaryToHome: typeof maybeResetPrimaryToHome;
     planCooldownFor429: typeof planCooldownFor429;
     reconcileCooldownFromQuota: typeof reconcileCooldownFromQuota;
+    isRetryableNetworkError: typeof isRetryableNetworkError;
     isPermanentRefreshFailure: typeof isPermanentRefreshFailure;
     getStreamFailureDetails: typeof getStreamFailureDetails;
     trackUpstreamReadableStream: typeof trackUpstreamReadableStream;

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

@@ -12,6 +12,7 @@
 import { access, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { Agent } from "undici";
 import { buildStableClaudeCodeBillingHeader, CLAUDE_CLI_USER_AGENT, CLAUDE_CODE_OAUTH_BETAS, getOrCreateClaudeCodeIdentity, parseClaudeCodeUserId, } from "../../auth/anthropicOAuth.js";
 import { clearAccountCooldown, loadAccountCooldowns, saveAccountCooldown, } from "../../proxy/accountCooldown.js";
 import { anthropicAccountKeysEqual, ENV_ANTHROPIC_ACCOUNT_KEY, isAccountAllowed, LEGACY_ANTHROPIC_ACCOUNT_KEY, shouldLoadFallbackCredential, } from "../../proxy/accountSelection.js";
@@ -91,6 +92,21 @@ const AUTH_REFRESH_MAX_COOLDOWN_MS = 5 * 60 * 1000;
  *  to cover the full lifecycle of streaming responses, including extended
  *  thinking from Opus models (which can exceed 5 minutes for large contexts). */
 const UPSTREAM_FETCH_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
+let anthropicUpstreamDispatcher;
+function fetchAnthropicUpstream(url, init) {
+    // Node's global fetch applies Undici's 300s default headers timeout before
+    // the route's 15-minute abort signal. Keep both transport deadlines aligned
+    // with the proxy contract and instantiate lazily so importing routes has no
+    // open transport handles.
+    anthropicUpstreamDispatcher ??= new Agent({
+        headersTimeout: UPSTREAM_FETCH_TIMEOUT_MS,
+        bodyTimeout: UPSTREAM_FETCH_TIMEOUT_MS,
+    });
+    return fetch(url, {
+        ...init,
+        dispatcher: anthropicUpstreamDispatcher,
+    });
+}
 const accountRuntimeState = new Map();
 /** Shared across requests so a concurrent burst gets at most two retries for
  *  the account/window, rather than every request starting its own retry chain. */
@@ -1406,7 +1422,7 @@ async function handleClaudePassthroughRequest(args) {
     recordAttempt("passthrough", "passthrough");
     let response;
     try {
-        response = await fetch("https://api.anthropic.com/v1/messages?beta=true", {
+        response = await fetchAnthropicUpstream("https://api.anthropic.com/v1/messages?beta=true", {
             method: "POST",
             headers: upstreamHeaders,
             body: bodyStr,
@@ -2510,10 +2526,11 @@ async function handleAnthropicStreamingSuccessResponse(args) {
     if (preflight.kind === "transport_error") {
         const message = describeTransportError(preflight.error);
         const partialBody = Buffer.concat(preflight.chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
-        logger.always(`[proxy] stream failed before first chunk account=${account.label}: ${message}; trying next account`);
+        // The POST has already returned a response. The upstream may have started
+        // processing it, so replaying it on another account could duplicate work.
+        logger.always(`[proxy] stream failed before first chunk account=${account.label}: ${message}; returning terminal error to avoid replaying an ambiguous request`);
         recordAttemptError(account.label, account.type, 502);
-        logAttempt(502, "stream_error", message, { retryable: true });
-        tracer?.recordRetry(account.label, "stream_before_first_chunk");
+        logAttempt(502, "stream_error", message, { retryable: false });
         upstreamSpan?.end();
         logProxyBody({
             phase: "upstream_response",
@@ -2529,8 +2546,16 @@ async function handleAnthropicStreamingSuccessResponse(args) {
             metadata: { logicalStatus: 502, transportError: message },
         });
         return {
-            retryNextAccount: true,
-            failure: { message, rateLimit: false },
+            response: finalizeAnthropicTerminalTransportError({
+                account,
+                tracer,
+                requestStartTime,
+                attemptNumber,
+                logProxyBody,
+                logFinalRequest,
+                errorType: "stream_error",
+                message,
+            }),
         };
     }
     if (preflight.kind === "empty") {
@@ -3176,7 +3201,7 @@ async function handleAnthropicAuthRetry(args) {
             metadata: { upstreamMethod: "POST", upstreamUrl: url },
         });
         try {
-            const retryResp = await fetch(url, {
+            const retryResp = await fetchAnthropicUpstream(url, {
                 method: "POST",
                 headers,
                 body: retryBodyStr,
@@ -3387,11 +3412,37 @@ async function handleAnthropicAuthRetry(args) {
                 : String(retryFetchErr);
             authRetryError = `network error on retry ${authRetry + 1}: ${message}`;
             currentLastError = authRetryError;
+            const retryable = isRetryableNetworkError(retryFetchErr);
             retryLogAttempt(502, "network_error", message, {
-                retryable: isRetryableNetworkError(retryFetchErr),
+                retryable,
                 errorCode: getErrorCode(retryFetchErr) ?? "unknown",
             });
             logger.debug(`[proxy] ${authRetryError}`);
+            if (!retryable) {
+                // Once a POST has left this process, a reset/timeout or unknown fetch
+                // failure is ambiguous: retrying it on another account can duplicate
+                // the request. Only connection-establishment failures are replay-safe.
+                currentUpstreamSpan?.end();
+                return {
+                    response: finalizeAnthropicTerminalTransportError({
+                        account,
+                        tracer,
+                        requestStartTime,
+                        attemptNumber: retryAttemptNumber,
+                        logProxyBody,
+                        logFinalRequest,
+                        errorType: "network_error",
+                        message,
+                    }),
+                    continueLoop: false,
+                    lastError: currentLastError,
+                    authFailureMessage: currentAuthFailureMessage,
+                    sawRateLimit: currentSawRateLimit,
+                    sawTransientFailure: currentSawTransientFailure,
+                    sawNetworkError: currentSawNetworkError,
+                    upstreamSpan: undefined,
+                };
+            }
             break;
         }
     }
@@ -3470,6 +3521,27 @@ function finalizeAnthropicTerminalFetchError(args) {
         errorType: terminalError.errorType,
     });
 }
+function finalizeAnthropicTerminalTransportError(args) {
+    const { account, tracer, requestStartTime, attemptNumber, logProxyBody, logFinalRequest, errorType, message, } = args;
+    tracer?.setError(errorType, message);
+    tracer?.end(502, Date.now() - requestStartTime);
+    logFinalRequest(502, account.label, account.type, errorType, message);
+    const clientError = buildClaudeError(502, message);
+    const clientErrorBody = JSON.stringify(clientError);
+    logProxyBody({
+        phase: "client_response",
+        headers: { "content-type": "application/json" },
+        body: clientErrorBody,
+        bodySize: Buffer.byteLength(clientErrorBody, "utf8"),
+        contentType: "application/json",
+        account: account.label,
+        accountType: account.type,
+        attempt: attemptNumber,
+        responseStatus: 502,
+        durationMs: Date.now() - requestStartTime,
+    });
+    return clientError;
+}
 async function handleAnthropicNonOkResponse(args) {
     const { response, account, accountState, enabledAccounts, orderedAccounts, tracer, requestStartTime, fetchStartMs, attemptNumber, logAttempt, logProxyBody, logFinalRequest, lastError, authFailureMessage, sawTransientFailure, invalidRequestFailure, } = args;
     let currentLastError = lastError;
@@ -4043,7 +4115,7 @@ async function fetchAnthropicAccountResponse(args) {
     const currentUpstreamSpan = upstreamSpan;
     let response;
     try {
-        response = await fetch(url, {
+        response = await fetchAnthropicUpstream(url, {
             method: "POST",
             headers,
             body: finalBodyStr,
@@ -4998,37 +5070,23 @@ function describeTransportError(error) {
     return detail ? `${message} (${detail})` : message;
 }
 /**
- * Determine whether a thrown fetch error is a transient connectivity issue.
+ * Determine whether a POST can be retried without risking duplicate provider
+ * work. Only failures that prove connection establishment did not complete are
+ * safe; a reset, socket error, or response timeout can happen after dispatch.
  */
 function isRetryableNetworkError(error) {
     const code = getErrorCode(error);
-    if (code &&
+    return (code !== undefined &&
         [
             "ECONNREFUSED",
-            "ECONNRESET",
+            "EADDRNOTAVAIL",
             // The Anthropic host is fixed, so ENOTFOUND can be a transient resolver
             // outage. Keep it inside the existing bounded same-account retry budget.
             "ENOTFOUND",
-            "ETIMEDOUT",
             "EHOSTUNREACH",
             "UND_ERR_CONNECT_TIMEOUT",
             "UND_ERR_CONNECT",
-            "UND_ERR_SOCKET",
-            "UND_ERR_HEADERS_TIMEOUT",
-        ].includes(code)) {
-        return true;
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    const normalized = message.toLowerCase();
-    return (normalized.includes("econnrefused") ||
-        normalized.includes("econnreset") ||
-        normalized.includes("enotfound") ||
-        normalized.includes("etimedout") ||
-        normalized.includes("timed out") ||
-        normalized.includes("connection error") ||
-        normalized.includes("connect error") ||
-        normalized.includes("fetch failed") ||
-        normalized.includes("socket hang up"));
+        ].includes(code));
 }
 const TRANSIENT_HTTP_STATUSES = new Set([
     408, 500, 502, 503, 504, 520, 521, 522, 523, 524, 525, 526, 529,
@@ -5158,6 +5216,7 @@ export const __testHooks = {
     maybeResetPrimaryToHome,
     planCooldownFor429,
     reconcileCooldownFromQuota,
+    isRetryableNetworkError,
     isPermanentRefreshFailure,
     getStreamFailureDetails,
     trackUpstreamReadableStream,

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

@@ -870,6 +870,8 @@ export type ProxySupervisorState = {
     host: string;
     port: number;
     startTime: string;
+    /** Version loaded by the long-lived supervisor process. */
+    version?: string;
     updaterPid?: number;
     rolling: ProxyRollingState;
 };

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

@@ -1724,6 +1724,15 @@ export type UpdateState = {
     lastCheckAt: string;
     lastCheckVersion: string;
     suppressedVersions: Record<string, SuppressedVersion>;
+    /**
+     * Last package version whose stable trampoline was successfully validated.
+     *
+     * Optional because `UpdateState` is part of the published type surface and a
+     * required addition would break every downstream object literal — and because
+     * state files written before this field existed legitimately omit it.
+     * `loadUpdateState()` always materializes it, so runtime readers see a value.
+     */
+    installedVersion?: string | null;
     lastUpdateAt: string | null;
     lastUpdateVersion: string | null;
     /** Installed by the updater but not yet confirmed as the running version. */

package/dist/proxy/updateState.d.ts

@@ -48,7 +48,7 @@ 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. */
+/** Record that the package was validated but live activation is still 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;

package/dist/proxy/updateState.js

@@ -87,6 +87,7 @@ export function getDefaultUpdateState() {
         lastCheckAt: new Date(0).toISOString(),
         lastCheckVersion: "",
         suppressedVersions: {},
+        installedVersion: null,
         lastUpdateAt: null,
         lastUpdateVersion: null,
         pendingRestartVersion: null,
@@ -124,6 +125,20 @@ export function loadUpdateState(stateFilePath) {
             ...getDefaultUpdateState(),
             ...candidate,
             suppressedVersions: candidate.suppressedVersions ?? {},
+            // Backfill order matters for state files written before `installedVersion`
+            // existed. Back then `recordUpdateInstalled()` set ONLY
+            // `pendingRestartVersion`, leaving `lastUpdateVersion` on the previously
+            // activated build — so a validated-but-not-yet-running update lives in
+            // `pendingRestartVersion` and is the newer of the two. Reading
+            // `lastUpdateVersion` first would report the superseded version as
+            // installed and re-offer an update that is already on disk.
+            installedVersion: typeof candidate.installedVersion === "string"
+                ? candidate.installedVersion
+                : typeof candidate.pendingRestartVersion === "string"
+                    ? candidate.pendingRestartVersion
+                    : typeof candidate.lastUpdateVersion === "string"
+                        ? candidate.lastUpdateVersion
+                        : null,
             pendingRestartVersion: typeof candidate.pendingRestartVersion === "string"
                 ? candidate.pendingRestartVersion
                 : null,
@@ -208,15 +223,17 @@ export function recordSuccessfulUpdate(version, stateFilePath) {
     const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
     state.lastUpdateAt = new Date().toISOString();
     state.lastUpdateVersion = version;
+    state.installedVersion = version;
     state.pendingRestartVersion = null;
     state.deferredUpdate = null;
     state.lastFailure = null;
     delete state.suppressedVersions[version];
     saveUpdateState(state, stateFilePath);
 }
-/** Record that package installation completed but the live restart is pending. */
+/** Record that the package was validated but live activation is still pending. */
 export function recordUpdateInstalled(version, stateFilePath) {
     const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.installedVersion = version;
     state.pendingRestartVersion = version;
     state.lastFailure = null;
     saveUpdateState(state, stateFilePath);

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

@@ -297,6 +297,12 @@ export declare function createClaudeProxyRoutes(modelRouter?: ModelRouterInterfa
 declare function reconcileEligibleAccountRuntimeState(account: ProxyPassthroughAccount): void;
 export declare function getTransientSameAccountRetryDelayMs(retryNumber: number): number;
 declare function describeTransportError(error: unknown): string;
+/**
+ * Determine whether a POST can be retried without risking duplicate provider
+ * work. Only failures that prove connection establishment did not complete are
+ * safe; a reset, socket error, or response timeout can happen after dispatch.
+ */
+declare function isRetryableNetworkError(error: unknown): boolean;
 /**
  * Parse a Claude error payload when available.
  */
@@ -338,6 +344,7 @@ export declare const __testHooks: {
     maybeResetPrimaryToHome: typeof maybeResetPrimaryToHome;
     planCooldownFor429: typeof planCooldownFor429;
     reconcileCooldownFromQuota: typeof reconcileCooldownFromQuota;
+    isRetryableNetworkError: typeof isRetryableNetworkError;
     isPermanentRefreshFailure: typeof isPermanentRefreshFailure;
     getStreamFailureDetails: typeof getStreamFailureDetails;
     trackUpstreamReadableStream: typeof trackUpstreamReadableStream;