UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,972 lines • 104 kB
import { advisorPlanRootConfig } from "./advisor-plan-slot";
import { admitsHostedAdvisor, scopedAnthropicServerTools } from "../messages-native-scope";
import { selectResponseReplayOwner } from "./replay-owner";
import { isPlaintextV2AgentMessagesEnabled } from "../../config/multi-agent-surface";
import { comboLogLabel, comboTargetLogLabel } from "../../combos/resolve";
import { clientFacingModelLabel, clientFacingModelText } from "../../lib/error-destination";
import { carryLocalFailureState, projectLocalModelRefusalLog, upstreamErrorIsLocal } from "../request-log-failure-detail";
import { carryProxyErrorContext, hasProxyErrorMessage, isPausedTurn, markProxyError, rememberPausedTurn } from "../../lib/client-error-body";
import { isXaiPrivacyModeRefusal } from "../../providers/xai-privacy-mode";
import { classifyUpstreamCondition } from "../../lib/upstream-condition";
import { effectiveAzureOutputBudget } from "../../adapters/azure";
import { resolveOutputCeiling } from "./input-admission";
import { buildResponsesTransport } from "../../adapters/openai-responses/transport";
import { isMetaAiResponsesDestination } from "../../responses/muse-tool-name-alias";
import { chatCanPreserveMandatoryToolChoice, hasMandatoryToolChoice } from "./combo-required-tool-contract";
import { isComboVisionDescriptionRefusal, isPolicyCandidateRefusal, isMandatoryToolChoiceRefusal } from "./policy-request-scope";
import { isCodexAccountCooldownResponse } from "../../codex/account-cooldown-response";
import { resolveWireProtocolOverride } from "../adapter-resolve";
import { parseSyntheticRowId } from "../fast-row";
import { resolveOpenAiVirtualModel } from "../../providers/openai-virtual-models";
import { comboCooldownRetryAfterSeconds, isDefiniteContextOverflow, type CodexAccountModelRefusal } from "../../combos/failover";
import { fallbackTriggerForStatus, guardFallbackHop } from "../../routing/fallback-policy";
import {
  isCodexReasoningEffort,
  isDeclaredReasoningEffort,
  resolveEffortAtOrBelow,
} from "../../reasoning-effort";
import { admissionMayUseMeteredComboTargets, admissionModelDeniedResponse, AdmissionModelDeniedError, intersectAdmissionModelScopes, projectAdmissionModelDeniedLog, resolveAdmissionModelScope, routeAllowedByScope } from "../admission-model-scope";
import { recordAttemptRequestedEffort } from "../request-log";
import { bindLinkTurnChild, failLinkTurnExpansion, markLinkTurnMissing, observeLinkTurnExpansion } from "../link-turn";
import {
  CODEX_TEXT_GUARDED_BUDGET_POLICY,
  deriveRequestExecutionBudget,
  isRequestExecutionBudget,
} from "../../lib/request-execution-budget";
import type {
  RequestExecutionBudgetPolicy,
  RequestExecutionBudget,
} from "../../lib/request-execution-budget";
import type { OcxComboDefaultEffort, OcxConfig, OcxUsage } from "../../types";
import type { RequestLogContext } from "../request-log";
import type { HandleResponsesOptions, ResponsesDispatchers, ConsumedComboFailure } from "./core-options";
import type { TranslatorBudget } from "../../lib/translator-budget";
import {
  getCombo,
  comboRequestHasImageInput,
  pickComboTarget,
  pickComboTargetWithWait,
  targetKey,
  concreteComboRequestBody,
  isComboTargetInCooldown,
  snapshotComboQuotaCooldowns,
  comboExclusion,
  comboUnavailableDiagnostics,
  comboTargetUnavailableCause,
  comboTargetSkipTrigger,
  noteComboSuccess,
  settleComboReprobeSuccess,
  comboFailureDecision,
  advanceComboAfterFailure,
  comboFailureCooldownScope,
  JEV_PROVIDER_ID,
  jevDecisionBackendFor,
  resolveJevComboDecision,
  type ComboPick,
  type JevCandidate,
  type JevDecision,
} from "../../combos";
import { formatErrorResponse } from "../../bridge";
import { SEND_BUDGET_EXHAUSTED_CODE } from "../../lib/errors";
import {
  expandPreviousResponseInput,
  previousResponseRestoredPrefixLength,
  previousResponseReplayFailure,
  previousResponseProviderState,
} from "../../responses/state";
import { hasUnreadableEncryptedAgentTask } from "./encrypted-payload";
import { eagerCodexToolCatalogSurface, warnEagerCodexToolCatalog } from "./codex-tool-catalog";
import { clampComboCallerEffort, comboCapabilityGate } from "../../combos/request-capability";
import { comboAdvertisesEffortUnion } from "../../combos/capability-policy";
import { requestStartComboConfig, snapshotComboAdmission, snapshotComboAdmissionProvider } from "./combo-admission-snapshot";
import { canDescribeComboImages } from "./request-sidecar-auth";
import { captureRouteStaticPolicy, routeConcreteModel, comboRouteDecisionTrace } from "../../router";
import { memoryModelRouteReason } from "./memory-models";
import { baseProviderLabel, poolAccountProviderLabel } from "../../providers/label";
import { getAccountSet } from "../../oauth/store";
import { anthropicRefusalCredentialIsCurrent } from "../../oauth/anthropic-account-refusal";
import { configuredAnthropicInstance } from "../../providers/anthropic-instance";
import { isAnthropicBillingFailure } from "../../providers/anthropic-billing-refusal";
import {
  anthropicRoutingFor,
  formatAnthropicProviderForLog,
} from "../../oauth/anthropic-routing";
import { codexAccountLogLabel, oauthAccountLogLabel } from "../../codex/account-label";
import { isGenericFailoverProvider, rotateGenericOAuthAccountOn429 } from "../../oauth/generic-account-failover";
import { codexQuotaScopeForModel, getCodexQuotaHealthSnapshot } from "../../codex/routing";
import { MAIN_CODEX_ACCOUNT_ID } from "../../codex/account-id";
import { providerCodexAccountMode } from "../../providers/registry";
import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
import type { AgentTaskRecoveryFailureReason } from "./agent-task-recovery";
import {
  agentTaskRecoveryConfig,
  discardEncryptedAgentTaskRecovery,
  recoverEncryptedAgentTaskWithResult,
} from "./agent-task-recovery";
import { isThreadSpawnRequest, supportedLadderFor } from "../effort-policy";
import { jevChoiceEfforts } from "./jev-combo-choice";
import { applyDroidResponsesReasoningDefault } from "../droid-reasoning-default";
import { isPlainObject } from "../../lib/plain-data";
import {
  clientCancelledResponse,
  comboUnavailable,
  comboUnavailableResponse,
  targetIncompatibleResponse,
  unreadableEncryptedAgentTaskResponse,
} from "./core-errors";
import {
  buildComboChildHeaders,
  createChildPassthroughCallbackGate,
  consumeComboFailure,
  isLateAttributionRefusal,
} from "./core-combo-failure";
import {
  linkRequestSessionLane,
  reasoningReplayConversationIdFromResponsesRequest,
  sessionIdHeaderFromRequest,
  sessionLaneIdFromRequest,
} from "../request-log-conversation";
import type { CodexAuthContext } from "../../codex/auth-context";
import type { ResponsesTerminalStatus } from "../../bridge";
import { beginRequestAttempt, sealRequestAttemptIdentity, finishRequestAttempt } from "../request-log";
import { sealedCredentialRefusals } from "../request-log-attempt-recovery";
import { recallComboTurnEffortForLane, rememberComboForLane, type ComboTurnEffort } from "./combo-session-recall";
import { COMBO_TOOL_LOOP_PIN_REASON, toolLoopPinnedPick } from "./combo-tool-loop-pin";
import { JEV_SESSION_PIN_ROUTE_REASON, jevSessionPinScope } from "./jev-session-pin";
import { runTurnAdapterSseResponses } from "./core-lifetime";
import { normalizePersistedJevDecision } from "../../usage/jev-stats";
import {
  isNativePassthroughSseResponse,
  isEagerRelaySseResponse,
  markNativePassthroughSseResponse,
  markEagerRelaySseResponse,
} from "../relay";
import { preflightComboStreamResponse } from "./combo-stream-preflight";
import { requiredToolContractOf } from "./combo-required-tool-contract";
import {
  streamingContextOverflowResponse,
  jsonContextOverflowResponse,
  lateAttributionLimitResponse,
  jsonIncompleteResponse,
  streamingIncompleteResponse,
} from "./context-overflow";
import { mandatoryResponsesReasoningReplayUnavailable } from "./core-replay";
import { isReplayRefusalResponse, settleOperatorReplacement, UPSTREAM_RESET_REPLAY_REFUSED_CODE } from "../../lib/upstream-retry";
import { attributeFinalRequest } from "../request-log-failure-attribution";
import { createComboProtocolLanes, dispatchNativeComboChild } from "./core-combo-native";
import { createJevModelInvoker } from "./jev-model-invoke";
import { comboRequestedEffortLabel } from "./combo-requested-effort";
import { clientWireOf } from "../inference/client-wire";
import { resolveContextPrincipal } from "../auth-cors";

/**
 * Sends one combo target may run on its own before the ladder moves on. A target is a whole
 * request as far as its own provider is concerned, so this is the guarded profile's base
 * allowance rather than a separate number to keep in sync.
 */
export const COMBO_TARGET_BASE_SENDS = CODEX_TEXT_GUARDED_BUDGET_POLICY.baseSendAllowance;

/**
 * OCX-11: where a combo target physically dispatches, after provider aliases and
 * blockedModelRedirects. A target that does not resolve keeps its configured selector; its
 * dispatch fails on its own.
 */
function resolvedComboDestination(config: OcxConfig, target: { provider: string; model: string }): { provider: string; model: string } {
  try {
    const route = routeConcreteModel(config, `${target.provider}/${target.model}`);
    return { provider: route.providerName, model: route.modelId };
  } catch {
    return { provider: target.provider, model: target.model };
  }
}

export function cooledPoolAccountLabel(config: OcxConfig, providerName: string, modelId: string, label: string | undefined): string | undefined {
  if (!label) return undefined;
  const instance = configuredAnthropicInstance(config, providerName);
  if (instance && config.providers[providerName]?.authMode === "oauth") {
    const matches = getAccountSet(instance)?.accounts.filter(account =>
      formatAnthropicProviderForLog(instance, account.id) === label) ?? [];
    return matches.length === 1 && anthropicRoutingFor(instance).getAnthropicAccountHealthSnapshot(matches[0]!.id) ? label : undefined;
  }
  const provider = config.providers[providerName];
  if (!provider || !isCanonicalOpenAiForwardProvider(provider)) return undefined;
  const quotaScope = codexQuotaScopeForModel(modelId);
  // The main account logs as `<provider>-main` and is not a `codexAccounts` entry (#8880). In pool
  // mode the pool rotates past a cooled main itself, so its 429 is account evidence exactly like a
  // pool account's, and parking the target would black out the siblings and main's own recovery for
  // the upstream Retry-After (up to 24h). Direct mode serves main without that check, so there the
  // target cooldown stays the only guard against re-sending to a spent account.
  if (label === `${providerName}-main`) {
    return providerCodexAccountMode(providerName, provider) === "pool"
      && getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope) ? label : undefined;
  }
  const matches = (config.codexAccounts ?? []).filter(account =>
    `${providerName}-${codexAccountLogLabel(account)}` === label);
  return matches.length === 1
    && getCodexQuotaHealthSnapshot(matches[0]!.id, quotaScope)
    ? label : undefined;
}

/**
 * The generic OAuth pool's counterpart of `cooledPoolAccountLabel`. Its 429 names one account
 * through `accountLogLabel`, but the per-request account budget can end the pool's own rotation
 * before the last refused account is recorded. Hand that account to the pool's rotator, which
 * cools it under the pool's own Retry-After policy, and spare the target only when the pool still
 * has an eligible sibling. The rotator only peeks round-robin here: nothing is sent to that sibling.
 * A lone account or an all-cooled pool returns null and cools the target.
 */
function cooledGenericOAuthAccountLabel(
  config: OcxConfig, providerName: string, modelId: string, label: string | undefined, retryAfter: string | undefined,
): string | undefined {
  const provider = config.providers[providerName];
  if (!label || !provider || !isGenericFailoverProvider(providerName, provider)) return undefined;
  const base = baseProviderLabel(providerName);
  const matches = getAccountSet(providerName)?.accounts.filter(account =>
    oauthAccountLogLabel(account.id, base) === label) ?? [];
  return matches.length === 1
    && rotateGenericOAuthAccountOn429(config, providerName, matches[0]!.id, retryAfter, Date.now(), modelId, false)
    ? label : undefined;
}

