cartethyia 2.7.0 → 2.7.2

package/src/network/outbound-fetch.ts

@@ -1,15 +1,14 @@
 // Validated fetch: SSRF-guarded outbound fetch with optional pool-agent support.
 import { GatewayError } from "../protocol/gateway-error";
-import { Agent as HttpAgent, request as httpRequest, type RequestOptions } from "node:http";
-import { Agent as HttpsAgent, request as httpsRequest } from "node:https";
-import { Readable, type Transform } from "node:stream";
-import { createBrotliDecompress, createGunzip, createInflate } from "node:zlib";
+import { Agent as HttpAgent } from "node:http";
+import { Agent as HttpsAgent } from "node:https";
+import { Agent as UndiciAgent, fetch as undiciFetch, type UndiciRequestInit } from "undici";
+import { SocksProxyAgent } from "socks-proxy-agent";
 import { resolveAllAddresses, validateResolvedAddresses } from "./ssrf";
 import type { SsrfPolicy } from "../config/network";
 import { isProxyAgentPair, type ProxyAgentPair } from "./pool/agent";
 import { metrics } from "../observability/metrics";
 import { trackNetworkCall } from "../observability/performance-metrics";
-import { stripResponseHeaders } from "./response-headers";
 // Validated fetch — single egress with ProxyAgent support
 export interface ValidatedFetchOptions {
   readonly fetchFn?: typeof fetch;
@@ -17,73 +16,25 @@ export interface ValidatedFetchOptions {
   readonly maxRedirects?: number;
   readonly resolveFn?: (hostname: string, signal: AbortSignal) => Promise<readonly string[]>;
   readonly agent?: HttpAgent | HttpsAgent | ProxyAgentPair;
+  /**
+   * Proxy URL to route the dial through, forwarded to the runtime-native fetch
+   * (`proxy` option). Pool egress passes the pool's endpoint here; without it
+   * a request that should leave through a proxy leaves directly.
+   */
+  readonly proxyUrl?: string;
+  /**
+   * Fetch implementation used for SOCKS5 dials (via the undici dispatcher).
+   * Defaults to undici's fetch; injectable for offline tests.
+   */
+  readonly socksFetch?: (input: RequestInfo | URL, init?: UndiciRequestInit) => Promise<Response>;
 }
 export type ValidatedFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
 /**
- * Node validates `agent.protocol` per request, so a pool pair contributes
- * the flavor matching the *target* scheme (redirect hops reselect, since
- * the scheme can change mid-chain).
+ * Whether a configured pool/relay agent owns this dial. When it does, the
+ * proxy resolves the upstream target itself, so the local resolve below is an
+ * advisory SSRF check rather than a prerequisite for egress.
  */
-function agentForTarget(
-  agent: HttpAgent | HttpsAgent | ProxyAgentPair | undefined,
-  protocol: string,
-): HttpAgent | HttpsAgent | undefined {
-  if (!agent) return undefined;
-  if (isProxyAgentPair(agent)) return protocol === "https:" ? agent.https : agent.http;
-  return agent;
-}
-
-/**
- * Keep-alive options for the direct (non-pool) egress agents.
- *
- * Matched to `network/pool/agent.ts`, which builds pool agents from
- * `resolveProxyMaxSockets()` / `resolveProxyMaxFreeSockets()` and
- * `PROXY_KEEP_ALIVE_TIMEOUT_MS`. Direct egress has no per-pool config to
- * read, so it uses the documented defaults those resolvers return.
- */
-const DIRECT_AGENT_OPTIONS = {
-  keepAlive: true,
-  maxSockets: 100,
-  maxFreeSockets: 20,
-  timeout: 60_000,
-} as const;
-
-/**
- * An agent whose socket key includes the SSRF-validated address.
- *
- * The direct (non-pool) path pins egress by passing a `lookup` that returns the
- * one validated address, but `Agent#getName` — the keep-alive socket key —
- * hashes only host/port/localAddress/family. Two requests to the same
- * `host:port` that validated to *different* addresses therefore share a pooled
- * socket, and the second one silently egresses to the first one's address:
- * the pin is bypassed without any error surfacing.
- *
- * Including the address in the key makes each validated address its own socket
- * bucket, so a re-resolved address always dials fresh while the *same* address
- * still reuses its socket (keep-alive is preserved, not defeated).
- *
- * This is a real gap, not a theoretical one: with no agent at all the request
- * falls back to the global agent, which has the same key shape *and* is shared
- * with unrelated traffic.
- */
-class PinnedAddressAgent extends HttpAgent {
-  override getName(options: Record<string, unknown> = {}): string {
-    const base = super.getName(options as never);
-    const pinned = (options["lookup"] as { pinnedAddress?: string } | undefined)?.pinnedAddress;
-    return `${base}:${pinned ?? "-"}`;
-  }
-}
-class PinnedAddressHttpsAgent extends HttpsAgent {
-  override getName(options: Record<string, unknown> = {}): string {
-    const base = super.getName(options as never);
-    const pinned = (options["lookup"] as { pinnedAddress?: string } | undefined)?.pinnedAddress;
-    return `${base}:${pinned ?? "-"}`;
-  }
-}
-
-const DIRECT_HTTP_AGENT = new PinnedAddressAgent(DIRECT_AGENT_OPTIONS);
-const DIRECT_HTTPS_AGENT = new PinnedAddressHttpsAgent(DIRECT_AGENT_OPTIONS);
 
 /**
  * Builds the application-relay request used by hosted relay front doors.
@@ -110,162 +61,127 @@ function relayRequest(
   return { url: relayUrl, init: { ...init, headers } };
 }
 
+const CREDENTIAL_HEADERS = ["authorization", "cookie", "proxy-authorization"] as const;
+
+function stripCredentialsOnCrossOrigin(
+  headersInit: HeadersInit | undefined,
+): Headers {
+  const headers = new Headers(headersInit);
+  for (const name of CREDENTIAL_HEADERS) headers.delete(name);
+  return headers;
+}
+
 /**
- * Decompresses an upstream body the way `fetch` would, because this path
- * bypasses `fetch`.
- *
- * `node:http` hands back the raw body and does not decode `content-encoding`,
- * while `fetch`/Undici transparently gunzips. Rebuilding a `Response` around the
- * still-compressed stream therefore told every consumer the body was plain when
- * it was not: `response.text()` returned binary garbage, and a JSON parse on it
- * failed as `platform_unavailable: Claude response is not valid JSON`. That is
- * why only the upstreams that actually compress (`br` for Anthropic) appeared
- * broken while others worked — nothing here requested an encoding, but a server
- * may compress anyway.
- *
- * Returns the stream untouched for `identity`, an unknown encoding, or when no
- * `content-encoding` is present.
+ * The injected dialer. `fetchFn` is the seam offline suites use to record
+ * requests without a socket; the runtime fetch is the only other dialer.
+ */
+function dialer(options: ValidatedFetchOptions): typeof fetch {
+  return options.fetchFn ?? fetch;
+}
+
+/**
+ * Builds the `undici` dispatcher that routes a dial through a SOCKS5 pool
+ * agent. The runtime-native fetch does not support `socks5://` proxies
+ * (`UnsupportedProxyProtocol`), so the socks pair drives the transport via
+ * undici's dispatcher instead — no node `http`/`https` adapter is involved.
  */
-function decompressBody(
-  body: Readable,
-  encoding: string | undefined,
-): { stream: Readable; encoding: string | undefined } {
-  const normalized = encoding?.trim().toLowerCase();
-  if (normalized === undefined || normalized === "" || normalized === "identity") {
-    return { stream: body, encoding: undefined };
+let socksDispatcherCache: WeakMap<SocksProxyAgent, UndiciAgent> | undefined;
+function socksDispatcherFor(agent: SocksProxyAgent): UndiciAgent {
+  socksDispatcherCache ??= new WeakMap();
+  let dispatcher = socksDispatcherCache.get(agent);
+  if (!dispatcher) {
+    dispatcher = new UndiciAgent({
+      connect: async (opts) => {
+        const o = opts as {
+          hostname?: string;
+          port?: number | string;
+          family?: number;
+          lookup?: (hostname: string, options: unknown, cb: (err: Error | null, addresses: unknown) => void) => void;
+        };
+        return await agent.connect(
+          {} as never,
+          {
+            host: o.hostname ?? "localhost",
+            port: Number(o.port ?? 80),
+            ...(o.family === undefined ? {} : { family: o.family }),
+            ...(o.lookup === undefined ? {} : { lookup: o.lookup }),
+          } as never,
+        );
+      },
+    });
+    socksDispatcherCache.set(agent, dispatcher);
   }
-  const decoder: Transform | undefined =
-    normalized === "gzip" || normalized === "x-gzip"
-      ? createGunzip()
-      : normalized === "deflate"
-        ? createInflate()
-        : normalized === "br"
-          ? createBrotliDecompress()
-          : undefined;
-  // An encoding we cannot decode (e.g. zstd) is left alone: forwarding the
-  // header with the raw body keeps the caller's own decoder in charge, which is
-  // strictly better than claiming a plain body we never decoded.
-  if (decoder === undefined) return { stream: body, encoding: normalized };
-  body.on("error", (error) => decoder.destroy(error));
-  return { stream: body.pipe(decoder), encoding: undefined };
+  return dispatcher;
 }
 
-async function pinnedFetch(
+/**
+ * One dial, always through `fetch`.
+ *
+ * The runtime's own fetch (Bun/Undici) is the transport the clients this
+ * gateway impersonates actually use, and several upstreams meter per client
+ * transport fingerprint — OpenCode's anonymous free tier refuses a
+ * Node-stack dial with 429 FreeUsageLimitError while accepting the identical
+ * bytes over this one. There is no Node `http`/`https` path to choose
+ * between: the SSRF resolve/validate pass that runs before this dial is the
+ * security boundary, and it is identical for every caller.
+ *
+ * A configured pool/relay agent is still honored through `dispatcher` when the
+ * runtime supports it (Bun and Undici both do); when it is not supported the
+ * agent is ignored rather than silently replaced by an unvalidated dial.
+ *
+ * `content-length` is set for a known-length body only when the caller did not
+ * set it: without the header the request falls back to chunked encoding, and
+ * some upstream gateways wait for the complete chunked stream before routing
+ * the request — an avoidable round trip per dial.
+ */
+async function dial(
   url: URL,
   init: RequestInit,
-  resolvedAddress: string | undefined,
-  agent?: HttpAgent | HttpsAgent,
+  fetchFn: typeof fetch,
+  proxyUrl: string | undefined,
+  dispatcher?: UndiciAgent,
+  socksFetch: (input: RequestInfo | URL, init?: UndiciRequestInit) => Promise<Response> = undiciFetch,
 ): Promise<Response> {
-  const request = url.protocol === "https:" ? httpsRequest : httpRequest;
   const headers = new Headers(init.headers);
-  // String/Buffer/Uint8Array bodies go direct: routing them through
-  // `new Response(body).arrayBuffer()` copied the whole body per request.
   const rawBody = init.body;
-  const body =
-    rawBody === undefined || rawBody === null
-      ? undefined
-      : typeof rawBody === "string" || Buffer.isBuffer(rawBody) || rawBody instanceof Uint8Array
-        ? rawBody
-        : Buffer.from(await new Response(rawBody).arrayBuffer());
-  const outboundHeaders: Record<string, string> = {};
-  headers.forEach((value, key) => {
-    outboundHeaders[key] = value;
-  });
-  // A known-length JSON/string body must not fall back to chunked encoding.
-  // Upstream gateways may wait for the complete chunked stream before routing
-  // the request, adding an avoidable RTT compared with global fetch/Undici.
-  if (body !== undefined && !headers.has("content-length")) {
-    outboundHeaders["content-length"] =
-      typeof body === "string" ? String(Buffer.byteLength(body, "utf8")) : String(body.byteLength);
+  if (rawBody !== undefined && rawBody !== null && !headers.has("content-length")) {
+    const bytes =
+      typeof rawBody === "string"
+        ? Buffer.byteLength(rawBody, "utf8")
+        : Buffer.isBuffer(rawBody) || rawBody instanceof Uint8Array
+          ? rawBody.byteLength
+          : (await new Response(rawBody).arrayBuffer()).byteLength;
+    headers.set("content-length", String(bytes));
   }
-  const lookup = Object.assign(
-    (
-      _hostname: string,
-      options: { all?: boolean; family?: number } | number,
-      callback: (
-        error: Error | null,
-        address?: string | Array<{ address: string; family: number }>,
-        family?: number,
-      ) => void,
-    ): void => {
-      if (resolvedAddress === undefined) {
-        callback(new Error("no validated address available"));
-        return;
-      }
-      const opts = typeof options === "number" ? { family: options } : options;
-      const family = resolvedAddress.includes(":") ? 6 : 4;
-      if (opts?.all) {
-        callback(null, [{ address: resolvedAddress, family }] as never);
-        return;
-      }
-      callback(null, resolvedAddress, family);
-    },
-    // Read by `PinnedAddressAgent#getName` so the keep-alive socket key
-    // carries the validated address. See the class comment for why.
-    { pinnedAddress: resolvedAddress },
-  ) as unknown as NonNullable<RequestOptions["lookup"]>;
-  // Direct egress gets a dedicated agent as well as the pinning `lookup`.
-  // Passing only `lookup` left the request on the global agent, whose socket
-  // key ignores `lookup` — so a re-resolved address could reuse a socket
-  // dialed against an earlier one and egress past the SSRF check. The direct
-  // agent keys its sockets on the pinned address, so the pin holds.
-  const directAgent = url.protocol === "https:" ? DIRECT_HTTPS_AGENT : DIRECT_HTTP_AGENT;
-  return new Promise<Response>((resolve, reject) => {
-    const nodeRequest = request(
-      {
-        protocol: url.protocol,
-        hostname: url.hostname,
-        port: url.port ? url.port : url.protocol === "https:" ? "443" : "80",
-        path: `${url.pathname}${url.search}`,
-        method: init.method ?? "GET",
-        headers: outboundHeaders,
-        signal: init.signal ?? undefined,
-        ...(agent ? { agent } : { agent: directAgent, lookup }),
-        ...(url.protocol === "https:" ? { servername: url.hostname } : {}),
-      },
-      (response) => {
-        const responseHeaders = stripResponseHeaders(response.headers);
-        const { stream, encoding } = decompressBody(response, response.headers["content-encoding"]);
-        if (encoding === undefined) {
-          // Body is plain (decoded here, or never compressed): the header must
-          // not survive, or the caller would try to decode a decoded body.
-          responseHeaders.delete("content-encoding");
-        }
-        // A compressed body this path cannot decode keeps its header so the
-        // caller's decoder still applies.
-        const webStream = Readable.toWeb(stream) as unknown as ReadableStream<Uint8Array>;
-        resolve(
-          new Response(webStream, {
-            status: response.statusCode ?? 502,
-            headers: responseHeaders,
-          }),
-        );
-      },
-    );
-    nodeRequest.on("error", reject);
-    if (body !== undefined) nodeRequest.write(body);
-    nodeRequest.end();
+  if (dispatcher !== undefined) {
+    return await socksFetch(url, {
+      ...init,
+      headers,
+      dispatcher,
+    });
+  }
+  return await fetchFn(url, {
+    ...init,
+    headers,
+    ...(proxyUrl === undefined ? {} : { proxy: proxyUrl }),
   });
 }
 
-const CREDENTIAL_HEADERS = ["authorization", "cookie", "proxy-authorization"] as const;
-
-function stripCredentialsOnCrossOrigin(
-  headersInit: HeadersInit | undefined,
-): Headers {
-  const headers = new Headers(headersInit);
-  for (const name of CREDENTIAL_HEADERS) headers.delete(name);
-  return headers;
-}
-
 export function createValidatedFetch(options: ValidatedFetchOptions = {}): ValidatedFetch {
   const policy = options.policy ?? {};
   const maxRedirects = options.maxRedirects ?? policy.maxRedirects ?? 3;
   const resolveFn = options.resolveFn ?? resolveAllAddresses;
+  const fetchFn = dialer(options);
   const configuredAgent = options.agent;
   const relayEndpoint = isProxyAgentPair(configuredAgent)
     ? configuredAgent.relayEndpoint
     : undefined;
+  const socksAgent = isProxyAgentPair(configuredAgent)
+    ? configuredAgent.socks
+    : undefined;
+  const socksFetch = options.socksFetch ?? undiciFetch;
+  const proxyUrl =
+    options.proxyUrl ?? (isProxyAgentPair(configuredAgent) ? configuredAgent.proxyUrl : undefined);
   return async (input, init = {}) => {
     const startedAt = performance.now();
     let url = input instanceof Request ? new URL(input.url) : new URL(input.toString());
@@ -319,14 +235,14 @@ export function createValidatedFetch(options: ValidatedFetchOptions = {}): Valid
       let response: Response;
       if (relayEndpoint) {
         const relay = relayRequest(relayEndpoint, url, requestInit);
-        response = options.fetchFn
-          ? await options.fetchFn(relay.url, relay.init)
-          : await pinnedFetch(relay.url, relay.init, relayResolvedAddress!);
-      } else if (options.fetchFn) {
-        response = await options.fetchFn(url, requestInit);
+        // The relay front door is reached directly: it reads the target from
+        // `x-relay-target`/`x-relay-path` and performs the upstream fetch
+        // itself, so the runtime fetch must NOT be given `proxy` here — that
+        // would make it attempt a CONNECT tunnel against the relay, which a
+        // serverless front door refuses (400).
+        response = await dial(relay.url, relay.init, fetchFn, undefined);
       } else {
-        const agent = agentForTarget(configuredAgent, url.protocol);
-        response = await pinnedFetch(url, requestInit, resolvedAddress!, agent);
+        response = await dial(url, requestInit, fetchFn, proxyUrl, socksAgent ? socksDispatcherFor(socksAgent) : undefined, socksFetch);
       }
       if (response.status < 300 || response.status >= 400) {
         trackNetworkCall(url.hostname, performance.now() - startedAt);

package/src/network/pool/agent.ts

@@ -309,6 +309,18 @@ export interface ProxyAgentPair {
    * validated fetcher sends `x-relay-target`/`x-relay-path` to this URL.
    */
   readonly relayEndpoint?: URL;
+  /**
+   * The proxy URL this pool dials through, forwarded to the runtime-native
+   * fetch (`proxy` option). The native transport has no agent concept, so
+   * the URL is what carries the pool egress.
+   */
+  readonly proxyUrl?: string;
+  /**
+   * The SOCKS5 agent instance for socks pools. The runtime-native fetch does
+   * not support `socks5://` proxies, so the validated fetcher drives this via
+   * the `undici` dispatcher when the pool is a socks pair.
+   */
+  readonly socks?: SocksProxyAgent;
 }
 
 export function isProxyAgentPair(value: unknown): value is ProxyAgentPair {
@@ -407,6 +419,7 @@ export function createHttpProxyAgent(
   return {
     http: new HttpProxyAgent(proxy, policy, config, poolId),
     https: new HttpsProxyAgent(proxy, policy, config, poolId),
+    proxyUrl: proxy.toString(),
     ...(isRelayHost(proxy.hostname) ? { relayEndpoint: proxy } : {}),
   };
 }
@@ -472,6 +485,8 @@ export function createSocks5Agent(
   return {
     http: http as unknown as HttpAgent,
     https: https as unknown as HttpsAgent,
+    socks: http,
+    proxyUrl: withCredential(url, credential).toString(),
   };
 }
 

package/src/network/pool/pool-state.ts

@@ -28,6 +28,13 @@ export interface ProxyCooldownEntry {
 export interface PoolRotation {
   readonly key: string;
   readonly rotateCount: number;
+  /**
+   * The strategy that produced this rotation request. `round_robin` serves
+   * `rotateCount` requests per pool before advancing; `random` scatters each
+   * selection across the eligible pools in a fresh random order. Absent means
+   * the default weighted least-loaded scan.
+   */
+  readonly strategy?: "round_robin" | "random";
 }
 
 export interface PoolUsageSnapshot {

package/src/network/pool/selector.ts

@@ -10,6 +10,7 @@
 import { redisEvalNumber, type RedisClient } from "../../persistence/redis";
 import { resolveInflightTtlSeconds } from "../../config/timeouts";
 import { log } from "../../observability/logger";
+import { providerRateLimitIsIpScoped } from "../../providers/provider-metadata";
 import {
   COOLDOWN_CLEAR_SCRIPT,
   COOLDOWN_FLAG_SCRIPT,
@@ -67,6 +68,21 @@ export function effectiveConcurrency(limit: number): number {
   return limit;
 }
 
+/**
+ * In-place Fisher–Yates shuffle. The `random` pool strategy uses it to scatter
+ * each selection across the eligible pools instead of always scanning from a
+ * fixed (or cursor-driven) order, so a burst does not clump onto the first
+ * pool and burn it while siblings sit idle.
+ */
+function shuffleArray<T>(items: T[]): void {
+  for (let i = items.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(Math.random() * (i + 1));
+    const swap = items[i]!;
+    items[i] = items[j]!;
+    items[j] = swap;
+  }
+}
+
 function normalizedWeight(weight: number | undefined): number {
   if (weight === undefined) return DEFAULT_PROXY_WEIGHT;
   if (!Number.isInteger(weight) || weight < 1 || weight > MAX_PROXY_WEIGHT) return 0;
@@ -257,6 +273,20 @@ export class NetworkPoolSelector {
     return `${poolId}::${providerId.toLowerCase()}`;
   }
 
+  /**
+   * Seeds one cooldown entry into the local map without touching Redis.
+   *
+   * Boot restore is the only writer: it replays the durable markers the
+   * previous process recorded (`network_pools.provider_cooldowns`, see
+   * `pool-cooldown-store.ts`) so dispatch starts remembering the egresses the
+   * upstream is still refusing. Anything whose window already passed is
+   * dropped by `restore…` before this is reached.
+   */
+  hydrateProviderCooldown(entry: ProxyCooldownEntry): void {
+    enforceCooldownLimit(this.state.cooldowns);
+    this.state.cooldowns.set(this.cooldownKey(entry.poolId, entry.providerId), entry);
+  }
+
   async flagProviderCooldown(
     poolId: string,
     providerId: string,
@@ -308,12 +338,32 @@ export class NetworkPoolSelector {
    * The entry uses the same storage as a cooldown so every reader that already
    * skips a cooling pool skips this one too; `reason` is what the console
    * renders to tell an operator-blocked proxy from a throttled one.
+   *
+   * Refuses to retire an egress for a provider whose limits belong to a
+   * credential. An address-scoped verdict only exists for providers that count
+   * requests by egress (`ipScopedRateLimit` — opencode); for everyone else a
+   * refusal belongs to the account that was dialed, so retiring the pool would
+   * sideline an address that is still serving every sibling account. Callers
+   * keep their own guard, and this one is the backstop that makes the rule
+   * impossible to route around from a new call site.
    */
   async flagProviderBlocked(
     poolId: string,
     providerId: string,
     reason = "Upstream refused this egress address",
   ): Promise<ProxyCooldownEntry> {
+    if (!providerRateLimitIsIpScoped(providerId)) {
+      log.warn("[pool-selector] refused to block an egress for a non-IP-scoped provider", {
+        networkPoolId: poolId,
+        providerId,
+      });
+      return {
+        poolId,
+        providerId: providerId.toLowerCase(),
+        until: Date.now(),
+        reason,
+      };
+    }
     const entry = await this.flagProviderCooldown(poolId, providerId, PROVIDER_BLOCK_MS, reason);
     const blocked: ProxyCooldownEntry = { ...entry, blocked: true };
     // Rewrite both copies with the flag: the cooldown write above is shared
@@ -455,6 +505,38 @@ export class NetworkPoolSelector {
     await this.clearRedisCooldown(poolId, providerId);
   }
 
+  /**
+   * Releases a *retired* egress only, leaving a cooldown intact.
+   *
+   * The two are one key, so `clearProviderCooldown` cannot be reused: it would
+   * also drop a live 429 cooldown and hand a spent address back to dispatch.
+   * This is the correction a 429 probe is entitled to make — the address is
+   * answering its own rate limiter, so it was never retired — and nothing more.
+   *
+   * No-op when the marker is a cooldown, and no-op when there is no marker.
+   */
+  async clearProviderBlockedOnly(poolId: string, providerId: string): Promise<void> {
+    const key = this.cooldownKey(poolId, providerId);
+    const local = this.state.cooldowns.get(key);
+    if (local !== undefined) {
+      if (local.blocked !== true) return;
+      this.state.cooldowns.delete(key);
+    }
+    if (!this.redis) return;
+    try {
+      const raw = await this.redis.get(proxyCooldownKey(poolId, providerId));
+      const entry = raw ? parseCooldownEntry(raw) : undefined;
+      // A missing or unparseable marker says nothing about the address, and
+      // deleting a key we cannot read would drop a cooldown this is forbidden
+      // from touching. Only a marker that names itself a block is released.
+      if (entry?.blocked !== true) return;
+      await this.clearRedisCooldown(poolId, providerId);
+    } catch {
+      // The local copy is already corrected; the Redis mirror stays until its
+      // TTL or the next write.
+    }
+  }
+
   /**
    * Removes one cooldown marker and its index entry in one atomic step.
    *
@@ -564,6 +646,26 @@ export class NetworkPoolSelector {
     if (scored.length === 0) return undefined;
 
     if (!this.redis) {
+      if (rotation?.strategy === "random") {
+        // Random scatter: shuffle the eligible pools and take the first one
+        // with a free slot, falling through like the ordered scans do.
+        shuffleArray(scored);
+        for (const candidate of scored) {
+          if (this.getInflight(candidate.poolId) >= candidate.capacity) continue;
+          const slot =
+            providerCapacity === undefined
+              ? this.acquire(candidate.poolId, candidate.capacity)
+              : this.acquireProvider(
+                  candidate.poolId,
+                  providerId,
+                  candidate.capacity,
+                  providerCapacity,
+                );
+          if (!slot.acquired) continue;
+          return { poolId: candidate.poolId, release: slot.release };
+        }
+        return undefined;
+      }
       if (rotation) {
         // Round robin: scan from the tenant cursor; a pool that is full falls
         // through to the next offset (failover). Only a successful admission
@@ -662,7 +764,13 @@ export class NetworkPoolSelector {
     // Original (pre-sort) index = absolute rotation position and
     // deterministic tie-breaking.
     const absoluteIndex = new Map(withCounts.map((candidate, index) => [candidate.poolId, index]));
-    if (rotation) {
+    if (rotation?.strategy === "random") {
+      // Random scatter: shuffle before the admit loop, which still enforces
+      // capacity and fails over to the next pool exactly like the ordered
+      // scans — but the order each request tries is fresh, so a burst does
+      // not gang up on the first pools in a fixed order.
+      shuffleArray(withCounts);
+    } else if (rotation) {
       // Round robin orders strictly by the tenant cursor; the CAS admit below
       // still enforces capacity, so a full pool falls through to the next
       // offset exactly like account failover.
@@ -715,7 +823,7 @@ export class NetworkPoolSelector {
       // to the next pool, which is the whole point of the ceiling: the request
       // moves to an egress that still has room for this provider.
       if (result !== 1) continue;
-      if (rotation) {
+      if (rotation && rotation.strategy !== "random") {
         advanceRotation(
           this.state.rotationCursors,
           rotation.key,