@bitkyc08/opencodex 2.56.0 → 2.57.0

package/src/images/loop.ts

@@ -615,7 +615,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
                   signal: headerDeadline.signal,
                 }, retryRecovery));
               },
-              { abortSignal: headerDeadline.signal, label: "image-bridge-loop" },
+              { replaySafe: true, abortSignal: headerDeadline.signal, label: "image-bridge-loop" },
             );
           }
         } finally {

package/src/lib/errors.ts

@@ -7,6 +7,15 @@ export interface OcxErrorPayload {
 export const ENCRYPTED_FUNCTION_OUTPUT_REJECTION =
   "Encrypted function output content could not be decrypted or decoded.";
 
+/**
+ * The error identity for a send this proxy declined to make (#4708).
+ *
+ * Declared here rather than only on the error class because the classifier is what decides
+ * whether the identity survives serialization, and every dispatch path has to name the same
+ * string for a client to be able to tell this apart from a provider rate limit.
+ */
+export const SEND_BUDGET_EXHAUSTED_CODE = "request_send_budget_exhausted";
+
 /** Canonical human-readable message paths used by Responses upstream failures. */
 export function upstreamErrorMessageFromPayload(payload: unknown): string | undefined {
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
@@ -253,6 +262,14 @@ export function classifyError(status: number, type: string, message: string): Oc
   ) {
     return { message, type: "insufficient_quota", code: "insufficient_quota" };
   }
+  // A refusal this proxy made itself, kept apart from the provider rate limits below. The HTTP
+  // semantics are identical -- 429, do not send this again now -- but the code is the only thing
+  // that tells an operator reading a log whether the provider throttled the request or whether
+  // this process declined to send it. Folding it into the generic rate-limit code sent them to
+  // the provider's dashboard to explain a decision that was never made there.
+  if (type === SEND_BUDGET_EXHAUSTED_CODE) {
+    return { message, type: "rate_limit_error", code: SEND_BUDGET_EXHAUSTED_CODE };
+  }
   if (
     status === 429 ||
     text.includes("rate limit") ||

package/src/lib/request-execution-budget.ts

@@ -56,6 +56,7 @@ export type BudgetDenial =
   | "final-recovery-spent"
   | "alternate-target-exhausted"
   | "target-transition-exhausted"
+  | "spend-exhausted"
   | "not-replay-safe";
 
 export interface DispatchIntent {
@@ -94,12 +95,45 @@ export interface SingleUseDispatchPermit {
    * once an external send reporter already settled it.
    */
   release(): void;
+  /**
+   * Take over an externally counted booking, because the layer holding this permit is the one
+   * that physically sends.
+   *
+   * `countedExternally` promises that a retry helper will name this send through
+   * `onSendsConsumed`. An adapter that owns its own dispatch ladder -- Kiro's reset loop,
+   * Cursor's transport loop -- reserves per physical send instead, so no reporter ever arrives
+   * and the pending booking would sit there until it silently swallowed an unrelated later
+   * report. Confirming through this method settles the permit AND closes the booking, so the
+   * send stays charged exactly once (#4709). Returns false once the permit is settled, which is
+   * what keeps one permit from admitting two sends.
+   */
+  assumeCharge(): boolean;
 }
 
 export type DispatchDecision =
   | { allowed: true; permit: SingleUseDispatchPermit }
   | { allowed: false; reason: BudgetDenial };
 
+/**
+ * Notified when this request's physical-send count moves.
+ *
+ * `spent` is the only number here that counts SENDS rather than intentions: a reservation
+ * increments it, a refund decrements it, and an externally reported send settles against a
+ * booking that was already counted. Anything that books one entry per increment therefore
+ * books exactly one entry per physical send -- which is what lets the durable spend ledger
+ * have a production caller without every dispatch site in the tree remembering to call it.
+ *
+ * `charge` may refuse, and a refusal denies the dispatch. That is deliberate: the ledger is
+ * the only bound here that survives a restart, so a limit it enforces has to be able to stop a
+ * send rather than merely describe one.
+ */
+export interface RequestSendObserver {
+  /** Book one physical send. False refuses the dispatch before the budget charges it. */
+  charge(): boolean;
+  /** Give back a booking whose send never happened. */
+  refund(): void;
+}
+
 /**
  * Carried on HandleResponsesOptions so a combo child, a rebuild and an alternate-account leg
  * all decrement the same holder. `used` is the existing #4605 counter and still counts every
@@ -134,33 +168,57 @@ const RESERVE_FUNDED_CLASSES: ReadonlySet<SendClass> = new Set<SendClass>([
 
 let logicalRequestSeq = 0;
 
-export function createRequestExecutionBudget(
-  policy: RequestExecutionBudgetPolicy = CODEX_TEXT_GUARDED_BUDGET_POLICY,
-  logicalRequestId?: string,
+/**
+ * One request's physical-send ledger, held apart from the budget object so a derived policy
+ * scope can share the exact same one.
+ *
+ * `spent` and `pendingExternalSends` belong together: a pending booking is a send that is
+ * already counted in `spent` and awaiting its reporter, so a scope that shared one without the
+ * other would either charge that send twice or never charge it at all.
+ *
+ * The durable-spend observer belongs here for the same reason. It books one entry per physical
+ * send by watching this counter move, so a derived scope that spent the counter without
+ * carrying the observer would move it without booking, and a combo child's sends would go
+ * missing from the ledger (#4707).
+ */
+interface SharedSendLedger {
+  spent: number;
+  pendingExternalSends: number;
+  readonly observer?: RequestSendObserver;
+}
+
+const sharedSendLedgers = new WeakMap<RequestExecutionBudget, SharedSendLedger>();
+
+function createRequestExecutionBudgetWithLedger(
+  policy: RequestExecutionBudgetPolicy,
+  logicalRequestId: string | undefined,
+  counter: SharedSendLedger,
 ): RequestExecutionBudget {
-  let spent = 0;
-  // Reservations whose physical send is reported by a retry helper rather than by the permit.
-  // They are already charged; the reporter's first send settles one instead of charging again.
-  let pendingExternalSends = 0;
+  const observer = counter.observer;
   let reserveSpent = false;
   let alternateTargetSends = 0;
   let targetTransitions = 0;
   let lastTargetKey: string | undefined;
 
   const budget: RequestExecutionBudget = {
-    get used(): number { return spent; },
+    get used(): number { return counter.spent; },
     set used(next: number) {
       // The retry helpers report their real send count by assigning through this field. A
       // reservation taken with `countedExternally` has already booked one of those sends, so
       // the report settles the pending booking first and only the surplus is charged.
-      const delta = next - spent;
+      const delta = next - counter.spent;
       if (delta <= 0) {
-        spent = Math.max(0, next);
+        counter.spent = Math.max(0, next);
         return;
       }
-      const settled = Math.min(delta, pendingExternalSends);
-      pendingExternalSends -= settled;
-      spent += delta - settled;
+      const settled = Math.min(delta, counter.pendingExternalSends);
+      counter.pendingExternalSends -= settled;
+      const charged = delta - settled;
+      counter.spent += charged;
+      // These sends have already left. The ledger records them even past a ceiling it would
+      // have refused, because refusing after the fact only hides spend that was really
+      // incurred -- the refusal has to happen at the reservation below, or not at all.
+      for (let index = 0; index < charged; index += 1) observer?.charge();
     },
     logicalRequestId: logicalRequestId ?? `lr-${Date.now().toString(36)}-${(logicalRequestSeq += 1).toString(36)}`,
     policyVersion: REQUEST_BUDGET_POLICY_VERSION,
@@ -171,11 +229,11 @@ export function createRequestExecutionBudget(
     get lastTargetKey() { return lastTargetKey; },
     remainingBaseSends(cap: number): number {
       const capped = Number.isFinite(cap) ? Math.trunc(cap) : 0;
-      return Math.max(0, Math.min(capped, policy.baseSendAllowance - spent));
+      return Math.max(0, Math.min(capped, policy.baseSendAllowance - counter.spent));
     },
     reserveDispatch(intent: DispatchIntent): DispatchDecision {
       if (intent.replaySafe === false) return { allowed: false, reason: "not-replay-safe" };
-      if (spent >= policy.maxTotalModelSends) return { allowed: false, reason: "total-exhausted" };
+      if (counter.spent >= policy.maxTotalModelSends) return { allowed: false, reason: "total-exhausted" };
 
       const changesTarget = lastTargetKey !== undefined && lastTargetKey !== intent.targetKey;
       const isAlternateTarget = changesTarget || intent.sendClass === "account-failover"
@@ -190,7 +248,7 @@ export function createRequestExecutionBudget(
       // The base allowance is spent first. Only once it is gone does a recovery class reach
       // for the single shared reserve -- an account move and a validated rebuild cannot each
       // take one.
-      const drawsReserve = policy.baseSendAllowance - spent <= 0;
+      const drawsReserve = policy.baseSendAllowance - counter.spent <= 0;
       if (drawsReserve) {
         if (!RESERVE_FUNDED_CLASSES.has(intent.sendClass)) {
           return { allowed: false, reason: "base-allowance-exhausted" };
@@ -200,13 +258,18 @@ export function createRequestExecutionBudget(
         }
       }
 
+      // Consulted last, because it is the only bound here that WRITES. A ledger entry booked
+      // for a dispatch a cheaper check above would have refused is spend this request never
+      // makes, and it would hold those tokens against the scope until retention expired.
+      if (observer && !observer.charge()) return { allowed: false, reason: "spend-exhausted" };
+
       // THE RESERVATION IS THE CHARGE. Deciding here and charging in `use()` left a window in
       // which two legs read the same remainder, both received a permit, and both dispatched:
       // one remaining send admitted two physical sends, which is the per-request multiplication
       // this budget exists to stop. Everything is booked now; `release()` is the way back.
       const previousTargetKey = lastTargetKey;
-      spent += 1;
-      if (intent.countedExternally === true) pendingExternalSends += 1;
+      counter.spent += 1;
+      if (intent.countedExternally === true) counter.pendingExternalSends += 1;
       if (drawsReserve) reserveSpent = true;
       if (isAlternateTarget) alternateTargetSends += 1;
       if (changesTarget) targetTransitions += 1;
@@ -222,16 +285,28 @@ export function createRequestExecutionBudget(
             settled = "used";
             return true;
           },
+          assumeCharge(): boolean {
+            if (settled !== "open") return false;
+            settled = "used";
+            // The booking this reservation made for an external reporter is now owned by the
+            // caller. Leaving it pending is not harmless: the next `used` report of this request
+            // would settle against it and one real send would go uncharged.
+            if (intent.countedExternally === true && counter.pendingExternalSends > 0) {
+              counter.pendingExternalSends -= 1;
+            }
+            return true;
+          },
           release(): void {
             if (settled !== "open") return;
             settled = "released";
             // An externally counted reservation the reporter already settled paid for a send
             // that physically happened. Refunding it would hand the request a free send back.
             if (intent.countedExternally === true) {
-              if (pendingExternalSends === 0) return;
-              pendingExternalSends -= 1;
+              if (counter.pendingExternalSends === 0) return;
+              counter.pendingExternalSends -= 1;
             }
-            spent -= 1;
+            counter.spent -= 1;
+            observer?.refund();
             if (drawsReserve) reserveSpent = false;
             if (isAlternateTarget) alternateTargetSends -= 1;
             if (changesTarget) targetTransitions -= 1;
@@ -241,9 +316,60 @@ export function createRequestExecutionBudget(
       };
     },
   };
+  sharedSendLedgers.set(budget, counter);
   return budget;
 }
 
+export function createRequestExecutionBudget(
+  policy: RequestExecutionBudgetPolicy = CODEX_TEXT_GUARDED_BUDGET_POLICY,
+  logicalRequestId?: string,
+  observer?: RequestSendObserver,
+): RequestExecutionBudget {
+  return createRequestExecutionBudgetWithLedger(policy, logicalRequestId, {
+    spent: 0,
+    pendingExternalSends: 0,
+    ...(observer ? { observer } : {}),
+  });
+}
+
+/**
+ * A budget that applies its own policy and keeps its own recovery ledgers while spending the
+ * parent's exact physical-send ledger.
+ *
+ * Aliasing the public `used` property was not enough, and that is the whole defect. The factory
+ * reads its own private counter back in `remainingBaseSends`, in the total check, and in the
+ * reserve test, so an aliased scope answered every admission question from a counter that only
+ * ever saw its own reservations. A combo's per-target holdback is computed from
+ * `maxTotalModelSends` and is therefore unenforceable unless the scope actually observes what
+ * the request has already spent.
+ */
+export function deriveRequestExecutionBudget(
+  parent: RequestExecutionBudget,
+  policy: RequestExecutionBudgetPolicy,
+): RequestExecutionBudget {
+  return createRequestExecutionBudgetWithLedger(policy, parent.logicalRequestId, ledgerFor(parent));
+}
+
+/**
+ * A budget that did not come from this factory still honors the public `used` contract, so
+ * bridge onto it rather than failing the request. `isRequestExecutionBudget` is a shape test,
+ * so a stub can reach here; turning that into a thrown error would convert a routing request
+ * into a 500 to report a condition production never produces. Only a factory-backed parent can
+ * share pending external bookings and a durable-spend observer, which are private by
+ * construction; a bridged scope keeps the parent's spend accurate and books nothing of its own.
+ */
+function ledgerFor(parent: RequestExecutionBudget): SharedSendLedger {
+  const existing = sharedSendLedgers.get(parent);
+  if (existing) return existing;
+  let pendingExternalSends = 0;
+  return {
+    get spent(): number { return parent.used; },
+    set spent(next: number) { parent.used = next; },
+    get pendingExternalSends(): number { return pendingExternalSends; },
+    set pendingExternalSends(next: number) { pendingExternalSends = next; },
+  };
+}
+
 export function isRequestExecutionBudget(
   value: TransientSendBudget | undefined,
 ): value is RequestExecutionBudget {

package/src/lib/spend-reservation-ledger.ts

@@ -669,6 +669,24 @@ export function createSpendReservationLedger(options: {
         case "checkpoint": applyCheckpoint(record); break;
       }
     }
+    // A reservation that survived replay has no owner left. The process that made it is gone,
+    // so nothing in this one can ever settle it, and leaving it live means the send stays
+    // pending forever against a scope that can never resolve it. Deleting the entry is not the
+    // alternative either: that would hand the same send id a second reservation.
+    //
+    // Both live states resolve to UNRESOLVED, including an undispatched one. The tempting
+    // distinction -- open never reached the wire, so give its tokens back -- assumes the
+    // journal is complete up to the crash, and the torn-tail handling above says it is not: a
+    // send can dispatch and die before its dispatch record lands. Abandoning that reservation
+    // returns tokens for a send that may have been billed, and worse, it RESETS a ceiling that
+    // had already fired. An exhausted scope staying exhausted across a restart is the whole
+    // reason this store is on disk.
+    const reconciledAt = now();
+    for (const [send, reservation] of reservations) {
+      if (!isLive(reservation.status)) continue;
+      applyResolve(send, "lost", 0, reconciledAt);
+      append({ v: 1, kind: "lost", send, at: reconciledAt });
+    }
   }
 
   /**

package/src/lib/state-store-registrations.ts

@@ -21,7 +21,7 @@ import {
 } from "../combos/failover";
 import { reconcileComboWarningMemos } from "../combos/request";
 import { reconcileComboRotationState } from "../combos/resolve";
-import { reconcileComboRecall } from "../server/responses/combo-session-recall";
+import { reconcileComboRecall, sweepExpiredComboRecall } from "../server/responses/combo-session-recall";
 import { listLiveComboTargetKeys } from "../combos/types";
 import {
   listLiveConfigOwnershipRoots,
@@ -112,7 +112,11 @@ export const STATE_STORE_REGISTRATIONS = [
   { name: "model-cache-history", reconcileGeneration: reconcileModelCacheGeneration },
   { name: "pool-rotation", reconcileGeneration: reconcilePoolRotationState },
   { name: "combo-rotation", reconcileGeneration: reconcileComboRotationState },
-  { name: "combo-session-recall", reconcileGeneration: reconcileComboRecall },
+  {
+    name: "combo-session-recall",
+    sweepExpired: sweepExpiredComboRecall,
+    reconcileGeneration: reconcileComboRecall,
+  },
   { name: "guardian-backoff", reconcileGeneration: reconcileGuardianBackoff },
   { name: "codex-reauth", reconcileGeneration: reconcileCodexReauthState },
   { name: "oauth-reauth", reconcileGeneration: reconcileOAuthReauthState },

package/src/lib/test-home-guard.ts

@@ -20,7 +20,7 @@
  *    how this incident happened.
  */
 import { homedir } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { realpathSync } from "node:fs";
 
 const GUARD_ENV = "OCX_TEST_HOME_GUARD";
@@ -152,3 +152,87 @@ export function assertNotRealCodexHomeUnderTest(dir: string): void {
     + "Point CODEX_HOME at a temp directory for this test before writing native auth.json.",
   );
 }
+
+/**
+ * The trees a removal must never reach, and the reason each one is named.
+ *
+ * The writer guard above cannot help here. `rmSync` is plain `node:fs`: it calls no writer of
+ * ours, so no assertion of ours runs, and by the time anything could observe the damage the
+ * directory is already gone. On 2026-09-15 that is exactly what happened — a test resolved the
+ * process-global config directory and removed it, taking every OAuth login, the Codex account
+ * store, the service tokens and a 372MB usage ledger with it.
+ */
+const PROTECTED_TREES: ReadonlyArray<{ path: string; lexical: string; label: string }> = [
+  { path: PROTECTED_HOME, lexical: resolve(join(REAL_HOME, ".opencodex")), label: "the real OpenCodex home" },
+  { path: PROTECTED_CODEX_HOME, lexical: resolve(join(REAL_HOME, ".codex")), label: "the real Codex home" },
+  {
+    path: PROTECTED_LAUNCH_AGENTS,
+    lexical: resolve(join(REAL_HOME, "Library", "LaunchAgents")),
+    label: "the real LaunchAgents directory",
+  },
+];
+const PROTECTED_REAL_HOME = canonicalize(REAL_HOME);
+const LEXICAL_REAL_HOME = resolve(REAL_HOME);
+
+/** Canonical paths whose removal is refused. Exported so the guard's tests cannot drift off them. */
+export function protectedRemovalTreesForTests(): readonly string[] {
+  return [PROTECTED_REAL_HOME, ...PROTECTED_TREES.map(tree => tree.path)];
+}
+
+/** Whether `child` sits strictly below `parent`, both already canonicalized. */
+function isInside(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/**
+ * Why removing `target` is refused, or `null` when it is not a protected location.
+ *
+ * Three relations are refused, not one. Equality alone would still permit
+ * `rmSync(getConfigPath())` against a live `config.json`, and it would permit
+ * `rmSync(homedir())`, which takes the protected tree with it. So a target is refused when it
+ * IS a protected tree, when it sits INSIDE one, or when it is an ANCESTOR of one.
+ *
+ * Canonicalization is what makes a symlink useless as a bypass: a temp path that merely points
+ * at the real home resolves to the real home before any comparison happens.
+ */
+export function protectedRemovalReason(target: string): string | null {
+  // Both spellings are judged, not just the canonical one. Canonicalization is what defeats a
+  // symlink alias, but it also resolves the target away: if `~/.opencodex` is itself a link,
+  // the literal path a caller passed is the thing that gets unlinked, and only the lexical
+  // form still names it. Upstream Codex makes the same distinction in its writable-root
+  // handling, keeping logical and resolved forms side by side rather than collapsing to one.
+  for (const candidate of [canonicalize(target), resolve(target)]) {
+    if (candidate === PROTECTED_REAL_HOME || candidate === LEXICAL_REAL_HOME) {
+      return `the real home directory (${PROTECTED_REAL_HOME})`;
+    }
+    for (const tree of PROTECTED_TREES) {
+      for (const protectedPath of [tree.path, tree.lexical]) {
+        if (candidate === protectedPath) return `${tree.label} (${protectedPath})`;
+        if (isInside(protectedPath, candidate)) return `a path inside ${tree.label} (${protectedPath})`;
+        if (isInside(candidate, protectedPath)) return `an ancestor of ${tree.label} (${protectedPath})`;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Throw before a removal that would reach a protected tree.
+ *
+ * Deliberately NOT gated on {@link isTestHomeGuardArmed}. Arming happens in `tests/preload.ts`,
+ * which Bun loads from the `bunfig.toml` it finds in the CURRENT WORKING DIRECTORY — so a run
+ * started outside the repository arms nothing, leaves OPENCODEX_HOME unset, and resolves the
+ * developer's real home. That unarmed run is precisely the one that caused the incident, so the
+ * refusal has to hold without it. Nothing in production calls this; the callers are test
+ * helpers, where the only cost of an unconditional check is a path comparison.
+ */
+export function assertRemovalOutsideProtectedTrees(target: string): void {
+  const reason = protectedRemovalReason(target);
+  if (reason === null) return;
+  throw new Error(
+    `refusing to remove ${reason} from a test process: "${target}" resolves there. `
+    + "Create the directory this test owns with createTempHome() from tests/helpers/temp-home "
+    + "and remove that handle instead (see devlog 260730_codex_rs_upstream_v2_live_handoff/070).",
+  );
+}

package/src/lib/upstream-retry.ts

@@ -2,10 +2,10 @@
  * Retry guard for upstream fetches that die on stale pooled keep-alive sockets.
  *
  * chatgpt.com (Cloudflare) closes idle keep-alive connections server-side; Bun's fetch pool
- * reuses the half-closed socket and the request write fails with ECONNRESET before any
- * response bytes arrive. Retrying on a fresh connection is safe for our replayable
- * (string-body) upstream requests, because fetch() rejects only before response headers —
- * a caught error here means no response was ever received.
+ * reuses the half-closed socket and a request can fail before response headers arrive.
+ * A pre-header rejection does not prove that the origin did not process the request.
+ * Mechanically reusable bytes do not make a model POST idempotent: an ambiguous reset
+ * becomes a terminal, non-replayable response unless the operation is explicitly safe.
  *
  * Deliberately narrow: timeouts, aborts, ECONNREFUSED/DNS/TLS failures, and HTTP error
  * statuses (returned as Response, never thrown) are NOT retried. Mid-stream SSE resets are
@@ -36,19 +36,66 @@ export function isNonReplayableResponse(response: Response): boolean {
   return nonReplayableResponses.has(response);
 }
 
+/**
+ * The narrower marker: responses this proxy synthesized as a replay refusal.
+ *
+ * {@link isNonReplayableResponse} answers "must not be sent again", which the WebSocket
+ * post-send verdicts share. This one answers "the upstream never said this", and that is the
+ * question a quota recorder or a `Retry-After` synthesizer has to ask. Both were written for
+ * a status that only ever arrived from a provider, so a synthetic 429 reads to them as a
+ * credential that rate-limited us and as a wait worth honouring -- one writes a cooldown
+ * against a credential that refused nothing, the other instructs the client to send the turn
+ * again. A marker rather than a body check, because it has to be answerable before the body
+ * is read and cannot be spoofed by an upstream that happens to echo the code.
+ */
+const replayRefusalResponses = new WeakSet<Response>();
+
+export function markReplayRefusalResponse(response: Response): void {
+  replayRefusalResponses.add(response);
+}
+
+export function isReplayRefusalResponse(response: Response): boolean {
+  return replayRefusalResponses.has(response);
+}
+
 /** Origin never produced a response event; the turn may still be executing. */
 export const UPSTREAM_NO_RESPONSE_CODE = "upstream_no_response";
 /** Transport closed after the send, before any response event. */
 export const UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE = "upstream_closed_before_response";
+/**
+ * This proxy refused to replay a pre-header fetch rejection.
+ *
+ * Distinct from {@link UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE}, which the Codex WebSocket
+ * transport settles as a 502 after the create frame was already sent. Both are ambiguous,
+ * but only this one is a refusal this process made before any response existed, so it
+ * follows the send-budget precedent and answers 429: the Codex client is configured with
+ * `retry_429: false` and `retry_5xx: true` over four attempts, so a 5xx here multiplies
+ * the duplicate send the refusal exists to prevent. See
+ * structure/transports/responses.md#ambiguous-connection-reset-replay-boundary.
+ */
+export const UPSTREAM_RESET_REPLAY_REFUSED_CODE = "upstream_reset_replay_refused";
 const NON_REPLAYABLE_UPSTREAM_CODES: ReadonlySet<string> = new Set([
   UPSTREAM_NO_RESPONSE_CODE,
   UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE,
+  UPSTREAM_RESET_REPLAY_REFUSED_CODE,
 ]);
 
 export function isNonReplayableUpstreamCode(code: unknown): boolean {
   return typeof code === "string" && NON_REPLAYABLE_UPSTREAM_CODES.has(code);
 }
 
+/**
+ * True for the one non-replayable code this proxy owns end to end. The status it carries is
+ * a local decision, so a re-wrapping formatter must restate it rather than inherit the
+ * caller's upstream-shaped status.
+ */
+export function isReplayRefusalCode(code: unknown): boolean {
+  return code === UPSTREAM_RESET_REPLAY_REFUSED_CODE;
+}
+
+/** Client-facing status for {@link UPSTREAM_RESET_REPLAY_REFUSED_CODE}. */
+export const REPLAY_REFUSED_STATUS = 429;
+
 // 1 initial + 2 retries: the pool may hold more than one stale socket.
 const RESET_RETRY_MAX_ATTEMPTS = 3;
 const RESET_RETRY_BASE_DELAY_MS = 150;
@@ -352,6 +399,12 @@ export async function fetchWithAttemptDeadline(
 }
 
 export interface ResetRetryOptions {
+  /**
+   * Opt in only when repeating this operation cannot duplicate upstream effects.
+   * This permits reset retries, not extra sends: attempts and onSendsConsumed still
+   * bound and count every physical send. A string body is not replay-safety proof.
+   */
+  replaySafe?: boolean;
   abortSignal?: AbortSignal;
   /** Short host/path label for the retry warn log (no secrets/query strings). */
   label?: string;
@@ -442,9 +495,9 @@ export function applyUpstreamRecoveryInit<T extends RequestInit>(
 }
 
 /**
- * Run `doFetch`, retrying only connection-reset-shaped rejections (see
- * isConnectionResetError) with jittered backoff. The caller's thunk must be replay-safe
- * (string body); every retry is logged so persistent resets stay visible.
+ * Run `doFetch` within one send budget. Connection-reset-shaped rejections are
+ * terminal by default; only an explicitly replay-safe operation receives reset retries
+ * with jittered backoff. HTTP responses retain the caller's existing retry policy.
  */
 export async function fetchWithResetRetry(
   doFetch: ReplayableFetch,
@@ -475,6 +528,20 @@ export async function fetchWithResetRetry(
         if (sawReset) throw new UpstreamRetryEvidenceError([], err, true);
         throw err;
       }
+      if (opts.replaySafe !== true) {
+        // Return evidence instead of throwing a generic transport error: outer catches
+        // otherwise turn it into a replayable 502 and a combo/account recovery resends it.
+        // The WeakSet protects in-process recovery; the code survives JSON re-wrapping.
+        // Never expose the raw exception, which can contain credentials or request data.
+        const response = new Response(JSON.stringify({ error: {
+          type: "upstream_error",
+          code: UPSTREAM_RESET_REPLAY_REFUSED_CODE,
+          message: "The upstream connection closed before a response was received. The request may already have been processed; automatic replay was stopped.",
+        } }), { status: REPLAY_REFUSED_STATUS, headers: { "content-type": "application/json" } });
+        markResponseNonReplayable(response);
+        markReplayRefusalResponse(response);
+        return response;
+      }
       if (attempt === attempts - 1) throw err;
       sawReset = true;
       lastError = err;
@@ -491,9 +558,9 @@ export async function fetchWithResetRetry(
 }
 
 /**
- * fetchWithResetRetry plus a transient-5xx status retry layer, PRE-STREAM only: a
- * returned Response has by definition not been relayed to the client yet, so replaying
- * the (string-body) request is safe. The failed attempt's body is cancelled before the
+ * fetchWithResetRetry plus the caller-selected transient-5xx policy, PRE-STREAM only.
+ * A received HTTP error follows that policy; an ambiguous reset's non-replayable
+ * verdict always stops it. The failed attempt's body is cancelled before the
  * retry; every returned response (ok, non-transient, aborted, slow, exhausted) keeps
  * its body intact. Honors Retry-After via retryBackoffDelayMs.
  *