/**
 * A 402 credit-balance refusal names one Anthropic OAuth account -- the evidence the pool already
 * accepts on a 403 -- but the pool rotates only on 401/403/429, so the 402 reaches the combo with
 * that account still selectable. Cool it under the pool's entitlement backoff and spare the target
 * only while a sibling is eligible; a lone account or an exhausted pool still cools the target.
 */
function creditRefusedAnthropicAccountLabel(
  config: OcxConfig, providerName: string, modelId: string, label: string | undefined,
  message: string, code: string | null | undefined, response: Response,
): string | undefined {
  const instance = configuredAnthropicInstance(config, providerName);
  if (!label || !instance || config.providers[providerName]?.authMode !== "oauth"
    || !isAnthropicBillingFailure(402, message, code)) return undefined;
  const routing = anthropicRoutingFor(instance);
  const matches = getAccountSet(instance)?.accounts.filter(account =>
    formatAnthropicProviderForLog(instance, account.id) === label) ?? [];
  return matches.length === 1
    && anthropicRefusalCredentialIsCurrent(response, instance, matches[0]!.id)
    && routing.recordAnthropicAccountRefusal(config, matches[0]!.id, 403, null)
    && routing.getEligibleAnthropicAccounts(Date.now(), modelId).length > 0
    ? label : undefined;
}

/**
 * True only for the Anthropic OAuth pool's OWN "all accounts cooled" 429. Its Retry-After is the
 * earliest per-account cooldown restated (`getAnthropicPoolRetryAfterSeconds`), which the pool
 * keeps enforcing locally, so it must not also park the combo target: an account added, resumed or
 * cleared a minute later would otherwise sit ignored until the target expired, up to the 24h
 * server-delay ceiling.
 *
 * Provenance, not just current state: the target must be the OAuth pool, no account may have been
 * identified for the failure, and the pool must be holding the wait right now. An upstream 429 on
 * a pool account always cools and names that account, and an API-key provider never qualifies, so
 * a genuine upstream Retry-After still parks the target in full.
 */
export function isAnthropicPoolLocalRefusal(
  config: OcxConfig,
  providerName: string,
  status: number,
  failedAccount: string | undefined,
  now = Date.now(),
): boolean {
  const instance = configuredAnthropicInstance(config, providerName);
  return instance !== undefined
    && config.providers[providerName]?.authMode === "oauth"
    && status === 429
    && failedAccount === undefined
    && anthropicRoutingFor(instance).getEligibleAnthropicAccounts(now).length === 0
    && anthropicRoutingFor(instance).getAnthropicPoolRetryAfterSeconds(now) !== null;
}

/**
 * A combo's execution policy is DECLARED by the combo, not inherited from the single-target
 * profile.
 *
 * `maxTargetTransitions: 1` and `maxAlternateTargetSends: 1` describe an account move, and
 * applying them to a combo would refuse the second hop of a three-target combo -- which is why
 * combo was left off `reserveDispatch` when the per-request split landed. The transitions a
 * combo may make are exactly the targets it declares minus the one it starts on. What stays
 * capped is the TOTAL: the first target's full ladder, one send for every further declared
 * target, and the one shared final-recovery reserve. A one-target combo reduces to the guarded
 * profile exactly, and a three-target combo whose every target fails hard reaches upstream six
 * times instead of the twelve #4546 measured.
 */
export function comboExecutionBudgetPolicy(declaredTargets: number): RequestExecutionBudgetPolicy {
  const targets = Math.max(1, Math.trunc(declaredTargets));
  const hops = targets - 1;
  const reserve = CODEX_TEXT_GUARDED_BUDGET_POLICY.finalRecoveryAllowance;
  const total = COMBO_TARGET_BASE_SENDS + hops + reserve;
  return {
    maxTotalModelSends: total,
    baseSendAllowance: total - reserve,
    finalRecoveryAllowance: reserve,
    maxAlternateTargetSends: Math.max(1, hops),
    maxTargetTransitions: Math.max(1, hops),
  };
}


/**
 * A budget scope that keeps its own recovery ledgers but spends the SAME request-wide counter.
 *
 * The sharing has to happen inside the factory. Redefining `used` as an accessor onto the parent
 * only shared what callers read from the outside: `remainingBaseSends`, the total check and the
 * reserve test all consult the factory's own private counter, which an overridden property
 * cannot reach. Each derived scope therefore admitted dispatches as though the request had spent
 * nothing, and the per-target holdback below -- expressed against `maxTotalModelSends` -- had
 * nothing to hold back from.
 *
 * `deriveRequestExecutionBudget` binds the scope to the parent's real ledger, including pending
 * externally-counted bookings and the durable-spend observer, all of which must travel together.
 * A pending booking is a send already counted in the total and waiting for its reporter, and the
 * observer books by watching that same counter move (#4707) -- so a scope that spent the counter
 * without carrying the observer would move it without booking, and this combo's child sends
 * would go missing from the spend ledger. The reserve, alternate-target and transition ledgers
 * stay per-scope on purpose: a combo target's account failover is its own recovery decision,
 * while the request total still bounds every target together.
 */
export function deriveSendBudgetScope(
  parent: RequestExecutionBudget,
  policy: RequestExecutionBudgetPolicy,
): RequestExecutionBudget {
  return deriveRequestExecutionBudget(parent, policy);
}


/**
 * The ladder one combo target may run, expressed as an allowance on the request-wide counter.
 *
 * `used + COMBO_TARGET_BASE_SENDS` gives this target its own ladder from wherever the request
 * already stands, and the clamp holds back one send for each target still declared after it: a
 * first target that 5xx-streaks must not eat the send the last declared target is entitled to.
 * That guarantee is the difference between a per-target policy and a shared pool the first
 * target drains.
 */
export function comboTargetSendBudget(
  comboScope: RequestExecutionBudget,
  targetsDeclaredAfterThisOne: number,
): RequestExecutionBudget {
  const policy = comboScope.policy;
  const heldForLaterTargets = Math.max(0, targetsDeclaredAfterThisOne);
  const ceiling = Math.max(1, policy.maxTotalModelSends - heldForLaterTargets);
  return deriveSendBudgetScope(comboScope, {
    maxTotalModelSends: policy.maxTotalModelSends,
    baseSendAllowance: Math.min(ceiling, comboScope.used + COMBO_TARGET_BASE_SENDS),
    finalRecoveryAllowance: policy.finalRecoveryAllowance,
    // Within one target the account-move shape is unchanged: three same-account sends plus one
    // alternate is the recovery live traffic depends on, and a combo does not widen it.
    maxAlternateTargetSends: CODEX_TEXT_GUARDED_BUDGET_POLICY.maxAlternateTargetSends,
    maxTargetTransitions: CODEX_TEXT_GUARDED_BUDGET_POLICY.maxTargetTransitions,
  });
}

interface JevComboChoice {
  pick: ComboPick;
  candidate: JevCandidate;
}

/** Enumerate this request's eligible targets without reserving another recovery pass. */
function eligibleJevComboChoices(
  config: OcxConfig,
  comboId: string,
  eligible: (target: NonNullable<ReturnType<typeof getCombo>>["targets"][number]) => boolean,
  now: number,
  cooldownReprobeTargets?: ComboPick["cooldownReprobeTargets"],
): JevComboChoice[] {
  const combo = getCombo(config, comboId);
  if (!combo) return [];
  const excluded = new Set<string>();
  const choices: JevComboChoice[] = [];
  const reserved = cooldownReprobeTargets ? Object.entries(cooldownReprobeTargets) : undefined;
  while (excluded.size < combo.targets.length) {
    const pick = pickComboTarget(config, comboId, {
      exclude: excluded, eligible, now, allowCooldownReprobe: false, cooldownReprobeTargets: reserved,
    });
    if (!pick) break;
    const key = targetKey(pick.target);
    excluded.add(key);
    // The TypeSafe row owns a decision credential, not an inference transport.
    if (pick.target.provider === JEV_PROVIDER_ID) continue;
    const identity = jevChoiceEfforts(config, pick.target, combo.decisionQuotaSignals === true);
    if (!identity) continue;
    choices.push({
      pick: { ...pick, attempted: [key] },
      candidate: {
        key,
        provider: pick.target.provider,
        model: pick.target.model,
        ...identity,
        modelProfile: pick.target.modelProfile,
      },
    });
  }
  // #5691: the synchronous pick above does not defer emergency-only targets, so apply the
  // same rule here — withhold them from JEV while any normal target is offered, never when
  // they are all that remains.
  if (combo.cooldownWaitPolicy === "before-last-resort" && choices.some(choice => !choice.pick.target.lastResort)) {
    return choices.filter(choice => !choice.pick.target.lastResort);
  }
  return choices;
}


