/**
 * Quota-aware subagent model fallback (issue #374).
 *
 * codex-rs spawns children with the agent-role TOML `model` pinned; when that model's
 * provider quota is exhausted the child fails immediately. This module rewrites thread_spawn
 * requests at the proxy choke point to the next healthy model in a configured fallback chain.
 */
import { existsSync, readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { hasOwnProvider } from "../config";
import { isRateLimitOrQuotaFailureMessage } from "../lib/errors";
import type { OcxParsedRequest, OcxConfig } from "../types";
import { slugsEquivalent } from "../providers/slug-codec";
import { CODEX_HOME, getCodexHome } from "./paths";
import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota";
import {
  canAcquireCodexQuotaProbeLease,
  canAcquireCodexQuotaScopeProbeLease,
  codexQuotaScopeForModel,
  computeCodexUsageScore,
  getCodexQuotaHealthSnapshot,
  getEffectiveActiveCodexAccountId,
  getPoolAccountPlan,
} from "./routing";
import {
  isCodexAccountUsable,
  type CodexAccountUsabilityOptions,
} from "./account-usability";
import { isCodexAccountPaused } from "./account-pause";
import { getEffectiveCodexAutoSwitchThreshold } from "./account-auto-switch";
import { slugEquals } from "../providers/slug-codec";
import { isThreadSpawnRequest } from "../server/effort-policy";
import { PROVIDER_REGISTRY } from "../providers/registry";
import {
  CODEX_FORWARD_BASE_URL,
  OPENAI_CODEX_PROVIDER_ID,
  isCanonicalOpenAiForwardProvider,
} from "../providers/openai-tiers";
import { routeModel, type RouteResult } from "../router";
import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
import { codexAccountNamespaceForModel } from "./account-namespace-match";
import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_MAIN_DRAIN_SENTINEL_MODELS } from "./catalog/native-models";
import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
import {
  getUpstreamHostHealth,
  normalizeUpstreamHostCircuitThreshold,
  upstreamHostHealthKey,
} from "./upstream-host-health";
export const DEFAULT_SUBAGENT_MODEL_FALLBACK_POLL_MS = 60_000;

const CODEX_FORWARD_ORIGIN = new URL(CODEX_FORWARD_BASE_URL).origin.toLowerCase();

type SubagentQuotaPrimeFn = (config: OcxConfig, reason: string) => Promise<void>;
/** Side-effect-free Pool account preview for one resolved fallback candidate. */
export type SubagentPoolAccountPreview = (
  modelId: string | undefined,
  now: number,
  modelEligibleAccountIds?: ReadonlySet<string>,
) => string | null;
export type SubagentModelEligibleAccountIds = (
  modelId: string | undefined,
) => ReadonlySet<string> | undefined;
/** Additional resolved routes that a restricted fallback caller has independently approved. */
export type SubagentFallbackRouteEligibility = (route: RouteResult) => boolean;
let subagentQuotaPrimeForTests: SubagentQuotaPrimeFn | null = null;
let quotaPrimeInFlight: Promise<void> | null = null;

type ModelHealth = {
  unavailableUntil: number;
  reason: string;
};

const modelHealth = new Map<string, ModelHealth>();
const quotaPrimedAt = new Map<string, number>();
const knownProviderIdSet = new Set(PROVIDER_REGISTRY.map(entry => entry.id.toLowerCase()));

function tryRouteFallbackModel(config: OcxConfig, model: string): RouteResult | null {
  try {
    return routeModel(config, model);
  } catch {
    return null;
  }
}

function isPoolCodexRoute(route: RouteResult): boolean {
  return route.codexAccountMode === "pool";
}

function healthKey(model: string, accountId: string | null, poolScoped: boolean): string {
  const scopedAccountId = poolScoped ? accountId : null;
  return `${scopedAccountId ?? "none"}::${model.toLowerCase()}`;
}

function isDisabledFallbackModel(model: string, config: OcxConfig): boolean {
  const disabled = config.disabledModels ?? [];
  if (disabled.length === 0) return false;
  if (!model.includes("/")) {
    return disabled.some(stored => stored === model || slugEquals(stored, "openai", model));
  }
  const slash = model.indexOf("/");
  const provider = model.slice(0, slash);
  const modelId = model.slice(slash + 1);
  if (codexAccountNamespaceForModel(config.codexAccountNamespaces, model)) {
    return disabled.some(stored =>
      stored === model
      || stored === modelId
      || slugEquals(stored, "openai", modelId)
    );
  }
  return disabled.some(stored => stored === model || slugEquals(stored, provider, modelId));
}

function pollIntervalMs(config: OcxConfig): number {
  const configured = config.subagentModelFallbackPollMs;
  if (typeof configured !== "number" || !Number.isFinite(configured) || configured < 1_000) {
    return DEFAULT_SUBAGENT_MODEL_FALLBACK_POLL_MS;
  }
  return configured;
}

