@apifuse/provider-sdk 2.2.0-beta.8 → 2.2.0-beta.9

package/dist/server/serve.js

@@ -312,11 +312,22 @@ function toErrorResponse(error, requestId) {
             },
         };
     }
+    // A masked internal error MUST NOT be advertised as retryable: without an
+    // explicit retryable:false the hub (bori provider-backed engine) defaults 5xx
+    // to retryable:true, which turns a deterministic pre-upstream crash into an
+    // infinite START->CONTINUE->restart loop (2026-07-22 catchtable reserve RCA).
+    // We still refuse to leak message/stack — only the error class name (or the
+    // primitive type for non-Error throwables) is surfaced for ops triage.
     return {
         error: {
             code: "internal_error",
             message: "Internal error",
             ...(requestId ? { requestId } : {}),
+            details: {
+                retryable: false,
+                category: "internal_error",
+                errorClass: error instanceof Error ? error.name : typeof error,
+            },
         },
     };
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.8",
+	"version": "2.2.0-beta.9",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/config/loader.ts

@@ -7,6 +7,7 @@ import { Redis } from "ioredis";
 import type { ProviderProxyPolicy, ProviderProxyProvider, TraceConfig } from "../types.js";
 import {
 	NODEMAVEN_DEFAULT_PROTOCOL,
+	NODEMAVEN_MAX_POOL_SIZE,
 	type ProxyProtocol,
 	hasNodemavenCredentials,
 	nodemavenPoolSize,
@@ -822,6 +823,114 @@ export function resolvePolicyProxyPoolSpan(policy: ProviderProxyPolicy): number
 	return chain.reduce((sum, vendor) => sum + vendorPoolSize(vendor, policy), 0);
 }
 
