cartethyia 2.7.4 → 2.7.5

package/src/security/csrf.ts

@@ -16,7 +16,7 @@ import { isRecord } from "../protocol/codecs";
  * but cannot read the cookie value, so it cannot forge the header.
  */
 export const CSRF_COOKIE_NAME = "csrf_token";
-export const CSRF_HEADER_NAME = "x-csrf-token";
+const CSRF_HEADER_NAME = "x-csrf-token";
 
 /**
  * Name of the session cookie whose presence gates CSRF validation in
@@ -30,7 +30,7 @@ export const SESSION_COOKIE_NAME = "session_token";
  * `SessionCookiePolicy` structurally satisfies this (extra fields are fine),
  * so call sites keep passing their existing policy object unchanged.
  */
-export interface CsrfCookiePolicy {
+interface CsrfCookiePolicy {
   readonly maxAge: number;
   readonly sameSite: "Lax" | "Strict" | "None";
   readonly secure: boolean;

package/src/security/ip-boundary.ts

@@ -3,185 +3,25 @@
 import { isIP } from "node:net";
 import type { TrustedProxyBoundary } from "../config/network";
 import { log } from "../observability/logger";
+import {
+  cidrContainsAddress,
+  ipv4ToNumber,
+  ipv6ToBigInt,
+  isLoopbackAddress,
+  unwrapMappedIpv4,
+} from "../network/ip-utils";
 
-function ipv4ToNumber(address: string): number | undefined {
-  const parts = address.split(".");
-  if (parts.length !== 4 || parts.some((part) => !/^\d+$/.test(part))) return undefined;
-  const octets = parts.map(Number);
-  if (octets.some((part) => part < 0 || part > 255)) return undefined;
-  const [a, b, c, d] = octets;
-  if (a === undefined || b === undefined || c === undefined || d === undefined) return undefined;
-  return ((a * 256 + b) * 256 + c) * 256 + d;
-}
-
-function ipv6ToBigInt(address: string): bigint | undefined {
-  const value = address.toLowerCase().split("%", 1)[0] ?? "";
-  if (value.includes(".")) return undefined;
-  const halves = value.split("::");
-  if (halves.length > 2) return undefined;
-  const left = halves[0] ? halves[0].split(":") : [];
-  const right = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
-  if (halves.length === 1 && left.length !== 8) return undefined;
-  const missing = 8 - left.length - right.length;
-  if (missing < 0 || (halves.length === 2 && missing < 1)) return undefined;
-  const groups = [...left, ...Array.from({ length: missing }, () => "0"), ...right];
-  if (groups.length !== 8 || groups.some((part) => !/^[0-9a-f]{1,4}$/.test(part)))
-    return undefined;
-  let result = 0n;
-  for (const group of groups) result = (result << 16n) | BigInt(Number.parseInt(group, 16));
-  return result;
-}
-
-/**
- * Unwraps an IPv4-mapped IPv6 address to plain IPv4.
- *
- * Bun reports an IPv4 loopback peer as `::ffff:127.0.0.1` on Windows, and
- * `isIP` classifies it as IPv6 — so `ipv6ToBigInt` (which bails on a dotted
- * quad) never matched `127.0.0.1/32`. The trust check therefore failed for the
- * exact peer `TRUSTED_PROXY_CIDRS=127.0.0.1/32` is meant to cover, forwarded
- * headers were ignored, and every cloudflared request stored the loopback peer
- * as the client address. Accepts both the dotted and the hex (`::ffff:7f00:1`)
- * spelling.
- */
-function unwrapMappedIpv4(address: string): string {
-  const value = address.toLowerCase().split("%", 1)[0] ?? "";
-  // Recognize the mapped range STRUCTURALLY, not by its compressed spelling. The
-  // old `startsWith("::ffff:")` test missed any form that writes the leading zero
-  // groups out — `0:0:0:0:0:ffff:7f00:1` is the same host as `::ffff:127.0.0.1`,
-  // but it failed the prefix test, fell through to `ipv6ToBigInt`, and was treated
-  // as an unrelated IPv6 address. The trust check then refused a peer the allowlist
-  // covered, and `canonicalClientIpKey` minted a second key for one host — which is
-  // stored on issued child keys for consistent usage reporting and audit.
-  //
-  // A mapped address is `::ffff:<32 bits>`, i.e. the first 80 bits are zero and the
-  // next 16 are `0xffff`. Matching that is the same test `isIP` uses internally.
-  const tail = mappedIpv4Tail(value);
-  if (tail === undefined) return address;
-  // `mappedIpv4Tail` always returns two hex groups, so the dotted and hex
-  // spellings have already converged by here.
-  const groups = tail.split(":");
-  if (groups.length !== 2) return address;
-  const high = Number.parseInt(groups[0] ?? "", 16);
-  const low = Number.parseInt(groups[1] ?? "", 16);
-  if (!Number.isInteger(high) || !Number.isInteger(low) || high < 0 || high > 0xffff || low < 0 || low > 0xffff)
-    return address;
-  return `${(high >> 8) & 0xff}.${high & 0xff}.${(low >> 8) & 0xff}.${low & 0xff}`;
-}
-
-/**
- * The 32-bit tail of an IPv4-mapped IPv6 address, or `undefined` when `value` is
- * not one. Accepts every spelling of the same address: `::ffff:1.2.3.4`,
- * `::ffff:102:304`, `0:0:0:0:0:ffff:102:304`, and `::ffff:0:102:304`.
- *
- * Works by normalizing to exactly eight 16-bit groups first. That is the only way
- * to compare spellings: a dotted tail is written as ONE colon-separated token but
- * occupies TWO group slots, so any check that counts `split(":")` entries gets the
- * position of the `ffff` marker wrong.
- */
-function mappedIpv4Tail(value: string): string | undefined {
-  const groups = normalizeIpv6Groups(value);
-  if (groups === undefined) return undefined;
-  // The first five groups (80 bits) must be zero, and the sixth must be `ffff`.
-  for (let index = 0; index < 5; index += 1) {
-    if (groups[index] !== "0") return undefined;
-  }
-  if (groups[5] !== "ffff") return undefined;
-  const high = groups[6];
-  const low = groups[7];
-  if (high === undefined || low === undefined) return undefined;
-  return `${high}:${low}`;
-}
-
-/**
- * An IPv6 literal as exactly eight lowercase 16-bit hex groups, or `undefined`
- * when it is not one. Expands a `::` run and converts a trailing dotted quad into
- * the two groups it represents.
- */
-function normalizeIpv6Groups(value: string): string[] | undefined {
-  const text = value.trim();
-  if (text.length === 0) return undefined;
-  const doubleIndex = text.indexOf("::");
-  // More than one `::` is invalid, as is a `::` inside a group.
-  if (doubleIndex !== text.lastIndexOf("::")) return undefined;
-
-  const headText = doubleIndex >= 0 ? text.slice(0, doubleIndex) : text;
-  const tailText = doubleIndex >= 0 ? text.slice(doubleIndex + 2) : "";
-  const head = headText.length > 0 ? headText.split(":") : [];
-  const tail = tailText.length > 0 ? tailText.split(":") : [];
-
-  // A dotted quad is a single token that fills two groups.
-  const expandDotted = (tokens: string[]): string[] | undefined => {
-    const last = tokens[tokens.length - 1];
-    if (last === undefined || !last.includes(".")) return tokens;
-    const quad = last.split(".");
-    if (quad.length !== 4) return undefined;
-    const octets = quad.map((part) => Number(part));
-    if (octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return undefined;
-    const [a, b, c, d] = octets;
-    if (a === undefined || b === undefined || c === undefined || d === undefined) return undefined;
-    const high = ((a << 8) | b).toString(16);
-    const low = ((c << 8) | d).toString(16);
-    return [...tokens.slice(0, -1), high, low];
-  };
-
-  const expandedHead = expandDotted(head);
-  const expandedTail = expandDotted(tail);
-  if (expandedHead === undefined || expandedTail === undefined) return undefined;
-
-  let full: string[];
-  if (doubleIndex >= 0) {
-    const missing = 8 - expandedHead.length - expandedTail.length;
-    // `::` must stand for at least one group, so exactly-8 without it is invalid.
-    if (missing < 1) return undefined;
-    full = [...expandedHead, ...Array.from({ length: missing }, () => "0"), ...expandedTail];
-  } else {
-    full = expandedHead;
-  }
-  if (full.length !== 8) return undefined;
-  const normalized: string[] = [];
-  for (const group of full) {
-    if (!/^[0-9a-f]{1,4}$/.test(group)) return undefined;
-    normalized.push(Number.parseInt(group, 16).toString(16));
-  }
-  return normalized;
-}
+export { isLoopbackAddress };
 
 function matchesCidr(address: string, cidr: string): boolean {
-  const [network, rawPrefix] = cidr.split("/");
-  if (!network) return false;
-  // A bare address (`"127.0.0.1"`) has no prefix and means "this exact host". A
-  // present-but-blank prefix (`"10.0.0.0/"`) must NOT be treated as /0: `Number("")`
-  // is 0, and /0 matches every address — which made `isTrustedProxyPeer` true for
-  // ANY peer, so the gateway believed a caller's own `X-Forwarded-For` and every
-  // per-address decision downstream (abuse throttling, model bans, the audit
-  // trail) read a forged value.
-  //
-  // Requiring a run of digits also refuses the exotic spellings `Number` accepts
-  // for zero (`-0`, `+0`, `0x0`, `0b0`, `0o0`, `0.0`), all of which are typos
-  // rather than a deliberate "trust everyone".
-  const prefixText = rawPrefix === undefined ? undefined : rawPrefix.trim();
-  if (prefixText !== undefined && !/^\d+$/.test(prefixText)) return false;
-  // A mapped peer and a plain-IPv4 allowlist entry describe the same host.
-  const subject = unwrapMappedIpv4(address);
-  const base = unwrapMappedIpv4(network);
-  const family = isIP(subject);
-  if (family === 4) {
-    const value = ipv4ToNumber(subject);
-    const networkValue = ipv4ToNumber(base);
-    if (value === undefined || networkValue === undefined) return false;
-    const prefix = prefixText === undefined ? 32 : Number(prefixText);
-    if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32) return false;
-    const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
-    return ((value >>> 0) & mask) === ((networkValue >>> 0) & mask);
-  }
-  if (family !== 6) return false;
-  const value = ipv6ToBigInt(subject);
-  const networkValue = ipv6ToBigInt(base);
-  if (value === undefined || networkValue === undefined) return false;
-  const prefix = prefixText === undefined ? 128 : Number(prefixText);
-  if (!Number.isInteger(prefix) || prefix < 0 || prefix > 128) return false;
-  const shift = BigInt(128 - prefix);
-  return (value >> shift) === (networkValue >> shift);
+  // `unwrapMapped: true`: a mapped peer and a plain-IPv4 allowlist entry
+  // describe the same host (Bun reports the IPv4 loopback peer as
+  // `::ffff:127.0.0.1` on Windows). `requirePrefix: false`: a bare address
+  // (`"127.0.0.1"`) means "this exact host".
+  return cidrContainsAddress(address, cidr, {
+    requirePrefix: false,
+    unwrapMapped: true,
+  });
 }
 
 function isTrustedPeer(peer: string, boundary: TrustedProxyBoundary): boolean {
@@ -206,20 +46,7 @@ const CLIENT_IDENTITY_HEADERS = [
 
 /**
  * True when `address` is a loopback address.
- *
- * Structural, not a string-prefix test: `127.0.0.1`, `::1`, and the mapped
- * `::ffff:127.0.0.1` a Windows/Bun peer arrives as are all the same host, and
- * a prefix test would miss the mapped form — the exact shape that hid this
- * class of bug before.
  */
-export function isLoopbackAddress(address: string): boolean {
-  const normalized = unwrapMappedIpv4(address.trim().split("%", 1)[0] ?? "");
-  if (normalized === "::1") return true;
-  if (isIP(normalized) !== 4) return false;
-  const value = ipv4ToNumber(normalized);
-  // 127.0.0.0/8 — the whole loopback block, not just 127.0.0.1.
-  return value !== undefined && ((value >>> 0) & 0xff000000) === (127 << 24);
-}
 
 /**
  * Whether a peer may vouch for forwarded headers *for client-address

package/src/security/model-access-rule.ts

@@ -24,7 +24,7 @@ import type { ApiKeyModelAccessMode } from "../persistence/schema";
 export type ModelRejectionReason = "model-denied" | "model-not-allowed";
 
 /** The subset of an authorization snapshot this rule reads. */
-export interface ModelAccessPolicy {
+interface ModelAccessPolicy {
   readonly model_access_mode?: ApiKeyModelAccessMode | null | undefined;
   readonly model_list?: readonly string[] | ReadonlySet<string> | null | undefined;
 }

package/src/security/outbound-headers.ts

@@ -21,6 +21,24 @@ export const X_FRAME_OPTIONS = "DENY";
  */
 export const BADGE_IMAGE_ORIGIN = "https://img.shields.io";
 
+/**
+ * Invariant: upstream response headers are NEVER forwarded wholesale to
+ * callers. There is no denylist-and-forward step on the egress path — the
+ * success projection (`proxySuccessHeaders` in
+ * `transport/dispatch/upstream.ts`) rebuilds the caller-facing header set from
+ * scratch (`cache-control: no-store`, `x-request-id`, and
+ * `GATEWAY_SECURITY_HEADERS` below), so credential-bearing upstream fields
+ * (`set-cookie`, `www-authenticate`, `proxy-authorization`) and hop-by-hop
+ * headers can never leak through by omission from a strip list.
+ *
+ * Any future feature that wants to pass upstream response fields to a caller
+ * must copy only the specific content-bearing headers it needs — do not
+ * reintroduce a "forward everything except" filter. A module implementing
+ * exactly that (`src/network/response-headers.ts` + `stripResponseHeaders`)
+ * existed once and was deleted as dead code (see git history for it), because
+ * every egress path had already moved to the rebuild-from-scratch projection.
+ */
+
 /**
  * Security headers on every `/v1` response, whichever path produced it.
  *

package/src/shared/invoke-guard.ts

@@ -0,0 +1,47 @@
+/**
+ * InvokeGuard — a process-local foreground-activity gauge (G-03).
+ *
+ * Every foreground request path signals its activity here: the console control
+ * plane bumps the counter for the duration of each request, and the proxy data
+ * plane exposes its in-flight count through `setProxyBusySource`. The scheduled
+ * worker registry (and the sweep runner between waves) consults
+ * `foregroundBusy()` before starting background work, so a page open / an
+ * invoke in progress is never forced to share the single event loop with a
+ * heavy sweep.
+ *
+ * The defer policy is at the call sites (scheduler: bounded pause before a
+ * tick; sweep runner: bounded pause between waves). This module only owns the
+ * gauge — it never decides when to pause.
+ */
+
+/** Console request counter. Bumped per in-flight console request. */
+let consoleActivity = 0;
+
+/** Optional live source of "the proxy plane is busy" (the in-flight store). */
+let proxyBusySource: (() => boolean) | undefined;
+
+/** Registers the proxy plane's busy source (wired once from the app root). */
+export function setProxyBusySource(source: () => boolean): void {
+  proxyBusySource = source;
+}
+
+/** Marks a foreground console request; returns the matching end callback. */
+export function beginConsoleActivity(): () => void {
+  consoleActivity += 1;
+  let ended = false;
+  return () => {
+    if (ended) return;
+    ended = true;
+    consoleActivity = Math.max(0, consoleActivity - 1);
+  };
+}
+
+/** Live foreground-request count (console counter + proxy source if wired). */
+export function foregroundActivityCount(): number {
+  return consoleActivity + (proxyBusySource?.() === true ? 1 : 0);
+}
+
+/** True when any foreground work is in flight right now. */
+export function foregroundBusy(): boolean {
+  return consoleActivity > 0 || (proxyBusySource?.() ?? false);
+}

package/src/transport/contracts.ts

@@ -54,12 +54,12 @@ export interface CanonicalAdapter {
  */
 
 /** One native service: the path it is served at and the kind its models carry. */
-export interface NativeServiceRoute {
+interface NativeServiceRoute {
   readonly serviceKind: Exclude<ServiceKind, "llm">;
   readonly path: string;
 }
 
-export const NATIVE_SERVICES: readonly NativeServiceRoute[] = [
+const NATIVE_SERVICES: readonly NativeServiceRoute[] = [
   { serviceKind: "systemone", path: "/v1/systemone" },
   { serviceKind: "websearch", path: "/v1/search" },
   { serviceKind: "imageGeneration", path: "/v1/images/generations" },
@@ -75,7 +75,7 @@ export const NATIVE_SERVICE_PATHS: readonly string[] = NATIVE_SERVICES.map(
 );
 
 /** Whether `path` is served by a native service route. */
-export function isNativeServicePath(path: string | undefined): boolean {
+function isNativeServicePath(path: string | undefined): boolean {
   return path !== undefined && NATIVE_SERVICE_PATHS.includes(path);
 }
 
@@ -97,6 +97,15 @@ export function isNativeServicePath(path: string | undefined): boolean {
  */
 export const TOKEN_COUNT_PATH = "/v1/messages/count_tokens";
 
+/**
+ * The native Codex compaction route (`POST /v1/responses/compact`).
+ *
+ * Not a native service (it has no `serviceKind` of its own — Codex rows are
+ * `llm`-adjacent), so it is declared separately from `NATIVE_SERVICE_PATHS`,
+ * but its body is equally opaque and must skip the canonical chat stage.
+ */
+export const RESPONSES_COMPACT_PATH = "/v1/responses/compact";
+
 /**
  * Whether `path` reads a JSON body that is *not* a canonical chat request.
  *
@@ -105,7 +114,7 @@ export const TOKEN_COUNT_PATH = "/v1/messages/count_tokens";
  * will either reject a body the upstream accepts or plan it twice.
  */
 export function isOpaqueBodyRoute(path: string | undefined): boolean {
-  return isNativeServicePath(path) || path === TOKEN_COUNT_PATH;
+  return isNativeServicePath(path) || path === TOKEN_COUNT_PATH || path === RESPONSES_COMPACT_PATH;
 }
 
 /** The route path serving `serviceKind`, when one is declared. */

package/src/transport/dispatch/attempt-finalize.ts

@@ -394,7 +394,7 @@ let captureFailureReported = false;
  * deployment condition that does not change per request, so repeating it for
  * every request would bury the rest of the log without adding information.
  */
-export function reportCaptureFailure(error: unknown): void {
+function reportCaptureFailure(error: unknown): void {
   if (captureFailureReported) return;
   captureFailureReported = true;
   const directory = payloadDirectory();

package/src/transport/dispatch/capture-policy.ts

@@ -1,8 +1,35 @@
 // Tenant payload-capture policy resolved once and shared by dispatch attempts.
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
-import { payloadRetentionMs, resolvePayloadCapture } from "../../observability/payload-capture";
+import { resolvePayloadCapture } from "../../observability/payload-capture";
 import type { TelemetryPayloadDepth, TelemetryPayloadMode } from "../../console/settings/contracts";
 
+/** The resolved payload-capture preference, memoized on the request state. */
+export type PayloadCapturePreference =
+  | {
+      readonly ok: true;
+      readonly mode: TelemetryPayloadMode;
+      readonly depth: TelemetryPayloadDepth;
+      readonly retentionMs: number;
+    }
+  | { readonly ok: false };
+
+/** The slice of request state that memoizes the capture preference. */
+export type CapturePreferenceState = { payloadCapturePreference?: PayloadCapturePreference };
+
+/** Resolves the tenant's capture preference once, memoized on the request state. */
+async function resolveCapturePreference(
+  db: CartethyiaDatabase,
+  tenantId: string | null,
+  state: CapturePreferenceState,
+): Promise<PayloadCapturePreference> {
+  let preference = state.payloadCapturePreference;
+  if (preference === undefined) {
+    preference = await resolvePayloadCapture(db, tenantId);
+    state.payloadCapturePreference = preference;
+  }
+  return preference;
+}
+
 /** Per-stage body cap for the provider request/response tee. */
 export function providerCaptureMaxBytes(depth?: TelemetryPayloadDepth): number {
   if (depth === "moderate") return 2 * 1024 * 1024;
@@ -14,14 +41,9 @@ export function providerCaptureMaxBytes(depth?: TelemetryPayloadDepth): number {
 export async function shouldCaptureProviderBodyForRequest(
   db: CartethyiaDatabase,
   tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
+  state: CapturePreferenceState,
 ): Promise<boolean> {
-  if (state.payloadCapturePreference === undefined) {
-    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
-  }
-  const resolved = state.payloadCapturePreference as
-    | { readonly ok: true; readonly mode: string }
-    | { readonly ok: false };
+  const resolved = await resolveCapturePreference(db, tenantId, state);
   return resolved.ok === true && resolved.mode === "full";
 }
 
@@ -29,14 +51,9 @@ export async function shouldCaptureProviderBodyForRequest(
 export async function resolveCaptureModeForRequest(
   db: CartethyiaDatabase,
   tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
+  state: CapturePreferenceState,
 ): Promise<TelemetryPayloadMode> {
-  if (state.payloadCapturePreference === undefined) {
-    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
-  }
-  const resolved = state.payloadCapturePreference as
-    | { readonly ok: true; readonly mode: TelemetryPayloadMode }
-    | { readonly ok: false };
+  const resolved = await resolveCapturePreference(db, tenantId, state);
   return resolved.ok === true ? resolved.mode : "none";
 }
 
@@ -44,32 +61,12 @@ export async function resolveCaptureModeForRequest(
 export async function resolveCaptureDepthForRequest(
   db: CartethyiaDatabase,
   tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
+  state: CapturePreferenceState,
 ): Promise<TelemetryPayloadDepth> {
-  if (state.payloadCapturePreference === undefined) {
-    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
-  }
-  const resolved = state.payloadCapturePreference as
-    | { readonly ok: true; readonly depth: TelemetryPayloadDepth }
-    | { readonly ok: false };
+  const resolved = await resolveCapturePreference(db, tenantId, state);
   return resolved.ok === true ? resolved.depth : "minimum";
 }
 
-/** Resolve the tenant's payload retention once per request. */
-export async function resolveCaptureRetentionForRequest(
-  db: CartethyiaDatabase,
-  tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
-): Promise<number> {
-  if (state.payloadCapturePreference === undefined) {
-    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
-  }
-  const resolved = state.payloadCapturePreference as
-    | { readonly ok: true; readonly retentionMs: number }
-    | { readonly ok: false };
-  return resolved.ok === true ? resolved.retentionMs : payloadRetentionMs();
-}
-
 /** Combined body cap for the four payload panels at one configured depth. */
 export function captureDepthMaxBytes(depth: TelemetryPayloadDepth): number {
   if (depth === "moderate") return 8 * 1024 * 1024;

package/src/transport/dispatch/empty-stream.ts

@@ -52,13 +52,13 @@ export type EmptyStreamFetch = (
  * unjittered, so a provider returning 200-with-no-events could drive an
  * unbounded wait, and concurrent clients could resynchronize their retries.
  */
-export interface EmptyStreamPolicy {
+interface EmptyStreamPolicy {
   readonly maxEmptyReplays?: number;
   readonly firstEventTimeoutMs?: number;
   readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
 }
 
-export interface EmptyStreamResult {
+interface EmptyStreamResult {
   readonly response: Response;
   readonly tally: StreamTally;
   readonly endpoint: string;
@@ -112,8 +112,7 @@ export async function fetchWithEmptyStreamRecovery(
 
   for (let endpointIndex = 0; endpointIndex < endpoints.length; endpointIndex++) {
     const endpoint = endpoints[endpointIndex]!;
-    const isLastEndpoint = endpointIndex === endpoints.length - 1;
-    const replaysAllowed = isLastEndpoint ? maxReplays : maxReplays;
+    const replaysAllowed = maxReplays;
 
     for (let replay = 0; replay <= replaysAllowed; replay++) {
       // Check abort before each fetch
@@ -167,12 +166,7 @@ export async function fetchWithEmptyStreamRecovery(
       // Empty — replay if we haven't exhausted this endpoint's budget
       if (replay < replaysAllowed) {
         const delay = fallbackRetryDelayMs(replay);
-        try {
-          await sleep(delay, deps.signal);
-        } catch (error) {
-          if (error instanceof GatewayError) throw error;
-          throw error;
-        }
+        await sleep(delay, deps.signal);
       }
     }
   }
@@ -196,9 +190,22 @@ async function fetchWithTimeout(
   signal: AbortSignal,
   timeoutMs: number,
 ): Promise<Response> {
-  // Race the fetch against a first-event timeout
+  // Race the fetch against a first-event timeout. The timer and the abort
+  // listener are both cleaned up once the race settles, so a successful fetch
+  // leaves neither behind.
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const onAbort = (): void => {
+    if (timer !== undefined) clearTimeout(timer);
+    // A client cancellation is the caller's signal; the fetch already races the
+    // same abort signal, so rejecting here only surfaces the 499 envelope.
+    timeoutPromiseReject(
+      new GatewayError("transport_closed", 499, "The request was aborted (request {requestId}). Send it again whenever ready 🙃"),
+    );
+  };
+  let timeoutPromiseReject!: (reason: unknown) => void;
   const timeoutPromise = new Promise<never>((_, reject) => {
-    const timer = setTimeout(() => {
+    timeoutPromiseReject = reject;
+    timer = setTimeout(() => {
       // A first-event timeout is the gateway waiting on a silent upstream (e.g.
       // a provider that holds the request in a queue), not the client leaving.
       // It must surface as a deadline failure, never as a `transport_closed`
@@ -206,19 +213,15 @@ async function fetchWithTimeout(
       // otherwise hide a real upstream wait behind "cancelled by client".
       reject(new GatewayError("deadline_exceeded", 504, "First event timeout (request {requestId}). Some things just take longer 🐢", {}, "upstream"));
     }, timeoutMs);
-    signal.addEventListener("abort", () => {
-      clearTimeout(timer);
-      reject(new GatewayError("transport_closed", 499, "The request was aborted (request {requestId}). Send it again whenever ready 🙃"));
-    }, { once: true });
   });
-
+  signal.addEventListener("abort", onAbort, { once: true });
   try {
     return await Promise.race([
       fetch(url, { headers: request.headers, body: request.body, signal }),
       timeoutPromise,
     ]);
-  } catch (error) {
-    if (error instanceof GatewayError) throw error;
-    throw error;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    signal.removeEventListener("abort", onAbort);
   }
 }