function fallbackChainKey(model: string, namespaces: unknown): string {
  const selector = codexAccountNamespaceForModel(namespaces, model);
  if (!selector) return JSON.stringify(["model", model.toLowerCase()]);
  const slash = model.indexOf("/");
  // Selector keys are exact-case account boundaries. Keep that segment distinct while
  // retaining legacy case-insensitive de-duplication for the native model suffix.
  return JSON.stringify(["account", selector, model.slice(slash + 1).toLowerCase()]);
}

function normalizedChain(
  primary: string,
  config: OcxConfig,
  extra: readonly string[] = [],
  trailing: readonly string[] = [],
): string[] {
  const chain: string[] = [];
  const seen = new Set<string>();
  const push = (model: string | undefined) => {
    if (!model || model.trim() === "") return;
    const trimmed = model.trim();
    const key = fallbackChainKey(trimmed, config.codexAccountNamespaces);
    if (seen.has(key)) return;
    seen.add(key);
    chain.push(trimmed);
  };
  push(primary);
  for (const model of extra) push(model);
  for (const model of config.subagentModelFallback ?? []) push(model);
  for (const model of trailing) push(model);
  return chain;
}

export function buildSubagentModelChain(
  primary: string,
  config: OcxConfig,
  extraFallback: readonly string[] = [],
): string[] {
  return normalizedChain(primary, config, extraFallback);
}

function quotaThreshold(config: OcxConfig, accountId: string): number {
  const threshold = getEffectiveCodexAutoSwitchThreshold(config, accountId);
  return threshold > 0 ? threshold : Number.POSITIVE_INFINITY;
}

/**
 * The account routing would actually use, not just the persisted operator
 * selection: round-robin, fill-first, failover, and priority preemption all
 * move the cursor in memory only, so reading the raw field would check quota
 * against an account this request is not going to touch.
 */
function activeCodexAccountId(config: OcxConfig): string | null {
  return getEffectiveActiveCodexAccountId(config) ?? null;
}

/**
 * Resolve the account id used for pool-scoped quota/health checks.
 * Explicit `null` means the pre-fallback preview found no usable account — do not
 * substitute `activeCodexAccountId` (that active id may itself be unusable).
 */
function resolvePoolFallbackAccountId(
  config: OcxConfig,
  accountId?: string | null,
): string | null {
  if (typeof accountId === "string") return accountId;
  if (accountId === null) return null;
  return activeCodexAccountId(config);
}

function resolveRouteFallbackAccountId(
  route: RouteResult | null,
  config: OcxConfig,
  accountId?: string | null,
  now = Date.now(),
  poolAccountPreview?: SubagentPoolAccountPreview,
  modelEligibleAccountIds?: ReadonlySet<string>,
): string | null {
  if (route?.codexAccountId !== undefined) return route.codexAccountId;
  if (route && isPoolCodexRoute(route) && poolAccountPreview) {
    return poolAccountPreview(route.modelId, now, modelEligibleAccountIds);
  }
  return resolvePoolFallbackAccountId(config, accountId);
}

function isRoutableFallbackModel(model: string, config: OcxConfig): boolean {
  const slash = model.indexOf("/");
  if (slash > 0) {
    if (codexAccountNamespaceForModel(config.codexAccountNamespaces, model)) return true;
    const providerName = model.slice(0, slash);
    if (!hasOwnProvider(config.providers, providerName)) {
      // Allow well-known "vendor/model" ids (e.g. anthropic/claude-*) to flow as
      // raw model ids through the default provider, but reject stale/typo prefixes.
      return knownProviderIdSet.has(providerName.toLowerCase());
    }
    const provider = config.providers[providerName];
    if (provider?.disabled === true) return false;
  }
  return true;
}

export function isNativeModelQuotaExhausted(
  model: string,
  config: OcxConfig,
  accountId?: string | null,
  now = Date.now(),
): boolean {
  const route = tryRouteFallbackModel(config, model);
  if (!route || !isPoolCodexRoute(route)) return false;
  const resolvedAccountId = resolveRouteFallbackAccountId(route, config, accountId);
  if (!resolvedAccountId) return false;
  const quota = getAccountQuota(resolvedAccountId);
  // Subagent fallback reads the same score, so a stale terminal reading would push
  // subagents off a native model whose window has already reset. Thread the caller's clock
  // rather than letting the scorer read wall time - the two would silently diverge.
  const usage = computeCodexUsageScore(quota, getPoolAccountPlan(config, resolvedAccountId), now);
  if (usage >= CODEX_UNKNOWN_USAGE_SCORE) return false;
  return usage >= quotaThreshold(config, resolvedAccountId);
}

export function isModelHealthBlocked(
  model: string,
  config: OcxConfig,
  accountId?: string | null,
  now = Date.now(),
): boolean {
  const route = tryRouteFallbackModel(config, model);
  const poolScoped = !!route && isPoolCodexRoute(route);
  const health = modelHealth.get(
    healthKey(
      model,
      resolveRouteFallbackAccountId(route, config, accountId),
      poolScoped,
    ),
  );
  return !!health && health.unavailableUntil > now;
}