/** Dispatch a Responses combo within its shared send budget and preserve terminal child failures. */
export async function executeComboResponses(
  req: Request,
  rawBody: unknown,
  comboId: string,
  config: OcxConfig,
  logCtx: RequestLogContext,
  options: HandleResponsesOptions & { translatorBudget: TranslatorBudget },
  requestDispatchers: ResponsesDispatchers,
): Promise<Response> {
  const clientModelLabel = options.clientModelLabel ?? clientFacingModelLabel(undefined);
  const responseModel = clientFacingModelText(clientModelLabel);
  const requestedModel = options.mainHardLockFallbackOverride?.sourceModel
    ?? (typeof (rawBody as { model?: unknown } | null)?.model === "string"
      ? (rawBody as { model: string }).model
      : `combo/${comboId}`);
  if (requestedModel !== responseModel) options = { ...options, clientResponseModelLabel: clientModelLabel };
  Object.assign(logCtx, {
    requestedModel: responseModel,
    model: responseModel,
    provider: "combo",
    comboId,
  });
  const combo = getCombo(config, comboId);
  if (!combo) {
    return formatErrorResponse(404, "invalid_request_error", "Unknown combo");
  }
  // Admission reads one detached copy of the request-start config. Mid-request edits to
  // capabilities, sidecars, protocols or the roster apply to the next request. Only spend
  // authority is read live, from the root config that management writes replace.
  const admissionSnapshot = snapshotComboAdmission(config, comboId);
  // Every image probe and the child it admits plan with these request-start sidecar settings.
  const comboVisionSidecar = { settings: admissionSnapshot.vision };
  const liveConfig = advisorPlanRootConfig(config);
  // Resolve against the original request once; every bridge candidate receives the same trusted
  // result after its provisional Authorization is removed, including an explicitly keyless result.
  const replayPrincipal = options.replayPrincipal
    ?? { clientPrincipalId: resolveContextPrincipal(req, config, options.admission) };
  // The caller's model scope, resolved once from the request options. A capability-authenticated
  // internal request carries the caller's captured scope on options.admissionScope even though
  // its own admission is the host's broad key; recomputing from options.admission would lose it.
  const admissionScope = options.admissionScope ?? resolveAdmissionModelScope(config, options.admission);
  // Every paid send also needs the key's current scope: a narrowed key never widens back.
  const currentAdmissionScope = () => intersectAdmissionModelScopes(admissionScope,
    resolveAdmissionModelScope(liveConfig, options.admission));
  // Present only when an opted-in ingress supplied a native source; otherwise every child
  // takes the bridge below exactly as before.
  const protocolLanes = createComboProtocolLanes({
    source: options.protocolSource,
    req,
    config,
    logCtx,
    admissionScope,
    droidDefaultEffort: options.droidDefaultEffort,
    comboId,
    targets: combo.targets,
  });
  // The ladder's own scope, derived from what this combo DECLARES. It shares the request-wide
  // counter with the holder that arrived on options -- a combo child already inherited that
  // counter, but nothing read it as a limit across targets -- while its transition and
  // alternate-target ledgers come from the target list rather than from the single-target
  // account-move profile (#4546).
  const comboSendScope = isRequestExecutionBudget(options.sendBudget)
    ? deriveSendBudgetScope(options.sendBudget, comboExecutionBudgetPolicy(combo.targets.length))
    : undefined;
  // Expand previous_response_id before image policy and child dispatch so a
  // continuation that only references prior images still fails closed when
  // imageInput is disabled (and so targets see the full replayed input).
  const inboundClientThreadId = req.headers.get("x-codex-parent-thread-id")?.trim() || undefined;
  const inboundOwnThreadId = req.headers.get("thread-id")?.trim() || undefined;
  const strictReplay = options.plaintextV2Decision ?? isPlaintextV2AgentMessagesEnabled(config);
  const { replayOwnerKey, replayConnectionScope } = selectResponseReplayOwner(strictReplay, replayPrincipal.clientPrincipalId, inboundOwnThreadId, options);
  const body = expandPreviousResponseInput(rawBody, strictReplay ? inboundOwnThreadId : inboundClientThreadId, replayOwnerKey);
  const replayFailure = previousResponseReplayFailure(body);
  if (replayFailure?.reason === "scope_mismatch") {
    console.warn("[opencodex] refusing continuation because the client task scope does not match replay state");
  }
  // Local replay failures require full client replay.
  if (replayFailure) {
    failLinkTurnExpansion(options.linkTurn, req, logCtx, body, replayFailure.reason);
    return formatErrorResponse(
      400,
      "previous_response_not_found",
      "Continuation state is unavailable or corrupt; resend the full conversation without previous_response_id.",
    );
  }
  // Missing state returns the original body without a failure marker. Reject
  // that unresolved continuation for image-disabled combos so a target cannot
  // resolve prior images out of band. A successful expansion yields a new
  // object (still carrying previous_response_id) and must not be treated as
  // unresolved — text-only stored continuations remain allowed.
  const requestedPreviousId = typeof (rawBody as { previous_response_id?: unknown } | null)?.previous_response_id === "string"
    ? (rawBody as { previous_response_id: string }).previous_response_id
    : "";
  const unresolvedPrevious = requestedPreviousId.trim().length > 0 && body === rawBody;
  // Remote Link (design T4 5 and 9.1): the combo's own expansion is the request's one capture point; its
  // children replay a snapshot and skip theirs.
  observeLinkTurnExpansion(options.linkTurn, req, logCtx, body,
    requestedPreviousId.trim().length > 0 ? (unresolvedPrevious ? "unexpanded" : "chained") : "none");
  // Live metered consent, checked before every paid send.
  const maySpendOnTarget = (target: (typeof combo.targets)[number]): boolean =>
    !target.metered || admissionMayUseMeteredComboTargets(liveConfig, options.admission, liveConfig.combos?.[comboId]);
  const mayUseTarget = (target: (typeof combo.targets)[number]): boolean =>
    maySpendOnTarget(target) && (combo.strategy !== "jev" || target.provider !== JEV_PROVIDER_ID);
  // The combo ladder owns the whole logical request, so the catalog diagnostic is counted here for
  // combo-routed turns; children run as concrete selections and would otherwise never report it.
  // Counting after the replay expansion keeps restored history out of the tally.
  if ((options.inboundWire ?? "responses") === "responses") {
    warnEagerCodexToolCatalog(body, req.headers, {
      surface: eagerCodexToolCatalogSurface(body, options.compactionRecoveryKind),
      replayPrefixLength: previousResponseRestoredPrefixLength(body),
      logicalRequest: logCtx,
    });
  }
  const comboReplaySnapshot = {
    sourceBody: body,
    previousResponseInputExpanded: body !== rawBody
      && typeof (body as { previous_response_id?: unknown }).previous_response_id === "string",
    providerContinuation: body !== rawBody && requestedPreviousId
      ? previousResponseProviderState(requestedPreviousId)
      : undefined,
    recoveredPlaintext: false,
  };
  const reasoningReplayConversationId = reasoningReplayConversationIdFromResponsesRequest({
    clientThreadId: inboundClientThreadId,
    threadIdHeader: req.headers.get("thread-id"),
    sessionIdHeader: sessionIdHeaderFromRequest(req.headers),
  });
  const reasoningReplayEligible = (target: (typeof combo.targets)[number]): boolean => {
    try {
      const route = routeConcreteModel(config, `${target.provider}/${target.model}`);
      const unavailable = mandatoryResponsesReasoningReplayUnavailable({
        body,
        clientThreadId: reasoningReplayConversationId,
        clientPrincipalId: replayPrincipal.clientPrincipalId,
        providerName: route.providerName,
        provider: route.provider,
        adapterName: route.provider.adapter,
        modelId: route.modelId,
      });
      return !unavailable;
    } catch {
      // Routing failures are not evidence of replay incompatibility. Keep the target eligible so
      // the existing selection and dispatch path preserves its original routing failure surface.
      return true;
    }
  };
  const adoptFailedChildLog = (childLog: RequestLogContext): void => {
    // Attempts remain the complete physical history; the logical row mirrors the failed
    // target whose response is returned, including an earlier quota refusal on exhaustion.
    // The ingress finalizer cannot stamp this child once activeAttempt is cleared below.
    if (childLog.activeAttempt) {
      attributeFinalRequest({
        status: childLog.activeAttempt.status,
        terminalSource: childLog.terminalSource,
        transportPhase: childLog.transportPhase,
        causeHint: childLog.causeHint,
        outputObserved: childLog.firstOutputMs !== undefined,
        locallyAnswered: childLog.localTerminalReason !== undefined,
        attempt: childLog.activeAttempt,
      });
    }
    carryProxyErrorContext(childLog, logCtx);
    Object.assign(logCtx, childLog, {
      client: logCtx.client,
      requestedModel: responseModel,
      model: responseModel,
      provider: "combo",
      comboId,
      routeDecision: logCtx.routeDecision,
      attempts: logCtx.attempts,
      activeAttempt: undefined,
      activeAttemptStartedAt: undefined,
    });
    carryLocalFailureState(childLog, logCtx);
    if (requestedModel !== responseModel) {
      projectLocalModelRefusalLog(logCtx, clientModelLabel);
      logCtx.model = responseModel; logCtx.requestedModel = responseModel;
      if (options.clientModelLabel) logCtx.jevDecision = undefined;
    }
  };

  const unreadableEncryptedAgentTask = hasUnreadableEncryptedAgentTask(
    (body as { input?: unknown } | undefined)?.input,
  );
  const canDecryptUnreadableAgentTask = (target: (typeof combo.targets)[number]): boolean => {
    const provider = config.providers[target.provider];
    if (!provider || provider.disabled === true) return false;
    try {
      const route = routeConcreteModel(config, `${target.provider}/${target.model}`);
      return isCanonicalOpenAiForwardProvider(route.provider);
    } catch {
      return false;
    }
  };
  let comboPayloadReadable = false;
  const payloadEligible = (target: (typeof combo.targets)[number]): boolean =>
    comboPayloadReadable || !unreadableEncryptedAgentTask || canDecryptUnreadableAgentTask(target);
  const museToolEligible = (target: (typeof combo.targets)[number]): boolean => {
    if (!hasMandatoryToolChoice(body)) return true;
    try {
      const selector = `${target.provider}/${target.model}`, { fastRow, effortRow } = parseSyntheticRowId(selector, config);
      const route = routeConcreteModel(config, fastRow?.baseId ?? effortRow?.baseId ?? selector);
      const modelId = resolveOpenAiVirtualModel(route.providerName, route.modelId)?.wireModelId ?? route.modelId;
      const inboundWire = options.inboundWire ?? "responses";
      const policy = captureRouteStaticPolicy(route.providerName, modelId, route.provider,
        route.staticPolicy.effectiveAlias, inboundWire);
      const provider = resolveWireProtocolOverride(route.providerName, modelId, route.provider, inboundWire, policy);
      // Copilot's Auto account may settle on a different wire; the child checks that result.
      if (route.providerName === "github-copilot" && provider.authMode !== "forward") return true;
      return provider.adapter === "openai-chat" ? chatCanPreserveMandatoryToolChoice(body, provider, modelId)
        : provider.adapter !== "openai-responses" || !isMetaAiResponsesDestination(buildResponsesTransport(provider, { headers: req.headers }).url);
    } catch {
      return true;
    }
  };
  const onlyMuseToolIncompatible = (): boolean => {
    const enabled = combo.targets.filter(target => config.providers[target.provider]?.disabled !== true);
    return enabled.length > 0 && enabled.every(target => !museToolEligible(target));
  };
  // A mandatory tool_choice no target preserves is unsupported (#7965), but shared exclusion evidence
  // (provider state, quota, live cooldowns) keeps precedence, exactly as in the readable reasons.
  const unsupportedToolChoice = (attempted: number) => comboUnavailableDiagnostics(combo.targets.length, attempted,
    combo.targets.map(target => comboTargetUnavailableCause(config, comboId, target, museToolEligible) ?? "unsupported"));
  const capabilityCandidate = (target: (typeof combo.targets)[number]): boolean =>
    mayUseTarget(target)
    && museToolEligible(target)
    && reasoningReplayEligible(target)
    && (protocolLanes?.pickable(target) ?? true);
  const unservableImageResponse = (): Response =>
    markProxyError(formatErrorResponse(400, "invalid_request_error", "No target of this combo can accept image input"));
  const warnComboImageOmission = (): void =>
    console.warn("[opencodex] combo has no image-capable target; images will be omitted");
  const resolveCapabilityRoute = (target: Pick<(typeof combo.targets)[number], "provider" | "model">) => {
    try {
      const route = routeConcreteModel(config, `${target.provider}/${target.model}`);
      const provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, options.inboundWire);
      return { ...route, provider };
    } catch { return undefined; }
  };
  const admitCombo = async () => {
    if (combo.imageInput === "disabled" && unresolvedPrevious) {
      markLinkTurnMissing(logCtx);
      return formatErrorResponse(
        400,
        "previous_response_not_found",
        "Continuation state is unavailable or corrupt; resend the full conversation without previous_response_id.",
      );
    }
    if (combo.imageInput === "disabled" && comboRequestHasImageInput(body)) {
      return formatErrorResponse(400, "invalid_request_error", "This combo does not accept image input");
    }
    const metadata = {
      providers: admissionSnapshot.providers,
      customModels: admissionSnapshot.customModels,
      providerContextCaps: admissionSnapshot.providerContextCaps,
      visionSidecar: admissionSnapshot.vision,
    };
    const capability = await comboCapabilityGate(metadata, combo, body,
      target => {
        const route = resolveCapabilityRoute(target);
        return route && {
          providerName: route.providerName, modelId: route.modelId, codexAccountId: route.codexAccountId,
          provider: snapshotComboAdmissionProvider(route.provider),
        };
      },
      (target, route, parsed) => capabilityCandidate(target)
        && (!admissionScope || !!route && routeAllowedByScope(admissionScope, route))
        && (options.anthropicHostedAdvisorSelection !== "selected" || !!route && admitsHostedAdvisor(
          route.provider, scopedAnthropicServerTools(admissionScope, route, options.anthropicServerTools), parsed?.context.tools,
        )),
      (route, parsed) => canDescribeComboImages(
        { config, req, options: { ...options, admissionScope, comboVisionSidecar } }, route, parsed));
    if (capability.unservable === "audio") {
      return formatErrorResponse(400, "invalid_request_error", "No target of this combo can accept audio input");
    }
    if (capability.unservable && combo.onUnservable === "reject") {
      return capability.unservable === "context"
        ? formatErrorResponse(400, "invalid_request_error", "No target of this combo has a context window large enough for this request")
        : unservableImageResponse();
    }
    return capability;
  };
  const capability = await admitCombo();
  if (capability instanceof Response) return capability;
  if (capability.unservable === "image") warnComboImageOmission();
  if (capability.unservable === "context") console.warn("[opencodex] combo has no target whose context window fits; sending to the largest");
  const visionRejectedTargets = new Set<string>();
  let omittingImages = capability.unservable === "image";
  const useImageDegradation = (target: (typeof combo.targets)[number]): boolean =>
    payloadEligible(target) && capabilityCandidate(target) && capability.imageDegradationEligible(target);
  // Recovery can replace unreadable encrypted input, but cannot relax other admission checks.
  const recoveryEligible = (target: (typeof combo.targets)[number]): boolean =>
    capabilityCandidate(target) && (omittingImages && capability.unservable !== "image"
      ? capability.imageDegradationEligible(target)
      : !visionRejectedTargets.has(targetKey(target)) && capability.eligible(target));
  const targetEligible = (target: (typeof combo.targets)[number]): boolean =>
    payloadEligible(target) && recoveryEligible(target);
  const onlyReplayIncompatibleTargetsRemain = (excluded: Iterable<string> = []): boolean => {
    const excludedKeys = new Set(excluded);
    const remaining = combo.targets.filter(target => {
      const provider = config.providers[target.provider];
      return provider?.disabled !== true
        && !excludedKeys.has(targetKey(target))
        && payloadEligible(target);
    });
    return remaining.length > 0 && remaining.every(target => !reasoningReplayEligible(target));
  };
  let encryptedTaskRecoveryAttempted = false;
  let recoveryFailureReason: AgentTaskRecoveryFailureReason | undefined;
  let storedPool401ReplayDispatched = false;
  const recovery = agentTaskRecoveryConfig(config);
  const encryptedTaskRecoveryAdmitted = (options.inboundWire ?? "responses") === "responses"
    && isThreadSpawnRequest(req.headers) && !!recovery && !options.comboAttempt;
  const recoverUnreadableEncryptedTask = async (): Promise<boolean> => {
    if (encryptedTaskRecoveryAttempted) return false;
    encryptedTaskRecoveryAttempted = true;
    if (!encryptedTaskRecoveryAdmitted || !recovery) {
      discardEncryptedAgentTaskRecovery(
        req,
        (body as { input?: unknown } | undefined)?.input,
        config,
        { parentThreadId: inboundClientThreadId },
      );
      return false;
    }
    let recovered = false;
    try {
      const result = await recoverEncryptedAgentTaskWithResult(
        req,
        (body as { input?: unknown } | undefined)?.input,
        recovery,
        config,
        { parentThreadId: inboundClientThreadId, abortSignal: options.abortSignal },
      );
      recovered = result.recovered;
      recoveryFailureReason = result.recovered ? undefined : result.reason;
    } catch {
      recovered = false;
      recoveryFailureReason = undefined;
    }
    // Recovery has the same in-place input mutation contract as the direct routed path.
    if (
      !recovered
      || hasUnreadableEncryptedAgentTask((body as { input?: unknown } | undefined)?.input)
    ) {
      discardEncryptedAgentTaskRecovery(
        req,
        (body as { input?: unknown } | undefined)?.input,
        config,
        { parentThreadId: inboundClientThreadId },
      );
      return false;
    }
    comboPayloadReadable = true;
    comboReplaySnapshot.recoveredPlaintext = true;
    return true;
  };
  const initialNow = Date.now();
  const pickWithWait = (pickOptions: {
    exclude?: Iterable<string>;
    eligible?: (target: NonNullable<typeof combo>["targets"][number]) => boolean;
    allowCooldownReprobe?: boolean;
    /** This request's own cooldown-reprobe reservation, carried through its failover hops. */
    cooldownReprobeTargets?: Iterable<readonly [string, number]>;
    now?: number;
  }) => pickComboTargetWithWait(config, comboId, {
    ...pickOptions,
    // Every pick, including the recovery picks that skip `targetEligible`, keeps metered
    // targets away from callers that may not spend on them.
    eligible: target => maySpendOnTarget(target) && (pickOptions.eligible?.(target) ?? true),
    waitForCooldownMs: combo.waitForCooldownMs,
    abortSignal: options.abortSignal,
  });
  // An in-flight tool loop stays on the target that issued its calls while that target is still
  // selectable (#7298). Override routes never record a lane target, so they never pin either.
  const toolLoopPin = options.compactionRoutingOverride || options.mainHardLockFallbackOverride
    ? undefined
    : toolLoopPinnedPick({
      config,
      comboId,
      lane: sessionLaneIdFromRequest(req.headers),
      body,
      eligible: target => maySpendOnTarget(target) && targetEligible(target),
      now: initialNow,
    });
  let pick = toolLoopPin ?? await pickWithWait({
    eligible: targetEligible,
    now: initialNow,
  });
  // Opt-in JEV session pin (#7525); override routes neither read nor write it, like the lane recall.
  const jevPin = options.compactionRoutingOverride || options.mainHardLockFallbackOverride
    ? undefined
    : jevSessionPinScope({ combo, comboId, admission: options.admission, lane: sessionLaneIdFromRequest(req.headers) });
  // A tool-loop continuation never asks JEV again, so under `decide` it keeps the effort the
  // decision set for its turn while the target still offers it. Without this the rest of the
  // turn ran at the caller's effort and only the first request at the decided one.
  let toolLoopTurnEffort: ComboTurnEffort | undefined;
  if (toolLoopPin && combo.strategy === "jev" && combo.jevEffortMode !== "client") {
    const carried = recallComboTurnEffortForLane(sessionLaneIdFromRequest(req.headers), comboId, toolLoopPin.target);
    const offered = carried ? jevChoiceEfforts(config, toolLoopPin.target, false)?.reasoningEfforts : undefined;
    if (carried && offered && (carried.effort === null ? offered.length === 0 : offered.includes(carried.effort))) {
      toolLoopTurnEffort = carried;
    }
  }

  if (unreadableEncryptedAgentTask && !pick) {
    pick = await pickWithWait({
      eligible: recoveryEligible,
      allowCooldownReprobe: encryptedTaskRecoveryAdmitted,
      now: initialNow,
    });
    if (!pick) {
      discardEncryptedAgentTaskRecovery(
        req,
        (body as { input?: unknown } | undefined)?.input,
        config,
        { parentThreadId: inboundClientThreadId },
      );
      if (!options.abortSignal?.aborted && onlyMuseToolIncompatible()) {
        return comboUnavailableResponse("No available targets for combo; targets cannot preserve mandatory tool_choice",
          { diagnostics: unsupportedToolChoice(0) });
      }
      return options.abortSignal?.aborted
        ? clientCancelledResponse()
        : comboUnavailable(comboId, undefined,
          comboExclusion(config, comboId, recoveryEligible));
    }
    if (!(await recoverUnreadableEncryptedTask())) {
      return options.abortSignal?.aborted
        ? clientCancelledResponse()
        : unreadableEncryptedAgentTaskResponse(recoveryFailureReason);
    }
  }

  if (!pick) {
    // Every enabled candidate skipped as unrepresentable: the ingress refusal, with no send.
    const protocolRefusal = protocolLanes?.refusal();
    if (protocolRefusal) return protocolRefusal;
    if (onlyReplayIncompatibleTargetsRemain()) return targetIncompatibleResponse();
    if (!options.abortSignal?.aborted && onlyMuseToolIncompatible()) {
      return comboUnavailableResponse("No available targets for combo; targets cannot preserve mandatory tool_choice",
        { diagnostics: unsupportedToolChoice(0) });
    }
    return options.abortSignal?.aborted
      ? clientCancelledResponse()
      : comboUnavailable(comboId, undefined, comboExclusion(config, comboId, targetEligible));
  }
  // OCX-11: an ordered failover combo that starts on a later target than its first one, for any
  // reason (cooling down, provider disabled, cached quota spent, ineligible for this request),
  // makes a proactive hop, so the fallback policy decides before anything is sent. Both ends are
  // the resolved destinations, after provider aliases and blockedModelRedirects.
  const primaryTarget = combo.targets[0];
  // An allowed hop is recorded only once its dispatch is admitted below.
  let pendingHopCommit: (() => void) | undefined;
  if (!toolLoopPin && (combo.strategy ?? "failover") === "failover" && primaryTarget
    && targetKey(primaryTarget) !== targetKey(pick.target)) {
    const primaryCooling = isComboTargetInCooldown(comboId, primaryTarget, initialNow);
    const proactive = guardFallbackHop(config, {
      site: "combo",
      route: `combo/${comboId}`,
      aliases: [requestedModel],
      from: resolvedComboDestination(config, primaryTarget),
      to: resolvedComboDestination(config, pick.target),
      trigger: primaryCooling ? "cooldown" : comboTargetSkipTrigger(config, primaryTarget, initialNow),
      admission: options.admission,
      retryAfter: primaryCooling ? comboCooldownRetryAfterSeconds(comboId, initialNow) ?? null : null,
      now: initialNow,
    });
    if (!proactive.ok) return proactive.response;
    pendingHopCommit = proactive.commit;
  }
  let jevDecision: JevDecision | undefined;
  let failedPinEffortDecision: JevDecision | undefined;
  if (combo.strategy === "jev" && !toolLoopPin) {
    // Live spend authority only: consent and the key's current scope.
    const spendAllowed = (scope: typeof admissionScope) => (target: (typeof combo.targets)[number]): boolean => {
      if (!maySpendOnTarget(target)) return false;
      if (!scope) return true;
      try {
        return routeAllowedByScope(scope, routeConcreteModel(config, `${target.provider}/${target.model}`));
      } catch {
        return false;
      }
    };
    // The decision call is a paid send: offer only members that live consent and scope still admit.
    const decisionScope = currentAdmissionScope();
    const choices = eligibleJevComboChoices(config, comboId,
      target => targetEligible(target) && spendAllowed(decisionScope)(target), Date.now(), pick.cooldownReprobeTargets);
    const first = choices[0];
    if (!first) {
      return comboUnavailable(comboId, undefined, comboExclusion(config, comboId, target =>
        targetEligible(target) && target.provider !== JEV_PROVIDER_ID && jevChoiceEfforts(config, target, false) !== undefined));
    }
    const fallbackFor = (choice: JevComboChoice): Pick<JevDecision, "targetKey" | "effort"> => {
      const effort = resolveEffortAtOrBelow("medium", choice.candidate.reasoningEfforts);
      return {
        targetKey: choice.candidate.key,
        effort: effort && isCodexReasoningEffort(effort) ? effort as OcxComboDefaultEffort : null,
      };
    };
    const fallback = fallbackFor(first);
    const decisionStartedAt = Date.now();
    const pinReuse = jevPin?.reuse(
      choices.map(choice => choice.candidate),
      combo.decisionQuotaSignals === true ? { config, tiers: combo.decisionQuotaTiers } : undefined,
    );
    const decide = (candidates: JevCandidate[], fallbackDecision: Pick<JevDecision, "targetKey" | "effort">) =>
      resolveJevComboDecision({
        body,
        candidates,
        fallback: fallbackDecision,
        config,
        isDestinationAllowed: (providerName, modelId) => routeAllowedByScope(
          decisionScope, { providerName, modelId },
        ),
        ...(combo.decisionQuotaSignals === true ? { decisionQuotaSignals: true, decisionQuotaTiers: combo.decisionQuotaTiers } : {}),
        ...(combo.decisionProvider ? { decisionProvider: combo.decisionProvider } : {}),
        ...(combo.decisionModel
          ? {
            decisionModel: combo.decisionModel,
            invokeModel: createJevModelInvoker({
              req,
              config,
              options: { ...options, admissionScope: decisionScope },
              handleResponses: requestDispatchers.handleResponses,
            }),
          }
          : {}),
        ...(combo.decisionTimeoutMs !== undefined ? { timeoutMs: combo.decisionTimeoutMs } : {}),
        signal: options.abortSignal,
      });
    let decision: JevDecision;
    let awaitedPinEffort = false;
    if (pinReuse?.decision) {
      const pinned = pinReuse.decision;
      decision = pinned;
      // `effort: "per-turn"` keeps the pinned target and asks only for its effort, offering the
      // pinned target alone. Anything but an applied answer for that target keeps the pinned effort.
      const pinnedChoice = combo.sessionPin?.effort === "per-turn" && combo.jevEffortMode !== "client"
        ? choices.find(choice => choice.candidate.key === pinned.targetKey)
        : undefined;
      if (pinnedChoice && pinnedChoice.candidate.reasoningEfforts.length > 1) {
        awaitedPinEffort = true;
        decision = { ...pinned, pinReason: "session_effort" };
        const fallback = { targetKey: pinned.targetKey, effort: pinned.effort };
        try {
          const effortDecision = await decide([pinnedChoice.candidate], fallback);
          if (effortDecision.gate === "apply" && effortDecision.targetKey === pinned.targetKey) {
            decision = { ...effortDecision, pinned: true, pinReason: "session_effort" };
          } else {
            failedPinEffortDecision = {
              ...effortDecision, ...fallback,
              gate: effortDecision.gate === "apply" ? "invalid" : effortDecision.gate,
            };
          }
        } catch {
          if (options.abortSignal?.aborted) return clientCancelledResponse();
          failedPinEffortDecision = {
            ...fallback, backend: jevDecisionBackendFor(combo), gate: "network",
            latencyMs: Math.max(0, Date.now() - decisionStartedAt),
          };
        }
      }
    } else try {
      decision = await decide(choices.map(choice => choice.candidate), fallback);
    } catch (error) {
      if (options.abortSignal?.aborted) return clientCancelledResponse();
      decision = {
        backend: jevDecisionBackendFor(combo),
        ...fallback,
        gate: "network",
        latencyMs: Math.max(0, Date.now() - decisionStartedAt),
      };
    }
    let selected = choices.find(choice => choice.candidate.key === decision.targetKey) ?? first;
    const recordDecision = (observedDecision: JevDecision) => logCtx.jevDecision = !options.clientModelLabel || requestedModel === responseModel ? normalizePersistedJevDecision({
      version: 1,
      comboId,
      selected: {
        provider: selected.pick.target.provider,
        model: selected.pick.target.model,
        effort: decision.effort,
      },
      gate: observedDecision.gate,
      latencyMs: observedDecision.latencyMs,
      backend: observedDecision.backend,
      ...(observedDecision.confidence !== undefined ? { confidence: observedDecision.confidence } : {}),
      ...(observedDecision.chosenProbability !== undefined
        ? { chosenProbability: observedDecision.chosenProbability }
        : {}),
      ...(observedDecision.usage ? { usage: observedDecision.usage } : {}),
      ...(observedDecision.quota ? { quota: observedDecision.quota } : {}),
      ...(decision.pinned ? { pinned: true } : {}),
      ...(decision.pinReason ? { pinReason: decision.pinReason } : {}),
    }) : undefined;
    let selectionUnavailable = false;
    if ((!pinReuse?.decision || pick.cooldownReprobeTargets || awaitedPinEffort) && !options.abortSignal?.aborted) {
      // Record the paid decision before anything below can refuse or throw.
      recordDecision(failedPinEffortDecision ?? decision);
      // The decided choices were admitted against the request-start snapshot. Recheck only what
      // can change their spend: availability (cooldowns, reprobe reservations), live consent and
      // the key's current scope. Capability edits made meanwhile apply to the next request.
      let currentChoices: typeof choices;
      try {
        const available = new Set(eligibleJevComboChoices(requestStartComboConfig(config, comboId, admissionSnapshot.rawCombo),
          comboId, spendAllowed(currentAdmissionScope()), Date.now(), pick.cooldownReprobeTargets)
          .map(choice => choice.candidate.key));
        currentChoices = choices.filter(choice => available.has(choice.candidate.key));
      } catch {
        return options.abortSignal?.aborted ? clientCancelledResponse() : comboUnavailable(comboId);
      }
      const current = currentChoices.find(choice => choice.candidate.key === decision.targetKey
        && (decision.effort === null ? choice.candidate.reasoningEfforts.length === 0
          : choice.candidate.reasoningEfforts.includes(decision.effort)));
      const available = current ?? currentChoices[0];
      if (available) selected = available;
      else selectionUnavailable = true;
      if (!current) {
        // Keep completed decision usage even when no target remains. Old scores and quota
        // selection describe neither a fail-open replacement nor a rejected selection.
        decision = {
          backend: decision.backend,
          ...(available ? fallbackFor(available) : { targetKey: decision.targetKey, effort: decision.effort }),
          gate: decision.gate === "apply" ? "invalid" : decision.gate,
          latencyMs: decision.latencyMs,
          ...(decision.usage ? { usage: decision.usage } : {}),
        };
      }
    }
    if (pinReuse?.released) decision = { ...decision, pinReason: pinReuse.released };
    jevDecision = decision;
    pick = { ...selected.pick, attempted: [targetKey(selected.pick.target)] };
    // Keep effort-call telemetry and take pin attribution from the final selection.
    const observedDecision = failedPinEffortDecision ?? decision;
    recordDecision(observedDecision);
    console.debug("[combo] JEV decision", {
      backend: observedDecision.backend,
      target: comboTargetLogLabel(config, comboId, pick.target),
      effort: decision.effort,
      gate: observedDecision.gate,
      latencyMs: observedDecision.latencyMs,
      ...(decision.pinReason ? { pinReason: decision.pinReason } : {}),
      ...(observedDecision.confidence !== undefined ? { confidence: observedDecision.confidence } : {}),
      ...(observedDecision.chosenProbability !== undefined
        ? { chosenProbability: observedDecision.chosenProbability }
        : {}),
      ...(observedDecision.usage ? { usage: observedDecision.usage } : {}),
    });
    // A completed decision belongs to the parent log even if no model can be dispatched.
    if (selectionUnavailable) {
      return comboUnavailable(comboId, undefined, comboExclusion(config, comboId, target =>
        targetEligible(target) && target.provider !== JEV_PROVIDER_ID && jevChoiceEfforts(config, target, false) !== undefined));
    }
  }
  // One immutable combo selection trace, before any child dispatch; child
  // adoption below must never replace it with a concrete child route trace.
  const decision = comboRouteDecisionTrace(config, comboId, pick, responseModel);
  const selectedReason = options.memoryModelPhase
    ? memoryModelRouteReason(options.memoryModelPhase)
    : toolLoopPin ? COMBO_TOOL_LOOP_PIN_REASON : jevDecision?.pinned ? JEV_SESSION_PIN_ROUTE_REASON : undefined;
  logCtx.routeDecision = selectedReason
    ? { ...decision, selected: { ...decision.selected, reason: selectedReason } }
    : decision;

  const originalReasoning = body && typeof body === "object" && !Array.isArray(body)
    ? (body as { reasoning?: unknown }).reasoning
    : undefined;
  const originalRequestedEffortValue = originalReasoning && typeof originalReasoning === "object" && !Array.isArray(originalReasoning)
    ? (originalReasoning as { effort?: unknown }).effort
    : undefined;
  const originalRequestedEffort = typeof originalRequestedEffortValue === "string"
    && isDeclaredReasoningEffort(originalRequestedEffortValue)
    ? originalRequestedEffortValue
    : undefined;
  const restoreOriginalRequestedEffort = (childLog: RequestLogContext, forcedEffort?: string | null): void => {
    if (originalRequestedEffort === undefined) return;
    childLog.requestedEffort = comboRequestedEffortLabel(originalRequestedEffort, childLog.requestedEffort, forcedEffort);
    recordAttemptRequestedEffort(childLog);
  };

  let lastFailure: Response | null = null;
  // Dispatched targets, not attempted picks: it indexes the declared target list so the clamp
  // below can tell how many targets are still entitled to a send.
  let comboTargetsDispatched = 0;
  // The child log behind `lastFailure`. The natural end of the ladder adopts it inside the
  // no-more-targets branch; a budget refusal ends the ladder one iteration later, where that
  // iteration's own `childLog` is already out of scope.
  let lastFailedChildLog: RequestLogContext | undefined;
  // The target behind `lastFailure`, so the next dispatch can tell a hop from a same-target retry.
  let lastFailedTarget: { provider: string; model: string } | undefined;
  let lastFailedRetryAfter: string | undefined;
  // The exhausted-combo mapping below runs outside the loop, where `failure.upstreamCode`
  // is gone, so carry the loop's own classification decision instead of re-deriving a
  // weaker one from the status alone (#4149).
  let lastFailureClassifiesOverflow = false;
  let zeroOutputLimitFailure: { childLog: RequestLogContext; usage?: OcxUsage } | undefined;
  let lastFailureUpstreamCode: string | undefined;
  const wantsStream = (rawBody as { stream?: unknown } | null)?.stream === true || (body as { stream?: unknown } | null)?.stream === true;
  // Local input admission refusals (#1524), while every failed target so far was one: such a
  // target sent nothing, so an exhausted ladder must not be reported as a provider rejection.
  let localAdmissionRefusals: string[] | undefined = [];
  let toolChoiceRefusalsOnly: boolean | undefined;
  // The first quota/rate-limit refusal of the ladder. A fallback that then refuses its own
  // credential or plan (401/403, or a 400 the ladder hopped past) says nothing about why the
  // request failed: the primary target ran out. Returning that fallback refusal told clients
  // "OpenAI account pool has no usable account credential" while every Claude account was spent.
  let quotaFailure: Response | undefined;
  let quotaFailedChildLog: RequestLogContext | undefined;
  let contextFailure: { response: Response; childLog: RequestLogContext } | undefined;
  let xaiPrivacyFailure: { response: Response; childLog: RequestLogContext } | undefined;
  // Snapshotted before dispatch: a 401/403 inside this ladder cools its own provider, and that
  // fresh cooldown is not a reason the request found no target.
  const quotaCooldownSnapshot = snapshotComboQuotaCooldowns(config, comboId);
  const exhaustedFailure = (targetsExhausted = false): Response => {
    const finalize = (response: Response, childLog = lastFailedChildLog): Response => {
      if (childLog) adoptFailedChildLog(childLog);
      return response;
    };
    if (contextFailure) {
      return finalize(contextFailure.response, contextFailure.childLog);
    }
    if (lastFailure && lastFailureUpstreamCode === "zero_output_token_limit" && zeroOutputLimitFailure) {
      adoptFailedChildLog(zeroOutputLimitFailure.childLog);
      // The terminal builder normalizes wire usage even when the child supplied none.
      logCtx.clientResponseUsage = "synthetic";
      return wantsStream
        ? streamingIncompleteResponse(responseModel, zeroOutputLimitFailure.usage, "max_output_tokens", options.translatorBudget)
        : jsonIncompleteResponse(responseModel, zeroOutputLimitFailure.usage, "max_output_tokens");
    }
    if (targetsExhausted && toolChoiceRefusalsOnly === true) return finalize(comboUnavailableResponse("No available targets for combo; attempted targets cannot preserve mandatory tool_choice", { diagnostics: unsupportedToolChoice(comboTargetsDispatched) }));
    if (lastFailure?.status === 429 || lastFailure?.status === 402) return finalize(lastFailure);
    const privacyOrLastFailure = () => xaiPrivacyFailure
      ? finalize(xaiPrivacyFailure.response, xaiPrivacyFailure.childLog)
      : finalize(lastFailure!);
    if (!lastFailure || ![400, 401, 403].includes(lastFailure.status)) return privacyOrLastFailure();
    if (quotaFailure) return finalize(quotaFailure, quotaFailedChildLog);
    // The quota-refused target was cooled before this request picked, so the ladder never saw
    // its refusal. The cooldown, with its Retry-After, is still the honest answer.
    let quotaCooldownUntil: number | undefined;
    let quotaCooledTargets = 0;
    const now = Date.now();
    for (const { target, cooldownUntil } of quotaCooldownSnapshot) {
      if (cooldownUntil <= now) continue;
      try {
        if (!targetEligible(target)) continue;
      } catch {
        // An eligibility check can exhaust the translator budget; it is not quota evidence.
        continue;
      }
      quotaCooldownUntil = Math.min(quotaCooldownUntil ?? cooldownUntil, cooldownUntil);
      quotaCooledTargets += 1;
    }
    const remainingQuotaCooldownMs = quotaCooldownUntil === undefined ? 0 : quotaCooldownUntil - Date.now();
    return remainingQuotaCooldownMs > 0
      ? finalize(comboUnavailableResponse("No available targets for combo", {
        retryAfter: String(Math.max(1, Math.ceil(remainingQuotaCooldownMs / 1000))),
        // Only quota-cooled eligible targets can produce this answer, so its class is quota.
        diagnostics: comboUnavailableDiagnostics(combo.targets.length, comboTargetsDispatched,
          Array.from({ length: quotaCooledTargets }, () => "quota" as const)),
      })) : privacyOrLastFailure();
  };
  // The caller's output ceiling, captured once so a floor applied to one target never
  // leaks into the next. An established parent estimate wins; otherwise (combo dispatch
  // precedes request preparation) the caller's own positive cap is reserved.
  const callerBudget = isPlainObject(body) ? body.max_output_tokens : undefined;
  const callerOutputCeilingTokens = logCtx.spendOutputCeilingTokens
    ?? (typeof callerBudget === "number" && Number.isFinite(callerBudget) && callerBudget > 0
      ? Math.trunc(callerBudget) : undefined);
  while (pick) {
    if (options.abortSignal?.aborted) return clientCancelledResponse();
    const firstComboTarget = comboTargetsDispatched === 0;
    // The physical destination after provider aliases and blockedModelRedirects: hops are
    // classified by where the request really goes, not by the selector the combo names.
    const targetRoute = routeConcreteModel(config, `${pick.target.provider}/${pick.target.model}`);
    // Every child send rechecks live metered consent and the key's current scope; a member that
    // fails either is skipped and an eligible sibling may still run.
    const dispatchScope = currentAdmissionScope();
    const scopeAllowed = routeAllowedByScope(dispatchScope, targetRoute);
    if (!scopeAllowed || !maySpendOnTarget(pick.target)) {
      const skipped: ComboPick = pick;
      pick = await pickWithWait({
        exclude: skipped.attempted,
        eligible: targetEligible,
        allowCooldownReprobe: false,
        cooldownReprobeTargets: Object.entries(skipped.cooldownReprobeTargets ?? {}),
      });
      if (options.abortSignal?.aborted) return clientCancelledResponse();
      if (!pick) {
        // A scope refusal keeps the child's own 403; a consent refusal ends like any exhausted ladder.
        if (!scopeAllowed) {
          return admissionModelDeniedResponse(projectAdmissionModelDeniedLog(
            new AdmissionModelDeniedError(clientModelLabel, targetRoute), logCtx));
        }
        return lastFailure ? exhaustedFailure() : comboUnavailable(comboId);
      }
      jevDecision = undefined;
      toolLoopTurnEffort = undefined;
      continue;
    }
    // Selection-free hard-lock preflight grants no hop. Enforce this actual first destination
    // against the locked source, after aliases and redirects resolve.
    if (firstComboTarget && options.mainHardLockFallbackOverride) {
      const hop = guardFallbackHop(config, {
        site: "combo",
        route: `combo/${comboId}`,
        aliases: [requestedModel],
        from: { provider: OPENAI_CODEX_PROVIDER_ID, model: options.mainHardLockFallbackOverride.sourceModel },
        to: { provider: targetRoute.providerName, model: targetRoute.modelId },
        trigger: "hard_lock",
        admission: options.admission,
      });
      if (!hop.ok) return hop.response;
      const declaredCommit = pendingHopCommit;
      pendingHopCommit = declaredCommit ? () => { declaredCommit(); hop.commit(); } : hop.commit;
    }
    // OCX-11: every later dispatch after a failure is a hop when the target changed. One check
    // here covers the ordinary failover pick and the recovery picks alike.
    if (!firstComboTarget && lastFailure && lastFailedTarget) {
      const hop = guardFallbackHop(config, {
        site: "combo",
        route: `combo/${comboId}`,
        aliases: [requestedModel],
        from: lastFailedTarget,
        to: { provider: targetRoute.providerName, model: targetRoute.modelId },
        trigger: fallbackTriggerForStatus(lastFailure.status),
        admission: options.admission,
        failureStatus: lastFailure.status,
        retryAfter: lastFailedRetryAfter ?? null,
      });
      if (!hop.ok) {
        if (lastFailedChildLog) adoptFailedChildLog(lastFailedChildLog);
        return hop.response;
      }
      pendingHopCommit = hop.commit;
    }
    // The inherited spend tracker observes this parent log, before the child has its own label.
    logCtx.spendPoolId = targetRoute.providerName;
    // Combo prepays before its child normalizes the route; the parent tracker must
    // already see this target's effective cap rather than a previous target's cap.
    const spendProvider = resolveWireProtocolOverride(targetRoute.providerName, targetRoute.modelId,
      targetRoute.provider, options.inboundWire ?? "responses", targetRoute.staticPolicy);
    const outputBudget = effectiveAzureOutputBudget(spendProvider, callerBudget);
    if (outputBudget !== callerBudget && typeof outputBudget === "number" && outputBudget > 0) {
      logCtx.spendOutputCeilingTokens = Math.trunc(outputBudget);
    } else if (callerOutputCeilingTokens === undefined) {
      delete logCtx.spendOutputCeilingTokens;
    } else {
      logCtx.spendOutputCeilingTokens = callerOutputCeilingTokens;
    }
    // Derive the target's allowance before booking its initial send; the booking occupies it.
    const targetSendBudget = comboSendScope
      ? comboTargetSendBudget(comboSendScope, combo.targets.length - 1 - comboTargetsDispatched)
      : options.sendBudget;
    // Every target prepays one send. Only its child may consume that booking; later targets
    // remain bounded by the shared total, transition ledger and per-target holdback.
    // `countedExternally` is required: the child charges its own physical sends against this
    // booking through the exact permit, and charging here as well would halve the cap.
    const hopDecision = comboSendScope?.reserveDispatch({
      sendClass: firstComboTarget ? "initial" : "combo-failover",
      targetKey: `${pick.target.provider}/${pick.target.model}`,
      countedExternally: true,
    });
    if (hopDecision && !hopDecision.allowed && firstComboTarget) {
      // A refused initial reservation authorizes no child send and has no upstream failure to return.
      return formatErrorResponse(429, SEND_BUDGET_EXHAUSTED_CODE, "request send budget exhausted before combo dispatch");
    }
    else if (hopDecision && !hopDecision.allowed) {
      // Out of budget is not this target's failure. The established exhaustion contract is to
      // return the last real upstream answer with its status, headers and any quota body
      // intact rather than to mint a synthetic error, and a later target only exists because
      // an earlier one already recorded one.
      return exhaustedFailure();
    }
    // Admitted: only now is a guarded hop to this target recorded as taken.
    pendingHopCommit?.();
    pendingHopCommit = undefined;
    const initialSend = hopDecision?.allowed ? { permit: hopDecision.permit, producerOwned: false } : undefined;
    try {
    comboTargetsDispatched += 1;
    const targetOutputCeiling = resolveOutputCeiling(
      targetRoute.provider,
      targetRoute.providerName,
      targetRoute.modelId,
    );
    const childLog: RequestLogContext = {
      model: pick.target.model,
      provider: pick.target.provider,
      comboTarget: pick.target,
      comboWriterGeneration: pick.writerGeneration,
      comboTargetOutputCeiling: targetOutputCeiling,
      ...(logCtx.conversationId ? { conversationId: logCtx.conversationId, conversationIdIsHermesFallback: logCtx.conversationIdIsHermesFallback } : {}),
      ...(logCtx.affinityLane ? { affinityLane: logCtx.affinityLane } : {}),
      ...(logCtx.surface ? { surface: logCtx.surface } : {}),
    };
    // A link turn's child reads its upstream only as the client drains, as the parent would (#8601).
    bindLinkTurnChild(logCtx, childLog);
    const targetReasoningEfforts = supportedLadderFor({
      provider: targetRoute.provider,
      modelId: targetRoute.modelId,
    });
    const initialJevDecision = firstComboTarget ? jevDecision : undefined;
    // The effort a decision owns on this dispatch: its own first request, or the turn a
    // tool-loop continuation resumes. Failover targets keep ordinary Combo policy either way.
    const turnEffort: ComboTurnEffort | undefined = initialJevDecision
      ?? (firstComboTarget ? toolLoopTurnEffort : undefined);
    // `client` keeps the decision's target but not its tier: the caller and the target ladder
    // own the wire effort, so a provider whose effort swaps the upstream model id is never
    // re-tiered mid-session and its prompt cache survives the turn.
    const jevEffortApplies = turnEffort !== undefined && combo.jevEffortMode !== "client";
    const childInput = options.droidDefaultEffort && isPlainObject(body) ? { ...body } : body;
    applyDroidResponsesReasoningDefault(childInput, options.droidDefaultEffort, {
      provider: targetRoute.provider,
      modelId: targetRoute.modelId,
    });
    const childBody = concreteComboRequestBody(
      childInput,
      pick.target,
      jevEffortApplies ? turnEffort.effort : combo.defaultEffort,
      jevEffortApplies && turnEffort.effort === null ? [] : targetReasoningEfforts,
      combo.reasoningEffortMode,
      jevEffortApplies
        ? (turnEffort.effort === null ? "fallback" : "force")
        : combo.defaultEffortMode,
    );
    if (comboAdvertisesEffortUnion(combo.capabilityPolicy, combo.reasoningEffortMode)) {
      clampComboCallerEffort(childBody, targetReasoningEfforts, pick.target);
    }
    if (turnEffort) {
      if (jevEffortApplies) delete childBody.service_tier;
      if (jevEffortApplies && turnEffort.effort !== null) {
        const childReasoning = childBody.reasoning;
        const preservedReasoning = childReasoning && typeof childReasoning === "object" && !Array.isArray(childReasoning)
          ? childReasoning as Record<string, unknown>
          : {};
        childBody.reasoning = { ...preservedReasoning, effort: turnEffort.effort };
        delete childBody.reasoning_effort;
        delete childBody.thinking_budget;
        delete childBody.thinking;
      }
    }
    const childHeaders = buildComboChildHeaders(req.headers);
    const childRequest = new Request(req.url, {
      method: req.method,
      headers: childHeaders,
      body: JSON.stringify(childBody),
    });
    linkRequestSessionLane(req, childRequest);
    let resolvedAuth: CodexAuthContext | undefined;
    let terminalRecorder: ((status: ResponsesTerminalStatus, httpStatusOverride?: number) => void) | undefined;
    const started = Date.now();
    const attempt = beginRequestAttempt(
      (logCtx.attempts?.length ?? 0) + 1,
      pick.target.provider,
      // The id the child wire will actually send, not the selector the combo named. A target may
      // be an alias, and `routeConcreteModel` above is where it becomes the provider's native id;
      // recording the alias here would describe a request that never left (the adapter resolves
      // the id before it reads any per-model list).
      targetRoute.modelId,
      config.providers[pick.target.provider]!.adapter,
    );
    childLog.activeAttempt = attempt;
    if (originalRequestedEffort !== undefined) {
      childLog.requestedEffort = originalRequestedEffort;
      recordAttemptRequestedEffort(childLog);
    }
    childLog.activeAttemptStartedAt = started;
    childLog.attempts = logCtx.attempts ??= [];
    childLog.attempts.push(attempt);
    // A key or account rotation inside this target seals the previous segment as its own attempt
    // and moves `childLog.activeAttemptStartedAt` forward (noteProviderAttemptSend). Timing the
    // live segment from the target's start would count every sealed segment a second time.
    const segmentStartedAt = (): number => childLog.activeAttemptStartedAt ?? started;
    let attemptRetained = false;
    const retainCancelledAttempt = (): void => {
      if (attemptRetained) return;
      sealRequestAttemptIdentity(
        attempt,
        childLog.provider,
        childLog.providerAdapter ?? attempt.adapter,
        childLog.accountLogLabel,
      );
      finishRequestAttempt(attempt, 499, Date.now() - segmentStartedAt(), childLog.usage);
      attemptRetained = true;
    };
    // The row is written from `logCtx`, which copies `childLog` only when the child commits. A
    // bridge child binds its usage later, at the terminal frame, so the binding is forwarded here
    // after that point. Left on `childLog`, the row would re-read the bridged wire instead of the
    // adapter's usage, and that wire has no providerCredits and a context-derived input count.
    // A binding that arrives before the commit waits for it, and a child that never commits
    // forwards nothing: both flags belong to this target only.
    let childCommitted = false;
    let childUsageBound = false;
    const forwardChildUsage = (): void => {
      if (!childCommitted || !childUsageBound) return;
      logCtx.usageFromBridge = true;
      if (childLog.usage) logCtx.usage = childLog.usage;
      if (isPausedTurn(childLog)) rememberPausedTurn(logCtx);
    };
    const completedTarget = { provider: pick.target.provider, model: pick.target.model };
    const writerGeneration = pick.writerGeneration;
    const servingPick = pick;
    let comboSuccessSettled = false;
    const settleServingSuccess = (): void => {
      if (comboSuccessSettled) return;
      comboSuccessSettled = true;
      noteComboSuccess(comboId, combo, servingPick.target, writerGeneration);
      settleComboReprobeSuccess(servingPick);
    };
    let hostedWebSearchStream = false;
    let consumedChildFailure: ConsumedComboFailure | undefined;
    let preflightModelRefusal: CodexAccountModelRefusal | undefined;
    const callbackGate = createChildPassthroughCallbackGate({
      ...options,
      onResponseComplete: model => {
        if (isPausedTurn(childLog)) rememberPausedTurn(logCtx);
        if (hostedWebSearchStream) settleServingSuccess();
        // The live config can change while the child is streaming. Never retain credentials.
        const currentCombo = getCombo(config, comboId);
        const provider = config.providers[completedTarget.provider];
        if (!options.compactionRoutingOverride && !options.mainHardLockFallbackOverride
          && Object.hasOwn(config.providers, completedTarget.provider)
          && provider && provider.disabled !== true
          && currentCombo?.targets.some(target => targetKey(target) === targetKey(completedTarget))) {
          rememberComboForLane(
            sessionLaneIdFromRequest(req.headers), comboId, completedTarget, model, writerGeneration,
            jevEffortApplies ? turnEffort : undefined,
          );
          // A failed effort decision only refreshes the live pin, which another turn may have updated.
          jevPin?.complete(targetKey(completedTarget), failedPinEffortDecision ? undefined : initialJevDecision, writerGeneration);
        }
        options.onResponseComplete?.(model);
      },
      onNativePassthroughTerminal: status => {
        // A committed stream can acquire terminal metadata after preflight copied
        // the child log. Publish it before the outer logger finalizes, but only
        // through the gate: discarded attempts must never affect the parent.
        // Undefined child fields must preserve metadata already inspected by WS.
        if (childLog.terminalHttpStatus !== undefined) logCtx.terminalHttpStatus = childLog.terminalHttpStatus;
        if (childLog.terminalIncompleteReason !== undefined) logCtx.terminalIncompleteReason = childLog.terminalIncompleteReason;
        if (childLog.committedIncompleteReason !== undefined) logCtx.committedIncompleteReason = childLog.committedIncompleteReason;
        if (childLog.terminalErrorCode !== undefined) logCtx.terminalErrorCode = childLog.terminalErrorCode;
        if (childLog.observedTerminalStatus !== undefined) logCtx.observedTerminalStatus = childLog.observedTerminalStatus;
        if (childLog.upstreamError !== undefined) logCtx.upstreamError = childLog.upstreamError;
        // Raw usage may arrive after the commit copy. Publish it before spend is finalized.
        if (childLog.usage !== undefined) {
          logCtx.usage = childLog.usage;
          logCtx.usageWireParsed = childLog.usageWireParsed;
        }
        if (isPausedTurn(childLog)) rememberPausedTurn(logCtx);
        // A committed stream that ends failed is a target failure too; incomplete is an answer.
        if (status === "failed") jevPin?.forget();
        else settleServingSuccess();
        options.onNativePassthroughTerminal?.(status);
      },
    });
    let response: Response;
    try {
      const currentTargetProvider = pick.target.provider;
      const remainingTargets = combo.strategy === "jev"
        ? combo.targets.filter(target => !pick!.attempted.includes(targetKey(target)))
        : combo.targets.slice(pick.targetIndex + 1);
      const deferCodexResetDerivedCooldown = (combo.strategy === "failover" || combo.strategy === "jev")
        && remainingTargets.some(target =>
          target.provider === currentTargetProvider
          && targetEligible(target)
          && !isComboTargetInCooldown(comboId, target),
        );
      const nativeChild = protocolLanes?.nativeChild(pick.target, targetRoute, targetSendBudget, turnEffort, jevEffortApplies);
      response = nativeChild ? await dispatchNativeComboChild({
        source: options.protocolSource!,
        plan: nativeChild,
        comboDispatchPermit: hopDecision?.allowed ? hopDecision.permit : undefined,
        logCtx,
        childLog,
        attempt,
        startedAt: started,
        ...(options.turnAdmissionLease ? { turnAdmissionLease: options.turnAdmissionLease } : {}),
        // Attempt-relative TTFT, recorded here for the same reason as the bridge child below.
        onFirstOutput: () => {
          if (!sealedCredentialRefusals.has(attempt) && attempt.firstOutputMs === undefined) {
            attempt.firstOutputMs = Math.max(0, Date.now() - segmentStartedAt());
          }
          options.onFirstOutput?.();
        },
        callbacks: {
          onTerminal: callbackGate.onTerminal,
          onCancel: callbackGate.onCancel,
          onResponseComplete: callbackGate.onResponseComplete,
        },
      }) : await requestDispatchers.handleResponses(childRequest, config, childLog, {
        ...options,
        admissionScope: dispatchScope,
        plaintextV2Decision: strictReplay,
        replayPrincipal,
        // A bridge child is a concrete route; the native source belongs to this loop only.
        ...(options.protocolSource ? { protocolSource: undefined } : {}),
        // After the spread: the child must run on THIS target's ladder, not on the holder the
        // parent arrived with.
        sendBudget: targetSendBudget,
        comboAttempt: true,
        comboVisionSidecar,
        ...(omittingImages ? { comboOmitImages: true }
          : capability.requiresVisionPlan(pick.target) ? { comboRequiresVisionPlan: true } : {}),
        ...(capability.unservable === "context" ? { comboContextDegraded: true } : {}),
        comboInitialSend: initialSend,
        comboDispatchPermit: hopDecision?.allowed ? hopDecision.permit : undefined,
        comboReplaySnapshot,
        deferCodexResetDerivedCooldown,
        onBridgeUsageBound: () => {
          childUsageBound = true;
          forwardChildUsage();
        },
        onHostedWebSearchStream: () => { hostedWebSearchStream = true; },
        onWebSearchLocalFailure: () => {
          if (childCommitted) carryLocalFailureState(childLog, logCtx);
        },
        // Attempt-relative TTFT is recorded HERE (not via childLog.firstOutputMs — a later
        // Object.assign(logCtx, childLog) would overwrite the request-relative value).
        onFirstOutput: () => {
          if (!sealedCredentialRefusals.has(attempt) && attempt.firstOutputMs === undefined) {
            attempt.firstOutputMs = Math.max(0, Date.now() - segmentStartedAt());
          }
          options.onFirstOutput?.();
        },
        onCodexAuthContextResolved: value => { resolvedAuth = value; },
        setTerminalOutcomeRecorder: value => { terminalRecorder = value; },
        onConsumedComboFailure: value => { consumedChildFailure = value; },
        onStoredPool401ReplayDispatched: () => { storedPool401ReplayDispatched = true; },
        onNativePassthroughTerminal: callbackGate.onTerminal,
        onNativePassthroughCancel: callbackGate.onCancel,
        onResponseComplete: callbackGate.onResponseComplete,
      });
      // Both lanes applied the initial choice before provider pins/caps; retain those transitions.
      restoreOriginalRequestedEffort(childLog, jevEffortApplies ? turnEffort?.effort : undefined);
    } catch (error) {
      callbackGate.discard();
      if (options.abortSignal?.aborted) {
        retainCancelledAttempt();
        return clientCancelledResponse();
      }
      jevPin?.forget();
      finishRequestAttempt(attempt, 502, Date.now() - segmentStartedAt(), childLog.usage);
      throw error;
    }

    if (options.abortSignal?.aborted) {
      callbackGate.discard();
      retainCancelledAttempt();
      return clientCancelledResponse();
    }

    // A native Chat child reports a pre-stream failure by status before any byte, so its body
    // is never peeked; a non-OK one takes the ordinary failure path below.
    if (response.ok && !runTurnAdapterSseResponses.has(response) && clientWireOf(response) === undefined) {
      const nativePassthrough = isNativePassthroughSseResponse(response);
      const eagerRelay = isEagerRelaySseResponse(response);
      let preflight;
      try {
        preflight = await preflightComboStreamResponse(response, childLog, undefined, {
          signal: options.abortSignal,
          requiredToolPrelude: childLog.providerAdapter === "openai-responses" && requiredToolContractOf(rawBody) !== undefined,
          degeneratePrelude: true,
        });
      } catch (error) {
        callbackGate.discard();
        if (options.abortSignal?.aborted) {
          retainCancelledAttempt();
          return clientCancelledResponse();
        }
        jevPin?.forget();
        finishRequestAttempt(attempt, 502, Date.now() - segmentStartedAt(), childLog.usage);
        throw error;
      }
      if (preflight.kind === "failed") {
        callbackGate.discard();
        terminalRecorder?.("failed", preflight.response.status);
        response = preflight.response;
        preflightModelRefusal = preflight.codexModelRefusal;
      } else {
        response = preflight.response;
        if (nativePassthrough) markNativePassthroughSseResponse(response);
        if (eagerRelay) markEagerRelaySseResponse(response);
      }
    }

    if (options.abortSignal?.aborted) {
      callbackGate.discard();
      await response.body?.cancel().catch(() => undefined);
      retainCancelledAttempt();
      return clientCancelledResponse();
    }

    if (response.ok) {
      sealRequestAttemptIdentity(
        attempt,
        childLog.provider,
        childLog.providerAdapter ?? attempt.adapter,
        childLog.accountLogLabel,
      );
      attemptRetained = true;
      // Native SSE can carry a failed verdict after HTTP acceptance, including after preflight.
      // A hosted web-search stream settles only when the loop reports a completed response.
      if (!isNativePassthroughSseResponse(response) && !hostedWebSearchStream) settleServingSuccess();
      carryProxyErrorContext(childLog, logCtx);
      Object.assign(logCtx, childLog, {
        client: logCtx.client,
        requestedModel: responseModel,
        model: responseModel,
        provider: "combo",
        comboId,
        comboTarget: pick.target,
        comboWriterGeneration: pick.writerGeneration,
        comboTargetOutputCeiling: targetOutputCeiling,
        routeDecision: logCtx.routeDecision,
        attempts: logCtx.attempts,
        activeAttempt: attempt,
        activeAttemptStartedAt: segmentStartedAt(),
        resolvedModel: childLog.resolvedModel ?? childLog.model,
      });
      carryLocalFailureState(childLog, logCtx);
      options.onCodexAuthContextResolved?.(resolvedAuth);
      options.setTerminalOutcomeRecorder?.((status, httpStatusOverride) => {
        if (isPausedTurn(childLog)) rememberPausedTurn(logCtx);
        if (status !== "failed" && !hostedWebSearchStream) settleServingSuccess();
        terminalRecorder?.(status, httpStatusOverride);
      });
      callbackGate.commit();
      childCommitted = true;
      forwardChildUsage();
      return response;
    }

    callbackGate.discard();
    if (response.status === 499) {
      retainCancelledAttempt();
      return clientCancelledResponse();
    }
    let failure: ConsumedComboFailure;
    try {
      failure = consumedChildFailure
        ?? await consumeComboFailure(response, options.abortSignal, Date.now(), childLog);
      if (hasProxyErrorMessage(childLog, failure.upstreamMessage ?? "", { type: failure.upstreamType, code: failure.upstreamCode })) markProxyError(failure.response);
      if (preflightModelRefusal !== undefined) failure = { ...failure, codexModelRefusal: preflightModelRefusal };
    } catch (error) {
      if (options.abortSignal?.aborted) {
        retainCancelledAttempt();
        return clientCancelledResponse();
      }
      jevPin?.forget();
      finishRequestAttempt(attempt, 502, Date.now() - segmentStartedAt(), childLog.usage);
      throw error;
    }
    if (options.abortSignal?.aborted) {
      retainCancelledAttempt();
      return clientCancelledResponse();
    }
    // A member's local late-attribution refusal reaches the client only as the literal constant
    // envelope: swap the response, keep every classification input, and skip the overflow rewrite.
    const lateAttributionRefusal = isLateAttributionRefusal(failure);
    if (lateAttributionRefusal) failure = { ...failure, response: lateAttributionLimitResponse() };
    sealRequestAttemptIdentity(
      attempt,
      childLog.provider,
      childLog.providerAdapter ?? attempt.adapter,
      childLog.accountLogLabel,
    );
    finishRequestAttempt(
      attempt,
      failure.response.status,
      Date.now() - segmentStartedAt(),
      failure.usage ?? childLog.usage,
    );
    const visionDescriptionRefused = isComboVisionDescriptionRefusal(failure.response);
    if (visionDescriptionRefused) visionRejectedTargets.add(targetKey(pick.target));
    const replayRefusal = isReplayRefusalResponse(failure.response);
    if (replayRefusal) {
      // Numeric 429 is a client replay policy here, not an upstream quota observation.
      childLog.causeHint = "transport-ambiguous";
      childLog.terminalSource = "synthetic";
      childLog.errorCode = UPSTREAM_RESET_REPLAY_REFUSED_CODE;
      if (!sealedCredentialRefusals.has(attempt)) attempt.errorCode = childLog.errorCode;
    }
    if (failure.upstreamCode === "input_admission_refused" && attempt.sendCount === 0) {
      attempt.errorCode = failure.upstreamCode;
      localAdmissionRefusals?.push(failure.upstreamMessage ?? "");
    } else {
      localAdmissionRefusals = undefined;
    }
    attemptRetained = true;
    lastFailure = failure.response;
    lastFailureUpstreamCode = failure.upstreamCode;
    toolChoiceRefusalsOnly = (toolChoiceRefusalsOnly ?? true) && isMandatoryToolChoiceRefusal(failure.response);
    const localDeadline = failure.response.status === 504 && upstreamErrorIsLocal(childLog);
    // A real target failure ends the session pin (#7525).
    if (!localDeadline) jevPin?.forget();
    if (!quotaFailure && !replayRefusal && (lastFailure.status === 429 || lastFailure.status === 402)) {
      quotaFailure = lastFailure;
      quotaFailedChildLog = childLog;
    }
    lastFailedChildLog = childLog;
    // The failed child's resolved destination, so the next hop compares physical targets.
    lastFailedTarget = { provider: targetRoute.providerName, model: targetRoute.modelId };
    lastFailedRetryAfter = failure.retryAfter;
    // A replacement that answers 200 is unmarked, and its zero-output failure only exists once
    // preflight has rebuilt the stream as a fresh Response. A spent grant never hops: a status the
    // client would resend becomes the refusal, and anything else reaches the client as it is.
    const spentReplacement = !failure.nonReplayable && comboSendScope?.ambiguousResendSpent === true;
    if (spentReplacement) {
      const settled = settleOperatorReplacement(failure.response);
      if (settled !== failure.response) {
        adoptFailedChildLog(childLog);
        return settled;
      }
    }
    // A non-replayable failure can come from a committed provider terminal or a send whose
    // outcome is ambiguous. Neither permits another target, regardless of the HTTP status.
    const failureDecision = failure.nonReplayable || spentReplacement
      ? "stop"
      : localDeadline || isPolicyCandidateRefusal(failure.response) ? "hop"
      : comboFailureDecision(failure.response.status, failure.classificationText, {
        code: failure.upstreamCode,
        rootCode: failure.upstreamRootCode,
        codexModelRefusal: failure.codexModelRefusal,
        verifiedPlanRefusal: failure.verifiedPlanRefusal,
        malformedResponseFormat: failure.malformedResponseFormat,
        openRouterOpaque400: failure.openRouterOpaque400,
        unofferedToolCallRefusal: failure.unofferedToolCallRefusal,
        providerModerationRefusal: failure.providerModerationRefusal,
        providerIntakeRefusal: failure.providerIntakeRefusal,
        // The adapter the failed leg actually resolved: a configured `kiro` provider can route a
        // model through another wire via `modelAdapters`, and an unresolved leg grants no hop.
        failedAdapter: childLog.providerAdapter,
      });
    const wantsStream = (rawBody as { stream?: unknown } | null)?.stream === true;
    // Local byte admission has its own diagnostic; do not relabel it as an upstream refusal.
    const classifyOverflow = failure.response.status === 413 && !lateAttributionRefusal
      && (wantsStream || (failure.upstreamCode !== "outbound_body_too_large"
        && failure.upstreamCode !== "translation_buffer_limit"));
    lastFailureClassifiesOverflow = classifyOverflow;
    if (storedPool401ReplayDispatched) {
      if (failureDecision === "hop" && unreadableEncryptedAgentTask && !comboPayloadReadable) {
        const recoveredTarget = await pickWithWait({
          exclude: pick.attempted,
          eligible: target => {
            if (!recoveryEligible(target)) return false;
            try {
              const route = routeConcreteModel(config, `${target.provider}/${target.model}`);
              return route.codexAccountMode === undefined
                && !isCanonicalOpenAiForwardProvider(route.provider);
            } catch {
              return false;
            }
          },
        });
        if (options.abortSignal?.aborted) return clientCancelledResponse();
        if (recoveredTarget && await recoverUnreadableEncryptedTask()) {
          pick = recoveredTarget;
          continue;
        }
        if (options.abortSignal?.aborted) return clientCancelledResponse();
      }
      // Keep the spent Pool budget sticky even after a recovered routed child:
      // no later failure may reopen ordinary combo/native account hopping.
      adoptFailedChildLog(childLog);
      if (classifyOverflow && failureDecision === "stop") {
        return wantsStream
          ? streamingContextOverflowResponse(responseModel, options.translatorBudget)
          : jsonContextOverflowResponse();
      }
      return lastFailure;
    }
    if (failureDecision === "stop") {
      adoptFailedChildLog(childLog);
      if (classifyOverflow) {
        return wantsStream
          ? streamingContextOverflowResponse(responseModel, options.translatorBudget)
          : jsonContextOverflowResponse();
      }
      return lastFailure;
    }
    const xaiPrivacyRefusal = isXaiPrivacyModeRefusal(failure.response);
    if (xaiPrivacyRefusal) xaiPrivacyFailure = { response: failure.response, childLog };
    // Retain a confirmed target context refusal when later retryable failures exhaust the ladder.
    // Hard stops above still return their own verdict, and every attempt keeps its own usage.
    if (!contextFailure && failure.response.status === 400 && isDefiniteContextOverflow(400, failure.classificationText)) {
      contextFailure = { childLog, response: formatErrorResponse(400, "invalid_request_error",
        failure.upstreamMessage ?? failure.classificationText, { code: "context_length_exceeded", classified: true }) };
    }
    if (failure.upstreamCode === "zero_output_token_limit") {
      zeroOutputLimitFailure = {
        childLog,
        usage: failure.usage ?? childLog.usage,
      };
    }
    // A bare status made a revoked credential read as a provider outage. Log the classified
    // condition (a closed member), never upstream-authored code or message text.
    const failureReason = localDeadline ? undefined : classifyUpstreamCondition({
      status: failure.response.status, code: failure.upstreamCode, type: failure.upstreamType, message: failure.upstreamMessage,
    });
    console.warn(
      `[combo] ${comboLogLabel(config, comboId)}: ${comboTargetLogLabel(config, comboId, pick.target)} failed with ${failure.response.status}`
        + ` after ${Date.now() - started}ms${failureReason ? `: ${failureReason}` : ""}`,
    );
    const failureNow = Date.now();
    const attemptedTargets = pick.attempted;
    // Legacy privacy mode is specific to the serving account.
    const failureCooldownScope = localDeadline || xaiPrivacyRefusal || isPolicyCandidateRefusal(failure.response) ? "none" : comboFailureCooldownScope(failure.response.status, failure.classificationText, {
      code: failure.upstreamCode,
      malformedResponseFormat: failure.malformedResponseFormat,
      openRouterOpaque400: failure.openRouterOpaque400,
      unofferedToolCallRefusal: failure.unofferedToolCallRefusal,
      providerModerationRefusal: failure.providerModerationRefusal,
    });
    const failedTargetKey = targetKey(pick.target);
    let failedTargetCooldownRecorded = false;
    // The dispatch rewrote this to name the pool account that actually served the turn.
    // The pool logs its main account under the bare provider name and carries "main" only as the
    // account label, which is stamped for pool and main-pool contexts alone (#8880).
    const poolAccountLabel = poolAccountProviderLabel(childLog.provider, pick.target.provider)
      ?? (childLog.accountLogLabel === "main" ? `${pick.target.provider}-main` : undefined);
    const failedAccount = failure.response.status === 402
      ? creditRefusedAnthropicAccountLabel(
        config, pick.target.provider, pick.target.model, poolAccountLabel, failure.classificationText, failure.upstreamCode,
        failure.response,
      )
      : cooledPoolAccountLabel(config, pick.target.provider, pick.target.model, poolAccountLabel)
      ?? (failure.response.status === 429 && failureCooldownScope === "target"
      ? cooledGenericOAuthAccountLabel(config, pick.target.provider, pick.target.model, childLog.accountLogLabel, failure.retryAfter)
      : undefined);
    // The target still cools on the pool's own refusal (the anti-hammer guard), but for the local
    // fallback rather than the pool's restated per-account Retry-After.
    const poolLocalRefusal = isAnthropicPoolLocalRefusal(
      config, pick.target.provider, failure.response.status, failedAccount, failureNow,
    );
    const codexLocalRefusal = isCodexAccountCooldownResponse(failure.response);
    const nextPick = advanceComboAfterFailure(config, pick, {
      retryAfter: poolLocalRefusal || codexLocalRefusal ? undefined : failure.retryAfter,
      resetAt: codexLocalRefusal ? undefined : failure.resetAt,
      cooldownMs: combo.cooldownMs,
      now: failureNow,
      recordFailure: !localDeadline, cooldownScope: failureCooldownScope,
      eligible: targetEligible,
      status: failure.response.status,
      code: failure.upstreamCode,
      message: failure.classificationText,
      failedAccount,
      onCooldownRecorded: target => {
        failedTargetCooldownRecorded ||= targetKey(target) === failedTargetKey;
      },
    });
    // A sibling cooldown is not this failure's write: stale-generation removal can
    // refuse recording even for a cooldown-producing classification. Require both.
    const failedTargetCooled = failureCooldownScope !== "none"
      && failedTargetCooldownRecorded
      && isComboTargetInCooldown(comboId, pick.target, failureNow);
    // Drop exclusions for the single-target retry, but wait for normal cooldown
    // expiry: an in-flight request cannot reserve a fresh recovery pass, though the
    // reservation it already owns still applies to entries unchanged since it was made.
    const carriedReprobe: ComboPick["cooldownReprobeTargets"] = pick.cooldownReprobeTargets;
    const retryAfterCooldown = (): Promise<ComboPick | null> =>
      pickWithWait({
        allowCooldownReprobe: false,
        cooldownReprobeTargets: carriedReprobe ? Object.entries(carriedReprobe) : undefined,
        eligible: targetEligible,
        now: failureNow,
      });
    if (nextPick) {
      pick = nextPick;
    } else {
      pick = await pickWithWait({
        exclude: pick.attempted,
        eligible: targetEligible,
        cooldownReprobeTargets: carriedReprobe ? Object.entries(carriedReprobe) : undefined,
        now: failureNow,
      });
      // A single-target combo with waitForCooldownMs has no alternate target to fail over to,
      // but can recover if it waits for its brief cooldown. The initial attempt accumulated into
      // pick.attempted, so the first pickWithWait above excluded it. retryAfterCooldown below is
      // the same selector with `exclude` deliberately dropped, so the single cooled target
      // becomes eligible again once its cooldown expires.
      // Termination is double-guarded:
      // 1) comboSendScope?.reserveDispatch refuses a second failover hop via comboExecutionBudgetPolicy
      //    (maxAlternateTargetSends: 1 for a single declared target).
      // 2) comboTargetsDispatched <= 1 bounds it locally so the retry never loops or waits unnecessarily
      //    even if sendBudget scope is absent.
      if (
        !pick
        && combo.targets.length === 1
        && combo.waitForCooldownMs > 0
        && comboTargetsDispatched <= 1
        && failedTargetCooled
        && !options.abortSignal?.aborted
      ) {
        pick = await retryAfterCooldown();
      }
    }
    if (!pick) {
      if (options.abortSignal?.aborted) return clientCancelledResponse();
      if (onlyReplayIncompatibleTargetsRemain(attemptedTargets)) {
        if (contextFailure || xaiPrivacyFailure) return exhaustedFailure();
        adoptFailedChildLog(childLog);
        return targetIncompatibleResponse();
      }
      if (unreadableEncryptedAgentTask && !comboPayloadReadable) {
        const recoveredTarget = await pickWithWait({
          exclude: attemptedTargets,
          eligible: recoveryEligible,
          cooldownReprobeTargets: carriedReprobe ? Object.entries(carriedReprobe) : undefined,
          now: failureNow,
        });
        if (recoveredTarget && await recoverUnreadableEncryptedTask()) {
          pick = recoveredTarget;
          continue;
        }
      }
      // Waiting or recovery may have observed cancellation after the check above.
      if (options.abortSignal?.aborted) return clientCancelledResponse();
      if (visionRejectedTargets.size > 0 && !omittingImages) {
        if (combo.onUnservable !== "reject") {
          // These children refused before sending the primary turn, so they can still serve it
          // with omission. Keep exclusions for every target that did attempt the primary turn.
          pick = await pickWithWait({
            exclude: attemptedTargets.filter(key => !visionRejectedTargets.has(key)),
            eligible: useImageDegradation,
            cooldownReprobeTargets: carriedReprobe ? Object.entries(carriedReprobe) : undefined,
          });
          if (options.abortSignal?.aborted) return clientCancelledResponse();
          if (pick) {
            omittingImages = true;
            warnComboImageOmission();
          }
        }
        if (!pick && visionDescriptionRefused) return unservableImageResponse();
      }
    }
    } finally {
      // External receipts make release a no-op after real work. runTurn owns its asynchronous
      // producer; core transfers cleanup there before returning a streaming response.
      if (!initialSend?.producerOwned) initialSend?.permit.release();
    }
  }
    const failure = exhaustedFailure(true);
  if (
    failure === lastFailure && lastFailure?.status === 413
    && lastFailureClassifiesOverflow
  ) {
    if (localAdmissionRefusals?.length) logCtx.errorCode = "input_admission_refused";
    const localMessage = localAdmissionRefusals?.length
      ? `opencodex refused this turn locally; nothing was sent upstream. No target of this combo `
        + `that was tried can fit its input: ${localAdmissionRefusals.join(" ")} Compact the conversation before retrying.`
      : undefined;
    return (rawBody as { stream?: unknown } | null)?.stream === true
      ? streamingContextOverflowResponse(responseModel, options.translatorBudget, localMessage)
      : jsonContextOverflowResponse(localMessage);
  }
  return failure;
}