+function vendorMaxPoolSize(vendor: ProxyVendorName): number {
+	return vendor === "nodemaven" ? NODEMAVEN_MAX_POOL_SIZE : SMARTPROXY_MAX_POOL_SIZE;
+}
+
+/**
+ * Absolute upper bound on a chain's attempt span — the sum of each vendor's
+ * *maximum* pool size. Unlike `resolvePolicyProxyPoolSpan` (the configured
+ * span), this backstop is independent of `session.poolSize`, so it never
+ * truncates a legitimately large pool below the point where the flat attempt
+ * index would cross into the next vendor (e.g. a 50-slot NodeMaven pool).
+ */
+export function maxPolicyProxyPoolSpan(policy: ProviderProxyPolicy): number {
+	const chain = resolveVendorChain(policy);
+	if (chain.length === 0) return SMARTPROXY_MAX_POOL_SIZE;
+	return chain.reduce((sum, vendor) => sum + vendorMaxPoolSize(vendor), 0);
+}
+
+const UNSAFE_TRANSPORT_RETRY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE", "TRACE"]);
+
+/**
+ * Transport-retry attempt cap for a policy-managed request. A transport failure
+ * rotates the flat attempt index onto the *next* endpoint (and, once the index
+ * passes the primary vendor's pool span, the *next vendor*), so the cap must be
+ * the chain's full pool span for failover to reach the fallback vendor — the
+ * per-endpoint retry budget (default 3) never gets there.
+ *
+ * The span only widens beyond the caller's retry budget when ALL hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — `HttpRetryOptions.attempts`
+ *    is the documented total-attempt ceiling and must be honoured verbatim;
+ *  - the method is safe/idempotent — an unsafe request must never be duplicated
+ *    across the pool even if some framework default would allow it;
+ *  - the policy resolves a non-empty *registry* vendor chain (smartproxy /
+ *    nodemaven). Static vendors (custom / decodo) and credential-less policies
+ *    resolve no allocator pool, so every attempt would hit the same endpoint
+ *    with no possible crossover — they keep the retry budget.
+ *
+ * The widened cap is bounded by the chain's true maximum span (sum of each
+ * vendor's max pool size), so a large NodeMaven pool (≤50) stays reachable and
+ * a pathological chain can never spin unbounded.
+ */
+/**
+ * True when a policy request is in *implicit chain-rotation* mode: successive
+ * transport attempts rotate the flat index across the concatenated vendor pool
+ * spans (and, past the primary vendor's span, into the fallback vendor). This is
+ * the ONLY mode in which the transport loop widens its attempt cap AND
+ * de-duplicates repeated endpoints — the two behaviours must share one predicate
+ * so they never diverge. It holds when ALL of the widening conditions hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — its `attempts` ceiling is
+ *    the documented contract and must be honoured verbatim against whatever
+ *    endpoint each attempt resolves (even a repeated one), so no de-duplication;
+ *  - the method is safe/idempotent — an unsafe request is never duplicated;
+ *  - the policy resolves a non-empty registry vendor chain (smartproxy /
+ *    nodemaven). Static vendors (custom / decodo) resolve the same URL every
+ *    attempt, so there is nothing to rotate or de-duplicate.
+ */
+export function policyRotatesTransportVendorChain(input: {
+	policy: ProviderProxyPolicy | undefined;
+	usesPolicyAllocator: boolean;
+	explicitRetry: boolean;
+	method: string;
+}): boolean {
+	if (!input.usesPolicyAllocator || !input.policy || input.explicitRetry) {
+		return false;
+	}
+	if (UNSAFE_TRANSPORT_RETRY_METHODS.has(input.method.toUpperCase())) {
+		return false;
+	}
+	return resolveVendorChain(input.policy).length > 0;
+}
+
+export function resolvePolicyTransportAttemptCap(input: {
+	policy: ProviderProxyPolicy | undefined;
+	usesPolicyAllocator: boolean;
+	retryAttempts: number;
+	explicitRetry: boolean;
+	method: string;
+}): number {
+	const budget = Math.max(1, Math.floor(input.retryAttempts));
+	if (
+		!policyRotatesTransportVendorChain({
+			policy: input.policy,
+			usesPolicyAllocator: input.usesPolicyAllocator,
+			explicitRetry: input.explicitRetry,
+			method: input.method,
+		})
+	) {
+		return budget;
+	}
+	const span = Math.min(maxPolicyProxyPoolSpan(input.policy as ProviderProxyPolicy), resolvePolicyProxyPoolSpan(input.policy as ProviderProxyPolicy));
+	return Math.max(budget, span);
+}
+
+/**
+ * A registry vendor chain (smartproxy/nodemaven) resolves a potentially
+ * *different* endpoint per flat attempt index, so a transport retry should
+ * advance across endpoints and de-duplicate once the chain stops yielding new
+ * ones. Static/custom/decodo policies (empty registry chain) resolve the *same*
+ * URL every attempt by design — retrying that same endpoint is intended, so the
+ * transport loop must not de-duplicate them.
+ */
+export function policyResolvesRegistryVendorChain(
+	policy: ProviderProxyPolicy | undefined,
+): boolean {
+	return Boolean(policy) && resolveVendorChain(policy as ProviderProxyPolicy).length > 0;
+}
+
 /** Map a resolved proxy source label to the vendor that served it. */
 export function vendorFromResolvedSource(
 	source: ResolvedProxyConfig["source"],

package/src/define.ts

@@ -25,6 +25,7 @@ import type {
 	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
 	ProviderProxyConfig,
+	ProviderProxyProvider,
 	ProviderPublicProfile,
 	ProviderReviewed,
 	ProviderSecretDeclaration,
@@ -87,6 +88,20 @@ const VALID_PROVIDER_PROXY_AFFINITIES = [
 ] as const;
 const VALID_PROVIDER_STT_MODES = ["optional", "required"] as const;
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
+const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+const NODEMAVEN_PASSWORD_SECRET = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+// Per-vendor provider-declared credential secrets. A required-mode chain must
+// declare every secret of every credentialed vendor it names, so a missing
+// credential fails at build/validation time rather than during a live outage: a
+// declared-but-uncredentialed fallback leg is a silently dead SPOF, which is
+// exactly the failure class the multi-vendor chain exists to remove. Vendors
+// absent from this map (e.g. `custom`/`decodo`, whose credentials come from the
+// `APIFUSE__PROXY__URL` bring-your-own escape hatch, not provider secrets) impose
+// no declaration requirement.
+const VENDOR_REQUIRED_SECRETS: Partial<Record<ProviderProxyProvider, readonly string[]>> = {
+	smartproxy: [SMARTPROXY_APP_KEY_SECRET],
+	nodemaven: [NODEMAVEN_USERNAME_SECRET, NODEMAVEN_PASSWORD_SECRET],
+};
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
 const MCP_TOOL_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_]{0,127}$/;
 const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"] as const;
@@ -446,26 +461,42 @@ function validateProviderProxy(config: {
 			);
 		}
 	}