export function isSubagentModelUnavailable(
  model: string,
  config: OcxConfig,
  accountId?: string | null,
  now = Date.now(),
  accountUsabilityOptions?: CodexAccountUsabilityOptions,
  poolAccountPreview?: SubagentPoolAccountPreview,
  modelEligibleAccountIdsForModel?: SubagentModelEligibleAccountIds,
): boolean {
  if (isDisabledFallbackModel(model, config)) return true;
  if (!isRoutableFallbackModel(model, config)) return true;
  const route = tryRouteFallbackModel(config, model);
  if (!route || route.provider.disabled === true) return true;
  const modelEligibleAccountIds = modelEligibleAccountIdsForModel?.(route.modelId);
  const candidateAccountUsabilityOptions = modelEligibleAccountIds !== undefined
    ? {
        ...accountUsabilityOptions,
        modelEligibleAccountIds,
      }
    : accountUsabilityOptions;
  const resolvedAccountId = resolveRouteFallbackAccountId(
    route,
    config,
    accountId,
    now,
    poolAccountPreview,
    candidateAccountUsabilityOptions?.modelEligibleAccountIds,
  );
  const accountUnavailable = (
    candidateAccountId: string | null,
    usabilityOptions: CodexAccountUsabilityOptions | undefined,
    includeQuotaExhaustion: boolean,
  ): boolean => {
    if (isModelHealthBlocked(model, config, candidateAccountId, now)) return true;
    if (!isPoolCodexRoute(route)) return false;

    // Pool candidates need a usable account. Derive requirement from the resolved
    // route (canonical openai defaults to pool even when codexAccountMode is omitted).
    if (!candidateAccountId) return true;
    if (isCodexAccountPaused(config, candidateAccountId)) return true;
    if (!isCodexAccountUsable(config, candidateAccountId, usabilityOptions)) return true;
    if (route.codexAccountId !== undefined) {
      // An account-qualified route is pinned and cannot consume Pool's recovery-probe
      // escape hatch. Honor both account-wide and model-scoped cooldowns so fallback
      // advances instead of selecting a candidate that exact auth will reject.
      const quotaScope = codexQuotaScopeForModel(route.modelId);
      if (getCodexQuotaHealthSnapshot(candidateAccountId, quotaScope, now) !== null) return true;
    } else {
      const quotaScope = codexQuotaScopeForModel(route.modelId);
      const cooldown = getCodexQuotaHealthSnapshot(candidateAccountId, quotaScope, now);
      if (cooldown !== null) {
        const probeAvailable = cooldown.quotaScope
          ? canAcquireCodexQuotaScopeProbeLease(candidateAccountId, cooldown.quotaScope, now)
          : canAcquireCodexQuotaProbeLease(candidateAccountId, now);
        if (!probeAvailable) return true;
      }
    }
    if (
      !includeQuotaExhaustion
      || (
        candidateAccountId === MAIN_CODEX_ACCOUNT_ID
        && usabilityOptions?.nativeMainSelectionOnly === true
      )
    ) return false;
    return isNativeModelQuotaExhausted(model, config, candidateAccountId, now);
  };

  // Prefer a genuinely usable entitled pool account. Preview can deliberately return
  // the configured active account even when no selectable candidate exists, so a
  // null/main-only check is not enough to detect the temporary-drain case.
  if (!accountUnavailable(resolvedAccountId, candidateAccountUsabilityOptions, true)) return false;

  // During a temporary native-main drain, entitlement discovery excludes main to
  // preserve the credential fence. If no non-main candidate can serve an unqualified
  // gated model, retain main only as a read-free sentinel: final auth owns the atomic
  // claim and returns maintenance instead of letting a routed fallback bypass it.
  //
  // The predicate is its OWN set, not the account-gated one. The sentinel protects the atomic
  // main claim during a drain, which has nothing to do with entitlement; it read the gated set
  // only because the two happened to hold the same slugs. Ungating the flagships (2026-09-04)
  // would have flipped this false and let a drain silently rewrite the operator's configured
  // subagent model instead of reporting maintenance -- a different model answering than was
  // chosen. The set is explicit rather than every supported native, so gpt-5.5 and friends keep
  // their existing fall-back-and-answer behaviour.
  const preserveDrainingMainCandidate = route.codexAccountId === undefined
    && candidateAccountUsabilityOptions?.nativeMainSelectionOnly === true
    && NATIVE_MAIN_DRAIN_SENTINEL_MODELS.has(route.modelId);
  if (!preserveDrainingMainCandidate) return true;
  const drainingMainUsabilityOptions: CodexAccountUsabilityOptions = {
    ...candidateAccountUsabilityOptions,
    modelEligibleAccountIds: new Set([
      ...(modelEligibleAccountIds ?? []),
      MAIN_CODEX_ACCOUNT_ID,
    ]),
  };
  // Quota scoring main would lazily read the native credential/plan. Cached health,
  // pause, reauth, and cooldown state are safe; defer physical scoring to final auth.
  return accountUnavailable(MAIN_CODEX_ACCOUNT_ID, drainingMainUsabilityOptions, false);
}

export function selectAvailableSubagentModel(
  primary: string,
  config: OcxConfig,
  extraFallback: readonly string[] = [],
  accountId?: string | null,
  now = Date.now(),
  nativeFallbackOnly = false,
  accountUsabilityOptions?: CodexAccountUsabilityOptions,
  trailingFallback: readonly string[] = [],
  poolAccountPreview?: SubagentPoolAccountPreview,
  modelEligibleAccountIdsForModel?: SubagentModelEligibleAccountIds,
  resolvedChain?: readonly string[],
  restrictedRouteEligible?: SubagentFallbackRouteEligibility,
): { model: string; rewritten: boolean; skipped: string[] } {
  const chain = resolvedChain ?? normalizedChain(primary, config, extraFallback, trailingFallback);
  const skipped: string[] = [];
  for (const candidate of chain) {
    if (nativeFallbackOnly) {
      const route = tryRouteFallbackModel(config, candidate);
      if (
        !route
        || route.combo !== undefined
        || (
          !isCanonicalOpenAiForwardProvider(route.provider)
          && restrictedRouteEligible?.(route) !== true
        )
      ) {
        skipped.push(candidate);
        continue;
      }
    }
    if (isSubagentModelUnavailable(
      candidate,
      config,
      accountId,
      now,
      accountUsabilityOptions,
      poolAccountPreview,
      modelEligibleAccountIdsForModel,
    )) {
      skipped.push(candidate);
      continue;
    }
    return { model: candidate, rewritten: !slugsEquivalent(candidate, primary), skipped };
  }
  return { model: primary, rewritten: false, skipped };
}

export function noteSubagentModelFailure(
  model: string,
  message: string,
  config: OcxConfig,
  accountId?: string | null,
  now = Date.now(),
  ttlMs?: number,
): void {
  const interval = ttlMs ?? DEFAULT_SUBAGENT_MODEL_FALLBACK_POLL_MS;
  if (!isRateLimitOrQuotaFailureMessage(message)) return;
  const route = tryRouteFallbackModel(config, model);
  const poolScoped = !!route && isPoolCodexRoute(route);
  modelHealth.set(
    healthKey(
      model,
      resolveRouteFallbackAccountId(route, config, accountId),
      poolScoped,
    ),
    {
      unavailableUntil: now + interval,
      reason: "quota_exhausted",
    },
  );
  sweepExpiredOnWrite(now);
}

export function sweepExpiredSubagentModelHealth(now = Date.now()): number {
  let removed = 0;
  for (const [key, health] of modelHealth) {
    if (health.unavailableUntil > now) continue;
    modelHealth.delete(key);
    removed += 1;
  }
  return removed;
}

export function resetSubagentModelFallbackStateForTests(): void {
  modelHealth.clear();
  quotaPrimedAt.clear();
  quotaPrimeInFlight = null;
  subagentQuotaPrimeForTests = null;
}

/** Test-only: inject the quota prime implementation used by {@link maybePrimeSubagentQuota}. */
export function setSubagentQuotaPrimeForTests(fn: SubagentQuotaPrimeFn | null): void {
  subagentQuotaPrimeForTests = fn;
}

/** Test-only: inspect shared prime TTL / in-flight state. */
export function getSubagentQuotaPrimeStateForTests(): {
  primedAt: number;
  inFlight: boolean;
} {
  return {
    primedAt: quotaPrimedAt.get("global") ?? 0,
    inFlight: quotaPrimeInFlight !== null,
  };
}

function rewriteParsedModel(parsed: OcxParsedRequest, model: string): void {
  parsed.modelId = model;
  if (parsed._rawBody && typeof parsed._rawBody === "object") {
    (parsed._rawBody as { model?: string }).model = model;
  }
}

const TOML_MODEL = /^(model)\s*=\s*("(?:\\.|[^"\\])*")\s*$/;

function parseTomlQuotedString(raw: string): string {
  const trimmed = raw.trim();
  if ((trimmed.startsWith("\"") && trimmed.endsWith("\""))
    || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
    return trimmed.slice(1, -1).replace(/\\"/g, "\"");
  }
  return trimmed;
}

function readAgentModel(filePath: string): string | null {
  try {
    const content = readFileSync(filePath, "utf8");
    for (const line of content.split(/\r?\n/)) {
      const match = line.match(TOML_MODEL);
      if (!match) continue;
      const model = parseTomlQuotedString(match[2] ?? "");
      return model.trim() === "" ? null : model.trim();
    }
  } catch {
    return null;
  }
  return null;
}

export function readCodexAgentModel(role: string, codexHome = CODEX_HOME): string | null {
  const file = join(codexHome, "agents", `${role}.toml`);
  if (!existsSync(file)) return null;
  return readAgentModel(file);
}