-	// Smartproxy uses a provider-declared secret; when it is a required-mode
-	// vendor (singular or in the chain) the app key must be declared so a missing
-	// credential fails at build/validation time, not during a live outage.
+	// Every credentialed vendor in a required-mode chain must declare its
+	// provider secret(s) so a missing credential fails at build/validation time,
+	// not during a live outage. This covers the fallback legs too (not just the
+	// first vendor): a declared-but-uncredentialed nodemaven fallback would leave
+	// the chain silently down to a single vendor, reintroducing the SPOF the chain
+	// removes.
 	const vendorChain =
 		proxy.providers && proxy.providers.length > 0
 			? proxy.providers
 			: proxy.provider
 				? [proxy.provider]
 				: [];
-	if (proxy.mode === "required" && vendorChain.includes("smartproxy")) {
-		const hasSmartproxySecret = config.secrets?.some(
-			(secret) => secret.name === SMARTPROXY_APP_KEY_SECRET && secret.required !== false,
-		);
-		if (!hasSmartproxySecret) {
-			throw new ValidationError(
-				`Provider "${config.id}" requires Smartproxy egress but does not declare ${SMARTPROXY_APP_KEY_SECRET}.`,
-				{
-					fix: `Add secrets: [{ name: "${SMARTPROXY_APP_KEY_SECRET}", required: true }] to the provider.`,
-				},
-			);
+	if (proxy.mode === "required") {
+		for (const vendor of vendorChain) {
+			const requiredSecrets = VENDOR_REQUIRED_SECRETS[vendor];
+			if (!requiredSecrets) continue;
+			for (const secretName of requiredSecrets) {
+				// Match the canonical runtime gate (assertRequiredSecretsPresent /
+				// listMissingRequiredSecrets), which enforces only `required === true`
+				// declarations. A declaration that omits `required` (defaulting to
+				// optional) is skipped at runtime, so accepting it here would pass
+				// validation while leaving the credential unenforced until proxy
+				// resolution during a live request — the fail-open gap this check exists
+				// to close.
+				const declared = config.secrets?.some(
+					(secret) => secret.name === secretName && secret.required === true,
+				);
+				if (!declared) {
+					throw new ValidationError(
+						`Provider "${config.id}" requires ${vendor} egress but does not declare ${secretName}.`,
+						{
+							fix: `Add secrets: [{ name: "${secretName}", required: true }] to the provider (every vendor in a required proxy chain must declare its credential secrets).`,
+						},
+					);
+				}
+			}
 		}
 	}
 	// `decodo`/`custom` are deprecated vendor values (string-union members, so the

package/src/runtime/choice.ts

@@ -11,7 +11,7 @@ import {
 	ProviderChoiceTokenError,
 	type ProviderChoiceTokenPayload,
 } from "../choice-token.js";
-import { ProviderError } from "../errors.js";
+import { isProviderError, ProviderError } from "../errors.js";
 import type {
 	CredentialContext,
 	EnvContext,
@@ -23,6 +23,7 @@ import type {
 	ProviderRequestContext,
 	ProviderRuntimeState,
 	ProviderStateDurationString,
+	StateValue,
 } from "../types.js";
 
 export const PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV =
@@ -359,9 +360,29 @@ async function parseServerStoredChoice(options: {
 		storage,
 		contextState: options.contextState,
 	});
-	const record = await namespace.get<ProviderChoiceTokenPayload>(
-		optionsStateKey(options.handle.state_id),
-	);
+	// Reading a server-stored choice back deserializes a persisted value. A
+	// corrupt/undecodable value would otherwise surface as a raw JSON.parse
+	// SyntaxError (or another unexpected throwable) that escapes the choice error
+	// taxonomy, gets masked as internal_error 500, and is treated as retryable by
+	// the hub -> reservation restart loop (2026-07-22 catchtable RCA, candidate A).
+	// Convert any non-branded throwable into a branded invalid_payload so it maps
+	// to a clean, non-retryable 400. Branded ProviderChoiceTokenError and genuine
+	// ProviderError (e.g. Redis-unavailable / state-unavailable) pass through so
+	// their category/retryable semantics are preserved.
+	let record: StateValue<ProviderChoiceTokenPayload> | null;
+	try {
+		record = await namespace.get<ProviderChoiceTokenPayload>(
+			optionsStateKey(options.handle.state_id),
+		);
+	} catch (error) {
+		if (error instanceof ProviderChoiceTokenError || isProviderError(error)) {
+			throw error;
+		}
+		throw new ProviderChoiceTokenError(
+			"invalid_payload",
+			"Provider choice token state payload could not be decoded.",
+		);
+	}
 	if (!record) {
 		throw new ProviderChoiceTokenError(
 			"invalid_payload",

package/src/runtime/http.ts

@@ -1,5 +1,9 @@
 import type { ProxyResolutionOptions } from "../config/loader.js";
-import { resolveProxyConfigAsync } from "../config/loader.js";
+import {
+	policyRotatesTransportVendorChain,
+	resolvePolicyTransportAttemptCap,
+	resolveProxyConfigAsync,
+} from "../config/loader.js";
 import { ProviderError, TransportError } from "../errors.js";
 import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import type {
@@ -8,6 +12,7 @@ import type {
 	HttpResponse,
 	HttpRetrySummary,
 	HttpStreamResponse,
+	ProviderProxyPolicy,
 	RequestOptions,
 	RequestWithMethodOptions,
 	SseMessage,
@@ -41,16 +46,28 @@ type HttpStatusOutcome = {
 	proxyUsed: boolean;
 };
 
-type NativeHttpAttemptOutcome = HttpResponse | HttpStatusOutcome;
+/**
+ * Sentinel returned when a policy-allocator attempt resolved an endpoint that a
+ * prior attempt already tried (an under-filled pool repeats endpoints via the
+ * modulo mapping before the flat offset crosses into the next vendor). The retry
+ * loop advances to the next offset rather than re-issuing the request — but does
+ * NOT treat it as chain exhaustion, so the offset still walks into the fallback
+ * vendor's span.
+ */
+type NativeHttpSkipOutcome = { kind: "dedupe-skip" };
+
+type NativeHttpAttemptOutcome = HttpResponse | HttpStatusOutcome | NativeHttpSkipOutcome;
 
 type NativeHttpAttemptError = TransportError & { proxyUsed?: boolean };
 
-function isHttpStatusOutcome(
-	outcome: HttpResponse | HttpStatusOutcome,
-): outcome is HttpStatusOutcome {
+function isHttpStatusOutcome(outcome: NativeHttpAttemptOutcome): outcome is HttpStatusOutcome {
 	return "kind" in outcome && outcome.kind === "http-status";
 }
 
+function isDedupeSkipOutcome(outcome: NativeHttpAttemptOutcome): outcome is NativeHttpSkipOutcome {
+	return "kind" in outcome && outcome.kind === "dedupe-skip";
+}
+
 async function sleep(ms: number): Promise<void> {
 	if (ms <= 0) return;
 	await new Promise((resolve) => setTimeout(resolve, ms));
@@ -297,6 +314,7 @@ async function fetchNativeHttp(
 	warn: (message: string) => void,
 	statusRetryCodes?: readonly number[],
 	proxyAttemptOffset = 0,
+	dedupe?: { attempted: Set<string> },
 ): Promise<NativeHttpAttemptOutcome> {
 	const requestUrl = appendQueryParams(resolveHttpUrl(baseUrl, url), options.params);
 	const controller = options.timeout ? new AbortController() : undefined;
@@ -306,7 +324,20 @@ async function fetchNativeHttp(
 
 	let proxy: string | undefined;
 	try {
+		// Resolve inside the try (and after the timeout is armed) so allocator
+		// failures are branded as TransportErrors and count against the request
+		// deadline, exactly as an inline resolve would.
 		proxy = await resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffset);
+		// For a registry allocator chain, skip an endpoint a prior attempt already
+		// tried rather than re-issuing the same request. Returning the sentinel
+		// (instead of breaking) lets the loop keep advancing the flat offset until
+		// it crosses into the fallback vendor's pool span.
+		if (dedupe && proxy) {
+			if (dedupe.attempted.has(proxy)) {
+				return { kind: "dedupe-skip" };
+			}
+			dedupe.attempted.add(proxy);
+		}
 		const requestInit: NativeFetchInit = {
 			headers: options.headers,
 			method,
@@ -452,6 +483,58 @@ export function createHttpClient(
 			? { ...headersOptions, throwOnHttpError: false }
 			: headersOptions;
 
+		// Span the whole vendor chain on transport failures. Like ctx.stealth, a
+		// policy-managed proxy resolves a *different* endpoint/vendor per attempt
+		// (the flat proxyAttemptOffset rotates across the concatenated vendor pool
+		// spans), so a transport failure should advance to the next endpoint —
+		// potentially crossing into the fallback vendor — rather than stopping at
+		// the per-endpoint retry budget and stranding the request on the primary
+		// vendor. resolvePolicyTransportAttemptCap widens the cap to the chain span
+		// only for implicit, safe-method allocator requests; explicit retry
+		// policies (their documented `attempts` ceiling), unsafe methods, and
+		// static/non-registry vendors keep the retry budget. Status-code retries
+		// stay bounded by the retry budget regardless; only transport rotation gets
+		// the full span.
+		const policyProxy: ProviderProxyPolicy | undefined = (() => {
+			const policy = clientOptions.proxyPolicy ?? clientOptions.upstream?.proxy;
+			return policy && typeof policy === "object" ? policy : undefined;
+		})();
+		const usesPolicyAllocator = Boolean(policyProxy) && !options.proxy && !clientOptions.proxy;
+		const transportAttemptCap = retryOptions
+			? resolvePolicyTransportAttemptCap({
+					policy: policyProxy,
+					usesPolicyAllocator,
+					retryAttempts: retryOptions.attempts,
+					explicitRetry,
+					method: methodName,
+				})
+			: 1;
+
+		// Track resolved endpoints across a policy-allocator chain. Successive
+		// attempts rotate the flat offset across the concatenated vendor pool
+		// spans, but an under-filled allocation (fewer live endpoints than the
+		// configured pool size) makes the modulo mapping repeat endpoints before
+		// the offset reaches the next vendor. Rather than re-hammering an
+		// already-tried endpoint under backoff, fetchNativeHttp returns a skip
+		// sentinel for a duplicate; the loop then advances the flat offset without
+		// issuing the request, so it keeps walking toward — and into — the fallback
+		// vendor's pool span instead of stalling on the primary vendor.
+		// De-duplication is gated on the SAME predicate that widens the attempt cap
+		// (implicit, safe-method, registry-chain rotation). It must NOT engage for
+		// an explicit retry policy: there the caller's `attempts` count is the
+		// contract and each attempt must issue against whatever endpoint it resolves
+		// — even a repeat — instead of being silently skipped (which would collapse
+		// a `poolSize: 1` + `attempts: 3` request to a single fetch).
+		const dedupeAllocatorEndpoints = policyRotatesTransportVendorChain({
+			policy: policyProxy,
+			usesPolicyAllocator,
+			explicitRetry,
+			method: methodName,
+		});
+		const dedupeContext = dedupeAllocatorEndpoints
+			? { attempted: new Set<string>() }
+			: undefined;
+
 		const executeOnce = (proxyAttemptOffset = 0): Promise<NativeHttpAttemptOutcome> =>
 			fetchNativeHttp(
 				baseUrl,
@@ -462,24 +545,52 @@ export function createHttpClient(
 				warnOnce,
 				statusRetryEnabled ? retryOptions?.statusCodes : undefined,
 				proxyAttemptOffset,
+				dedupeContext,
 			);
 
 		if (!retryEnabled || !retryOptions) {
 			const outcome = await executeOnce();
+			if (isDedupeSkipOutcome(outcome)) {
+				// Single-shot path never de-duplicates (dedupeContext is undefined),
+				// but keep the union total.
+				throw new TransportError("HTTP request produced no terminal result", {
+					code: "retry_exhausted",
+				});
+			}
 			if (isHttpStatusOutcome(outcome)) {
 				throw toUpstreamHttpError(outcome.status);
 			}
 			return outcome;
 		}
 
+		let lastError: unknown;
 		let lastErrorCode: string | undefined;
 		let lastStatus: number | undefined;
-		for (let attempt = 1; attempt <= retryOptions.attempts; attempt += 1) {
+		// `attempt` walks the flat proxy offset across the full chain span; `issued`
+		// counts requests that were actually sent (skipped duplicate offsets do not
+		// increment it). Retry summaries and the status-retry budget must reflect
+		// issued requests, not the raw offset, so they stay accurate when partial
+		// allocations skip offsets.
+		let issued = 0;
+		for (let attempt = 1; attempt <= transportAttemptCap; attempt += 1) {
+			// Whether this offset actually issued a request (vs. a skipped duplicate),
+			// so the catch counts a thrown *transport* failure once without
+			// double-counting a status outcome that already incremented before it
+			// re-threw as an upstream HTTP error.
+			let issuedThisAttempt = false;
 			try {
 				const outcome = await executeOnce(attempt - 1);
+				if (isDedupeSkipOutcome(outcome)) {
+					// Duplicate endpoint from a partial allocation: advance the flat
+					// offset without issuing the request (no backoff, not a failure) so
+					// the loop keeps rotating toward the fallback vendor.
+					continue;
+				}
+				issued += 1;
+				issuedThisAttempt = true;
 				if (isHttpStatusOutcome(outcome)) {
 					lastStatus = outcome.status;
-					if (outcome.retryable && attempt < retryOptions.attempts) {
+					if (outcome.retryable && issued < retryOptions.attempts) {
 						await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers));
 						continue;
 					}
@@ -491,10 +602,10 @@ export function createHttpClient(
 					throw toUpstreamHttpError(response.status);
 				}
 
-				if (attempt > 1) {
+				if (issued > 1) {
 					const summary: HttpRetrySummary = {
-						attempts: attempt,
-						retries: attempt - 1,
+						attempts: issued,
+						retries: issued - 1,
 						...(retryOptions.preset ? { preset: retryOptions.preset } : {}),
 						transport: "native",
 						...(lastErrorCode ? { lastErrorCode } : {}),
@@ -504,11 +615,13 @@ export function createHttpClient(
 				}
 				return response;
 			} catch (error) {
+				if (!issuedThisAttempt) issued += 1;
+				lastError = error;
 				lastErrorCode = proxyTransportRetryErrorCode(error);
 				lastStatus = proxyTransportRetryErrorStatus(error);
 				const proxyUsed = Boolean((error as NativeHttpAttemptError).proxyUsed);
 				if (
-					attempt < retryOptions.attempts &&
+					attempt < transportAttemptCap &&
 					shouldRetryProxyTransportAttempt({
 						error,
 						explicitRetry,
@@ -524,6 +637,13 @@ export function createHttpClient(
 			}
 		}
 
+		// Reached when the attempt cap is consumed without a terminal outcome —
+		// e.g. the final offsets of a partial allocation all resolved to
+		// already-tried endpoints and were skipped. Surface the last real transport
+		// failure rather than a synthetic exhaustion error.
+		if (lastError !== undefined) {
+			throw lastError;
+		}
 		throw new TransportError("HTTP retry exhausted without a terminal result", {
 			code: "retry_exhausted",
 		});

package/src/runtime/proxy-nodemaven.ts

@@ -27,7 +27,7 @@ const NODEMAVEN_PORTS: Record<ProxyProtocol, { min: number; max: number }> = {
 const NODEMAVEN_FILTERS = new Set(["medium", "high"]);
 const DEFAULT_NODEMAVEN_FILTER = "medium";
 const DEFAULT_NODEMAVEN_POOL_SIZE = 20;
-const NODEMAVEN_MAX_POOL_SIZE = 50;
+export const NODEMAVEN_MAX_POOL_SIZE = 50;
 /** NodeMaven sticky sessions persist up to 24h server-side, keyed by the sid. */
 const NODEMAVEN_MAX_LIFETIME_MINUTES = 1440;
 const SID_LENGTH = 10;

package/src/runtime/state.ts

@@ -115,7 +115,17 @@ function envelopeFromJson(
 	// biome-ignore lint/suspicious/noExplicitAny: state envelopes deserialize caller-owned generic values.
 ): StateValue<any> | null {
 	if (!raw) return null;
-	const parsed: unknown = JSON.parse(raw);
+	// A corrupt/undecodable persisted envelope must be treated as absent rather
+	// than throwing a raw JSON.parse SyntaxError: an uncaught SyntaxError escapes
+	// the provider error taxonomy, is masked as internal_error 500, and is then
+	// retried by the hub (2026-07-22 catchtable reserve RCA, candidate A). Returning
+	// null also keeps list() from aborting the whole scan on a single bad entry.
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
 	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
 		return null;
 	}