export function resolveAgentModelFallbackForPrimary(
  primary: string,
  codexHome = CODEX_HOME,
  namespaces?: unknown,
): string[] {
  const merged: string[] = [];
  const seen = new Set<string>();
  const push = (model: string | null | undefined) => {
    if (!model || model.trim() === "") return;
    const trimmed = model.trim();
    // Match global-chain de-dupe: keep account-selector prefixes case-sensitive when
    // those selectors are configured, while ordinary provider/model ids stay case-insensitive.
    const key = fallbackChainKey(trimmed, namespaces);
    if (seen.has(key)) return;
    seen.add(key);
    merged.push(trimmed);
  };
  for (const role of listCodexAgentRoles(codexHome)) {
    const model = readCodexAgentModel(role, codexHome);
    if (!model || !slugsEquivalent(model, primary)) continue;
    for (const fallback of readCodexAgentModelFallback(role, codexHome)) push(fallback);
  }
  return merged;
}

function subagentQuotaPrimeBlockedByHostCircuit(config: OcxConfig): boolean {
  if (normalizeUpstreamHostCircuitThreshold(config.upstreamHostCircuitThreshold) === 0) return false;
  const key = upstreamHostHealthKey(OPENAI_CODEX_PROVIDER_ID, CODEX_FORWARD_ORIGIN);
  return getUpstreamHostHealth(key)?.cooldownUntil !== undefined;
}

/**
 * Per-primary-model fallback chains from opencodex config (#1190).
 *
 * Storing `model_fallback` inside `$CODEX_HOME/agents/*.toml` makes Codex >= 0.146
 * reject the whole role file as an unknown field. The config-keyed map is the
 * supported home for that metadata; keys match the requested primary model id,
 * using the same raw/encoded slug tolerance as the TOML role lookup.
 */
export function resolveConfiguredModelFallbackForPrimary(
  primary: string,
  config: OcxConfig,
): string[] {
  const byModel = config.subagentModelFallbackByModel;
  if (!byModel || typeof byModel !== "object") return [];
  const entries: string[] = [];
  const seen = new Set<string>();
  const push = (model: string) => {
    const trimmed = model.trim();
    if (trimmed === "") return;
    const key = fallbackChainKey(trimmed, config.codexAccountNamespaces);
    if (seen.has(key)) return;
    seen.add(key);
    entries.push(trimmed);
  };
  for (const [key, chain] of Object.entries(byModel)) {
    if (!slugsEquivalent(key, primary)) continue;
    for (const model of chain) push(model);
  }
  return entries;
}

/**
 * Best-effort quota refresh before subagent model selection.
 * Concurrent callers share one in-flight promise. The success TTL is updated only
 * after a successful refresh so failures remain retryable. Errors are swallowed so
 * spawn routing can continue. When the canonical ChatGPT origin is circuit-blocked,
 * cached quota is used instead of sending credential-bearing usage probes to the
 * same origin before the request's final host admission check.
 */
export function maybePrimeSubagentQuota(
  config: OcxConfig,
  now = Date.now(),
  options: { nativeMainReadsForbidden?: boolean } = {},
): Promise<void> {
  if (options.nativeMainReadsForbidden) return Promise.resolve();
  if (subagentQuotaPrimeBlockedByHostCircuit(config)) return Promise.resolve();
  if (quotaPrimeInFlight) return quotaPrimeInFlight;
  if (!shouldPrimeSubagentQuota(config, now)) return Promise.resolve();

  quotaPrimeInFlight = (async () => {
    try {
      // Re-check after claiming single-flight ownership so a circuit opened by
      // a concurrent request cannot race us into a fresh usage-probe pass.
      if (subagentQuotaPrimeBlockedByHostCircuit(config)) return;
      if (subagentQuotaPrimeForTests) {
        await subagentQuotaPrimeForTests(config, "subagent-spawn");
      } else {
        const { primeCodexPoolQuotas } = await import("./auth-api");
        await primeCodexPoolQuotas(config, "subagent-spawn");
      }
      quotaPrimedAt.set("global", Date.now());
    } catch {
      // Owning boundary: do not fail the spawn path when priming is unavailable.
      // Leave quotaPrimedAt untouched so a later spawn can retry.
    } finally {
      quotaPrimeInFlight = null;
    }
  })();
  return quotaPrimeInFlight;
}

export function recordSubagentQuotaFailureForThreadSpawn(
  headers: Headers,
  model: string,
  message: string | number,
  config: OcxConfig,
  accountId?: string | null,
  now = Date.now(),
): void {
  if (!isThreadSpawnRequest(headers)) return;
  noteSubagentModelFailure(model, String(message), config, accountId, now, pollIntervalMs(config));
}

export function applySubagentModelFallback(
  parsed: OcxParsedRequest,
  headers: Headers,
  config: OcxConfig,
  accountId?: string | null,
  now = Date.now(),
  nativeFallbackOnly = false,
  accountUsabilityOptions?: CodexAccountUsabilityOptions,
  poolAccountPreview?: SubagentPoolAccountPreview,
  modelEligibleAccountIdsForModel?: SubagentModelEligibleAccountIds,
  resolvedFallbackChain?: readonly string[] | null,
  restrictedRouteEligible?: SubagentFallbackRouteEligibility,
): { from?: string; to?: string; skipped?: string[] } | null {
  if (!isThreadSpawnRequest(headers)) return null;
  const fallbackChain = resolvedFallbackChain === undefined
    ? resolveSubagentFallbackChain(parsed, config)
    : resolvedFallbackChain;
  if (!fallbackChain) return null;
  const selection = selectAvailableSubagentModel(
    parsed.modelId,
    config,
    [],
    accountId,
    now,
    nativeFallbackOnly,
    accountUsabilityOptions,
    [],
    poolAccountPreview,
    modelEligibleAccountIdsForModel,
    fallbackChain,
    restrictedRouteEligible,
  );
  if (!selection.rewritten) return selection.skipped.length > 0
    ? { from: parsed.modelId, to: parsed.modelId, skipped: selection.skipped }
    : null;
  const from = parsed.modelId;
  rewriteParsedModel(parsed, selection.model);
  return { from, to: selection.model, skipped: selection.skipped };
}

/** Resolve the effective fallback chain once for one logical spawn request. */
export function resolveSubagentFallbackChain(
  parsed: OcxParsedRequest,
  config: OcxConfig,
): readonly string[] | null {
  const tomlRoleFallback = resolveAgentModelFallbackForPrimary(
    parsed.modelId,
    getCodexHome(),
    config.codexAccountNamespaces,
  );
  // Config-keyed chains are the supported per-role home (#1190); TOML `model_fallback`
  // stays readable for backwards compatibility with homes written before Codex 0.146.
  const configuredFallback = resolveConfiguredModelFallbackForPrimary(parsed.modelId, config);
  const globalFallback = config.subagentModelFallback ?? [];
  if (globalFallback.length === 0 && configuredFallback.length === 0 && tomlRoleFallback.length === 0) return null;
  return normalizedChain(parsed.modelId, config, configuredFallback, tomlRoleFallback);
}

/** Whether the effective fallback chain crosses an account-gated native Pool model. */
export function subagentFallbackNeedsModelEntitlements(
  fallbackChain: readonly string[] | null,
  config: OcxConfig,
): boolean {
  return fallbackChain?.some((candidate) => {
    const route = tryRouteFallbackModel(config, candidate);
    return !!route
      && isPoolCodexRoute(route)
      && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(route.modelId);
  }) === true;
}

export function subagentFallbackGuidanceText(config: OcxConfig): string {
  const chain = config.subagentModelFallback ?? [];
  if (chain.length === 0) return "";
  const quoted = chain.map(model => `"${model}"`).join(", ");
  return ` Subagent model fallback chain (priority order): ${quoted}. When the primary model is quota-exhausted, opencodex rewrites thread_spawn requests to the next available model automatically.`;
}

const TOML_MODEL_FALLBACK_KEY = /^\s*(?:model_fallback|"model_fallback"|'model_fallback')\s*=/;

type TomlModelFallbackField = { present: false; value: null } | { present: true; value: string[] | null };

type TomlScanState = {
  inMultilineString: '"""' | "'''" | null;
  arrayDepth: number;
};

/** Track TOML strings, comments, and array brackets on one line. */
function scanTomlLine(line: string, state: TomlScanState): void {
  let i = 0;
  while (i < line.length) {
    const ch = line[i]!;
    if (ch === "#") return;
    if (ch === '"' || ch === "'") {
      const delimiter = ch.repeat(3);
      if (line.startsWith(delimiter, i)) {
        const end = findTomlMultilineStringEnd(line, i + 3, ch);
        if (end === -1) {
          state.inMultilineString = delimiter as '"""' | "'''";
          return;
        }
        i = end + 3;
        continue;
      }
      i++;
      while (i < line.length) {
        if (ch === '"' && line[i] === "\\") {
          i += 2;
          continue;
        }
        if (line[i] === ch) break;
        i++;
      }
      i++;
      continue;
    }
    if (ch === "[") state.arrayDepth++;
    else if (ch === "]") state.arrayDepth = Math.max(0, state.arrayDepth - 1);
    i++;
  }
}

/** Parse a TOML string starting at `start`; returns the decoded value and end offset. */
function parseTomlStringAt(text: string, start: number): { value: string; end: number } | null {
  const quote = text[start]!;
  const delimiter = quote.repeat(3);
  if (text.startsWith(delimiter, start)) {
    const end = findTomlMultilineStringEnd(text, start + 3, quote);
    if (end === -1) return null;
    let value = text.slice(start + 3, end).trim();
    if (quote === '"') value = value.replace(/\\"/g, '"').replace(/\\\\/g, "\\");
    return { value, end: end + 3 };
  }
  let i = start + 1;
  let value = "";
  while (i < text.length) {
    const ch = text[i]!;
    if (quote === '"' && ch === "\\") {
      const next = text[i + 1];
      if (next === '"' || next === "\\") {
        value += next;
        i += 2;
        continue;
      }
    }
    if (ch === quote) return { value, end: i + 1 };
    value += ch;
    i++;
  }
  return null;
}

function findTomlMultilineStringEnd(text: string, from: number, quote: string): number {
  const delimiter = quote.repeat(3);
  let index = text.indexOf(delimiter, from);
  while (index !== -1) {
    if (quote === "'") return index;
    let backslashes = 0;
    for (let j = index - 1; j >= 0 && text[j] === "\\"; j--) backslashes += 1;
    if (backslashes % 2 === 0) return index;
    index = text.indexOf(delimiter, index + 1);
  }
  return -1;
}

/** After an array close, only horizontal whitespace, an inline comment, or the line end is valid. */
function isValidTomlArrayTail(text: string, from: number): boolean {
  let i = from;
  while (i < text.length && (text[i] === " " || text[i] === "\t")) i += 1;
  if (i >= text.length || text[i] === "\n" || text[i] === "\r") return true;
  if (text[i] === "#") {
    while (i < text.length && text[i] !== "\n") i += 1;
    return true;
  }
  return false;
}

/** Parse a TOML string-array value; null when the value is not a well-formed array of strings. */
function parseTomlStringArrayValue(text: string): string[] | null {
  const values: string[] = [];
  let i = 0;
  const skipIgnored = () => {
    while (i < text.length) {
      const ch = text[i]!;
      if (ch === "#") {
        while (i < text.length && text[i] !== "\n") i += 1;
        continue;
      }
      if (/\s/.test(ch)) {
        i += 1;
        continue;
      }
      break;
    }
  };
  skipIgnored();
  if (text[i] !== "[") return null;
  i += 1;
  let expectValue = true;
  for (;;) {
    skipIgnored();
    if (i >= text.length) return null;
    const ch = text[i]!;
    if (ch === "]") {
      if (!isValidTomlArrayTail(text, i + 1)) return null;
      return values;
    }
    if (ch === ",") {
      if (expectValue) return null; // leading or doubled comma
      expectValue = true;
      i += 1;
      continue;
    }
    if (ch === '"' || ch === "'") {
      if (!expectValue) return null; // adjacent strings must be comma-separated
      const parsed = parseTomlStringAt(text, i);
      if (!parsed) return null;
      values.push(parsed.value);
      i = parsed.end;
      expectValue = false;
      continue;
    }
    return null;
  }
}

/**
 * TOML-aware, presence-aware parse of the `model_fallback` field. Quoted keys
 * are recognized, and text inside strings (including multiline strings) is
 * never treated as a key. `present` is true whenever the key exists, even when
 * the value is not a readable string array; `value` is null in that case.
 */
function parseTomlModelFallbackField(content: string): TomlModelFallbackField {
  const lines = content.split(/\r?\n/);
  const state: TomlScanState = { inMultilineString: null, arrayDepth: 0 };
  for (let i = 0; i < lines.length; i += 1) {
    const line = lines[i]!;
    if (state.inMultilineString) {
      const end = findTomlMultilineStringEnd(line, 0, state.inMultilineString[0]!);
      if (end === -1) continue;
      state.inMultilineString = null;
      scanTomlLine(line.slice(end + 3), state);
      continue;
    }
    if (state.arrayDepth === 0) {
      const key = line.match(TOML_MODEL_FALLBACK_KEY);
      if (key) {
        const rest = `${line.slice(key[0].length)}\n${lines.slice(i + 1).join("\n")}`;
        return { present: true, value: parseTomlStringArrayValue(rest) };
      }
    }
    scanTomlLine(line, state);
  }
  return { present: false, value: null };
}

export function readAgentModelFallback(filePath: string): string[] | null {
  try {
    const content = readFileSync(filePath, "utf8");
    const parsed = parseTomlModelFallbackField(content);
    return parsed.present ? parsed.value : null;
  } catch {
    return null;
  }
}

export function readCodexAgentModelFallback(role: string, codexHome = CODEX_HOME): string[] {
  const file = join(codexHome, "agents", `${role}.toml`);
  if (!existsSync(file)) return [];
  return readAgentModelFallback(file) ?? [];
}

/**
 * True when the role TOML carries a `model_fallback` key, even an empty array.
 * Presence is what matters for the doctor scan: Codex >= 0.146 rejects the
 * field as unknown and skips the whole role regardless of its value. Uses the
 * same TOML-aware parse as the fallback-reading path, so quoted keys count and
 * text inside string literals does not.
 */
export function hasCodexAgentModelFallbackField(role: string, codexHome = CODEX_HOME): boolean {
  const file = join(codexHome, "agents", `${role}.toml`);
  if (!existsSync(file)) return false;
  try {
    const content = readFileSync(file, "utf8");
    return parseTomlModelFallbackField(content).present;
  } catch {
    return false;
  }
}

/** Roles whose TOML still carries `model_fallback`, including empty arrays. */
export function scanCodexAgentRolesWithTomlModelFallback(
  codexHome = CODEX_HOME,
  onListError?: (cause: unknown) => void,
): string[] {
  try {
    return listCodexAgentRoles(codexHome).filter(role => hasCodexAgentModelFallbackField(role, codexHome));
  } catch (cause) {
    onListError?.(cause);
    return [];
  }
}

const TOML_MODEL_KEY = /^\s*(?:model|"model"|'model')\s*=/;

/**
 * TOML-aware read of the root `model` pin, or null when there is none.
 *
 * Distinct from {@link readCodexAgentModel}, which matches one exact unindented double-quoted
 * line. That is fine for resolving a fallback chain opencodex itself wrote, but it is the wrong
 * question for a diagnostic: the file being judged was written by somebody else, so `model = 'x'`,
 * an indented key, or a trailing comment are all valid TOML that Codex honours and that a
 * stricter matcher would report as unpinned.
 *
 * It shares the scanner used for `model_fallback` for the reason that matters here: an imported
 * role file keeps its instructions in a multiline string, and that string contains the very words
 * this scan looks for. A line matcher would read a key out of prose.
 *
 * Table context is not tracked, matching the `model_fallback` parse. A `model` key under a later
 * table header would be read as the root pin; Codex role files are flat in practice, and for a
 * warning the conservative direction is to stay quiet.
 */
function parseTomlModelPin(content: string): string | null {
  const lines = content.split(/\r?\n/);
  const state: TomlScanState = { inMultilineString: null, arrayDepth: 0 };
  for (let i = 0; i < lines.length; i += 1) {
    const line = lines[i]!;
    if (state.inMultilineString) {
      const end = findTomlMultilineStringEnd(line, 0, state.inMultilineString[0]!);
      if (end === -1) continue;
      state.inMultilineString = null;
      scanTomlLine(line.slice(end + 3), state);
      continue;
    }
    if (state.arrayDepth === 0) {
      const key = line.match(TOML_MODEL_KEY);
      if (key) {
        const rest = `${line.slice(key[0].length)}\n${lines.slice(i + 1).join("\n")}`;
        let at = 0;
        while (at < rest.length && (rest[at] === " " || rest[at] === "\t")) at += 1;
        if (rest[at] !== '"' && rest[at] !== "'") return null;
        const value = parseTomlStringAt(rest, at)?.value.trim() ?? "";
        return value === "" ? null : value;
      }
    }
    scanTomlLine(line, state);
  }
  return null;
}

/** Filename prefix opencodex gives the Claude agents it generates. */
const OPENCODEX_DERIVED_ROLE_PREFIX = "ocx-";

/**
 * Body markers that survive the Codex desktop external-agent import.
 *
 * The import carries the generated Claude agent's instructions across, so both the provenance
 * marker and the routing directive end up inside the role TOML. `ocx-route:` is matched without
 * its `<!--` comment prefix on purpose: the same import text-replaces "Claude Code" with "Codex"
 * inside that body, so anything around the directive should be assumed rewritten.
 */
const OPENCODEX_DERIVED_ROLE_MARKERS = ["generated-by: opencodex", "ocx-route:"] as const;

/**
 * Roles that look opencodex-derived but pin no model, so Codex runs them on the parent model.
 *
 * opencodex does not write Codex role TOMLs. These arrive when the Codex desktop external-agent
 * import converts `~/.claude/agents/ocx-*.md` into `$CODEX_HOME/agents/ocx-*.toml`, dropping the
 * `model:` frontmatter because a `claude-ocx-native--` id is not a Codex model and keeping only the
 * instructions. The surviving `ocx-route` directive cannot make up the difference: it is honoured
 * only on the Claude `/v1/messages` path and is inert on `/v1/responses`. So the role file names
 * one model while every spawn runs on another, which is invisible until someone diffs
 * `session_meta.agent_role` against `turn_context.model` (#4790).
 *
 * Detection is a heuristic for a warning, deliberately not an ownership claim. Nothing here
 * authorizes writing to, repairing, or removing these files, and the marker-based ownership rules
 * that govern the files opencodex does write are unchanged.
 */
export function scanOpencodexDerivedCodexAgentRolesWithoutModelPin(
  codexHome = CODEX_HOME,
  onListError?: (cause: unknown) => void,
): string[] {
  const findings: string[] = [];
  let roles: string[];
  try {
    roles = listCodexAgentRoles(codexHome);
  } catch (cause) {
    onListError?.(cause);
    return [];
  }
  for (const role of roles) {
    let content: string;
    try {
      content = readFileSync(join(codexHome, "agents", `${role}.toml`), "utf8");
    } catch {
      // An unreadable file is not evidence of a missing pin.
      continue;
    }
    const derived = role.startsWith(OPENCODEX_DERIVED_ROLE_PREFIX)
      || OPENCODEX_DERIVED_ROLE_MARKERS.some(marker => content.includes(marker));
    if (!derived) continue;
    if (parseTomlModelPin(content) !== null) continue;
    findings.push(role);
  }
  return findings.sort();
}

export function listCodexAgentRoles(codexHome = CODEX_HOME): string[] {
  const dir = join(codexHome, "agents");
  if (!existsSync(dir)) return [];
  return readdirSync(dir)
    .filter(name => name.endsWith(".toml"))
    .map(name => name.slice(0, -".toml".length));
}

/** True when a new quota prime should start (no success within the poll interval). */
export function shouldPrimeSubagentQuota(config: OcxConfig, now = Date.now()): boolean {
  const last = quotaPrimedAt.get("global") ?? 0;
  return now - last >= pollIntervalMs(config);
}
