@iislee/opencodex 2.31.0 → 2.35.0

package/src/codex/subagent-model-fallback.ts

@@ -15,12 +15,12 @@ import { CODEX_HOME, getCodexHome } from "./paths";
 import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota";
 import {
   canAcquireCodexQuotaProbeLease,
+  canAcquireCodexQuotaScopeProbeLease,
   codexQuotaScopeForModel,
   computeCodexUsageScore,
   getCodexQuotaHealthSnapshot,
   getEffectiveActiveCodexAccountId,
   getPoolAccountPlan,
-  isCodexAccountInCooldown,
 } from "./routing";
 import {
   isCodexAccountUsable,
@@ -38,6 +38,7 @@ import {
 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 } from "./catalog/native-models";
 import {
   getUpstreamHostHealth,
   normalizeUpstreamHostCircuitThreshold,
@@ -48,6 +49,15 @@ 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;
 let subagentQuotaPrimeForTests: SubagentQuotaPrimeFn | null = null;
 let quotaPrimeInFlight: Promise<void> | null = null;
 
@@ -177,8 +187,15 @@ function resolveRouteFallbackAccountId(
   route: RouteResult | null,
   config: OcxConfig,
   accountId?: string | null,
+  now = Date.now(),
+  poolAccountPreview?: SubagentPoolAccountPreview,
+  modelEligibleAccountIds?: ReadonlySet<string>,
 ): string | null {
-  return route?.codexAccountId ?? resolvePoolFallbackAccountId(config, accountId);
+  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 {
@@ -237,33 +254,53 @@ export function isSubagentModelUnavailable(
   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;
-  if (isModelHealthBlocked(model, config, accountId, now)) return true;
+  const modelEligibleAccountIds = modelEligibleAccountIdsForModel?.(route.modelId);
+  const candidateAccountUsabilityOptions = modelEligibleAccountIds !== undefined
+    ? {
+        ...accountUsabilityOptions,
+        modelEligibleAccountIds,
+      }
+    : accountUsabilityOptions;
+  const resolvedAccountId = resolveRouteFallbackAccountId(
+    route,
+    config,
+    accountId,
+    now,
+    poolAccountPreview,
+    candidateAccountUsabilityOptions?.modelEligibleAccountIds,
+  );
+  if (isModelHealthBlocked(model, config, resolvedAccountId, 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).
-  const resolvedAccountId = resolveRouteFallbackAccountId(route, config, accountId);
   if (!resolvedAccountId) return true;
   if (isCodexAccountPaused(config, resolvedAccountId)) return true;
-  if (!isCodexAccountUsable(config, resolvedAccountId, accountUsabilityOptions)) return true;
+  if (!isCodexAccountUsable(config, resolvedAccountId, candidateAccountUsabilityOptions)) 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(resolvedAccountId, quotaScope, now) !== null) return true;
-  } else if (
-    isCodexAccountInCooldown(resolvedAccountId, now)
-    && !canAcquireCodexQuotaProbeLease(resolvedAccountId, now)
-  ) {
-    return true;
+  } else {
+    const quotaScope = codexQuotaScopeForModel(route.modelId);
+    const cooldown = getCodexQuotaHealthSnapshot(resolvedAccountId, quotaScope, now);
+    if (cooldown !== null) {
+      const probeAvailable = cooldown.quotaScope
+        ? canAcquireCodexQuotaScopeProbeLease(resolvedAccountId, cooldown.quotaScope, now)
+        : canAcquireCodexQuotaProbeLease(resolvedAccountId, now);
+      if (!probeAvailable) return true;
+    }
   }
-  return isNativeModelQuotaExhausted(model, config, accountId, now);
+  return isNativeModelQuotaExhausted(model, config, resolvedAccountId, now);
 }
 
 export function selectAvailableSubagentModel(
@@ -275,8 +312,11 @@ export function selectAvailableSubagentModel(
   nativeFallbackOnly = false,
   accountUsabilityOptions?: CodexAccountUsabilityOptions,
   trailingFallback: readonly string[] = [],
+  poolAccountPreview?: SubagentPoolAccountPreview,
+  modelEligibleAccountIdsForModel?: SubagentModelEligibleAccountIds,
+  resolvedChain?: readonly string[],
 ): { model: string; rewritten: boolean; skipped: string[] } {
-  const chain = normalizedChain(primary, config, extraFallback, trailingFallback);
+  const chain = resolvedChain ?? normalizedChain(primary, config, extraFallback, trailingFallback);
   const skipped: string[] = [];
   for (const candidate of chain) {
     if (nativeFallbackOnly) {
@@ -286,7 +326,15 @@ export function selectAvailableSubagentModel(
         continue;
       }
     }
-    if (isSubagentModelUnavailable(candidate, config, accountId, now, accountUsabilityOptions)) {
+    if (isSubagentModelUnavailable(
+      candidate,
+      config,
+      accountId,
+      now,
+      accountUsabilityOptions,
+      poolAccountPreview,
+      modelEligibleAccountIdsForModel,
+    )) {
       skipped.push(candidate);
       continue;
     }
@@ -515,27 +563,27 @@ export function applySubagentModelFallback(
   now = Date.now(),
   nativeFallbackOnly = false,
   accountUsabilityOptions?: CodexAccountUsabilityOptions,
+  poolAccountPreview?: SubagentPoolAccountPreview,
+  modelEligibleAccountIdsForModel?: SubagentModelEligibleAccountIds,
+  resolvedFallbackChain?: readonly string[] | null,
 ): { from?: string; to?: string; skipped?: string[] } | null {
   if (!isThreadSpawnRequest(headers)) return 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;
+  const fallbackChain = resolvedFallbackChain === undefined
+    ? resolveSubagentFallbackChain(parsed, config)
+    : resolvedFallbackChain;
+  if (!fallbackChain) return null;
   const selection = selectAvailableSubagentModel(
     parsed.modelId,
     config,
-    configuredFallback,
+    [],
     accountId,
     now,
     nativeFallbackOnly,
     accountUsabilityOptions,
-    tomlRoleFallback,
+    [],
+    poolAccountPreview,
+    modelEligibleAccountIdsForModel,
+    fallbackChain,
   );
   if (!selection.rewritten) return selection.skipped.length > 0
     ? { from: parsed.modelId, to: parsed.modelId, skipped: selection.skipped }
@@ -545,6 +593,37 @@ export function applySubagentModelFallback(
   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 "";

package/src/codex/transition-state.ts

@@ -10,7 +10,17 @@
  * Design record: devlog/_fin/260804_codex_write_substrate/005_contract.md §1.
  */
 import { randomUUID } from "node:crypto";
-import { chmodSync, lstatSync, realpathSync } from "node:fs";
+import {
+  chmodSync,
+  closeSync,
+  fsyncSync,
+  linkSync,
+  lstatSync,
+  openSync,
+  realpathSync,
+  unlinkSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
 
 import { Database } from "bun:sqlite";
 
@@ -38,7 +48,7 @@ import {
 } from "./user-identity";
 
 export const CODEX_COORDINATOR_SCHEMA_VERSION = 1;
-const DURABLE_HISTORY_STATUSES = new Set(["converged", "pending", "running", "blocked", "unknown"]);
+const DURABLE_HISTORY_STATUSES = new Set(["adoption-pending", "converged", "pending", "running", "blocked", "unknown"]);
 const DURABLE_HISTORY_REASONS = new Set([
   "db-busy",
   "permission",
@@ -66,7 +76,7 @@ const CREATE_TRANSITION_TABLE = `
     history_pending_rows INTEGER,
     history_backup_entries INTEGER,
     updated_at TEXT NOT NULL,
-    CHECK (history_status IN ('converged', 'pending', 'running', 'blocked', 'unknown')),
+    CHECK (history_status IN ('adoption-pending', 'converged', 'pending', 'running', 'blocked', 'unknown')),
     CHECK (history_reason IS NULL OR history_reason IN
       ('db-busy', 'permission', 'unreadable', 'schema', 'timeout',
        'shutdown-cancelled', 'worker-died', 'overtaken', 'record-write-failed')),
@@ -75,14 +85,20 @@ const CREATE_TRANSITION_TABLE = `
     CHECK ((native_generation = 0 AND current_tx_id IS NULL)
         OR (native_generation > 0 AND length(trim(current_tx_id)) > 0)),
     CHECK ((native_generation = 0
+            AND history_status = 'unknown'
             AND history_tx_id IS NULL
             AND history_direction IS NULL
             AND history_authority_snapshot_id IS NULL)
+        OR (native_generation = 0
+            AND history_status = 'adoption-pending'
+            AND length(trim(history_tx_id)) > 0
+            AND history_direction IS NOT NULL
+            AND length(trim(history_authority_snapshot_id)) > 0)
         OR (native_generation > 0
             AND history_tx_id = current_tx_id
             AND history_direction IS NOT NULL
             AND length(trim(history_authority_snapshot_id)) > 0)),
-    CHECK (native_generation > 0 OR
+    CHECK (native_generation > 0 OR history_status = 'adoption-pending' OR
       (history_status = 'unknown'
        AND history_reason IS NULL
        AND history_attempts = 0
@@ -100,6 +116,15 @@ const INITIALIZE_TRANSITION_ROW = `
     history_backup_entries, updated_at
   ) VALUES (1, 0, NULL, 'unknown', NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, ?)`;
 
+const INITIALIZE_ADOPTION_ROW = `
+  INSERT INTO codex_transition_state (
+    singleton, native_generation, current_tx_id,
+    history_status, history_reason, history_attempts,
+    history_next_retry_at, history_tx_id, history_direction,
+    history_authority_snapshot_id, history_pending_rows,
+    history_backup_entries, updated_at
+  ) VALUES (1, 0, NULL, 'adoption-pending', NULL, 0, NULL, ?, ?, ?, NULL, NULL, ?)`;
+
 const SELECT_TRANSITION_ROW = `
   SELECT native_generation, current_tx_id,
          history_status, history_reason, history_attempts,
@@ -210,8 +235,15 @@ function rowToState(row: TransitionRow | null): CodexTransitionState {
 
   const generation = row.native_generation;
   if (generation === 0) {
-    if (row.current_tx_id !== null || row.history_tx_id !== null
-      || row.history_direction !== null || row.history_authority_snapshot_id !== null) {
+    const ordinaryInitial = row.history_status === "unknown"
+      && row.history_tx_id === null
+      && row.history_direction === null
+      && row.history_authority_snapshot_id === null;
+    const adoptionInitial = row.history_status === "adoption-pending"
+      && Boolean(row.history_tx_id?.trim())
+      && (row.history_direction === "apply" || row.history_direction === "remove")
+      && Boolean(row.history_authority_snapshot_id?.trim());
+    if (row.current_tx_id !== null || (!ordinaryInitial && !adoptionInitial)) {
       throw new CodexCoordinatorTransactionError("The initial coordinator row contains transition metadata.");
     }
   } else if (!row.current_tx_id?.trim()
@@ -234,13 +266,82 @@ function rowToState(row: TransitionRow | null): CodexTransitionState {
     nativeGeneration: generation,
     currentTxId: row.current_tx_id,
     history,
-    historySchedule: generation === 0 ? null : {
+    historySchedule: generation === 0 && row.history_status !== "adoption-pending" ? null : {
       direction: row.history_direction as "apply" | "remove",
       authoritySnapshotId: row.history_authority_snapshot_id as string,
     },
   };
 }
 
+export type CodexCoordinatorAdoptionCheckpoint = "temp-created" | "temp-committed" | "published";
+
+export interface CodexCoordinatorAdoptionOptions {
+  readonly direction: "apply" | "remove";
+  readonly onCheckpoint?: (checkpoint: CodexCoordinatorAdoptionCheckpoint) => void;
+}
+
+function fsyncFile(path: string): void {
+  // Writable fd on purpose. Windows FlushFileBuffers needs GENERIC_WRITE;
+  // openSync(path, "r") is GENERIC_READ only and fails with EPERM (measured on
+  // Windows 11 25H2 / bun 1.3.14). prompt-journal.ts uses the same "r+" open.
+  const fd = openSync(path, "r+");
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function fsyncDir(path: string): void {
+  // POSIX directory fsync is O_RDONLY. O_RDWR ("r+") is EISDIR.
+  const fd = openSync(path, "r");
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function publishAdoptionDatabase(
+  finalDatabasePath: string,
+  options: CodexCoordinatorAdoptionOptions,
+): void {
+  const parent = dirname(finalDatabasePath);
+  const tempPath = join(parent, `.${basename(finalDatabasePath)}.adopt-${process.pid}-${randomUUID()}.tmp`);
+  let tempPresent = false;
+  try {
+    const fd = openSync(tempPath, "wx", 0o600);
+    closeSync(fd);
+    tempPresent = true;
+    options.onCheckpoint?.("temp-created");
+
+    const temp = new Database(tempPath, { readwrite: true, create: false });
+    try {
+      temp.exec("PRAGMA journal_mode = DELETE; BEGIN IMMEDIATE");
+      temp.exec(CREATE_TRANSITION_TABLE);
+      temp.query(INITIALIZE_ADOPTION_ROW).run(
+        randomUUID(),
+        options.direction,
+        randomUUID(),
+        new Date().toISOString(),
+      );
+      temp.exec(`PRAGMA user_version = ${CODEX_COORDINATOR_SCHEMA_VERSION}; COMMIT`);
+      readCodexCoordinatorState(temp);
+    } catch (error) {
+      try { temp.exec("ROLLBACK"); } catch { /* commit may already have completed */ }
+      throw error;
+    } finally {
+      temp.close();
+    }
+    fsyncFile(tempPath);
+    options.onCheckpoint?.("temp-committed");
+
+    linkSync(tempPath, finalDatabasePath);
+    options.onCheckpoint?.("published");
+    if (process.platform !== "win32") fsyncDir(parent);
+  } catch (error) {
+    if (errorCode(error) !== "EEXIST") throw error;
+  } finally {
+    if (tempPresent) {
+      try { unlinkSync(tempPath); } catch (error) {
+        if (errorCode(error) !== "ENOENT") throw error;
+      }
+    }
+  }
+}
+
 export function readCodexCoordinatorState(database: Database): CodexTransitionState {
   const row = database.query<TransitionRow, []>(SELECT_TRANSITION_ROW).get();
   return rowToState(row);
@@ -346,7 +447,10 @@ function createCapability(
   };
 }
 
-export function openCodexCoordinatorTransaction(finalDatabasePath: string): CodexCoordinatorTransactionController {
+export function openCodexCoordinatorTransaction(
+  finalDatabasePath: string,
+  adoption?: CodexCoordinatorAdoptionOptions,
+): CodexCoordinatorTransactionController {
   let database: Database | undefined;
   let transactionOpen = false;
   let closed = false;
@@ -389,6 +493,10 @@ export function openCodexCoordinatorTransaction(finalDatabasePath: string): Code
       if (errorCode(cause) !== "ENOENT") throw cause;
       databaseWasAbsent = true;
     }
+    if (databaseWasAbsent && adoption) {
+      publishAdoptionDatabase(finalDatabasePath, adoption);
+      databaseWasAbsent = false;
+    }
     database = new Database(finalDatabasePath, { create: true });
     if (databaseWasAbsent) {
       try { chmodSync(finalDatabasePath, 0o600); } catch { /* Windows applies ACLs in WP11. */ }

package/src/combos/failover.ts

@@ -109,6 +109,28 @@ export function clearComboTargetCooldowns(comboId?: string): void {
 
 export type ComboFailureDecision = "hop" | "stop";
 
+function isModelLifecycleGone(
+  status: number,
+  message: string,
+  code?: string | null,
+): boolean {
+  if (status !== 410) return false;
+  const normalizedCode = code?.trim().toLowerCase().replaceAll("-", "_");
+  if ([
+    "model_deprecated",
+    "model_end_of_life",
+    "model_eol",
+    "model_not_found",
+    "model_retired",
+  ].includes(normalizedCode ?? "")) return true;
+  const text = message.toLowerCase();
+  return /\bmodel\b/.test(text) && (
+    /\bend[ -]of[ -]life\b/.test(text)
+    || /\bno longer available\b/.test(text)
+    || /\b(?:deprecated|retired|retirement|sunset|decommissioned)\b/.test(text)
+  );
+}
+
 export function comboFailureDecision(
   status: number,
   message: string,
@@ -119,6 +141,11 @@ export function comboFailureDecision(
   // Cyber policy is a hard non-retryable refusal — honor structured code even when
   // classificationText was truncated before the JSON code field.
   if (isCyberPolicyCode(options?.code)) return "stop";
+  // HTTP 410 is normally terminal. A model-specific lifecycle verdict is target-local,
+  // however: another provider/model in the declared combo can still serve the request.
+  // Require structured lifecycle code or explicit model+lifecycle prose so unrelated
+  // application-level 410 responses remain fail-closed.
+  if (isModelLifecycleGone(status, message, options?.code)) return "hop";
   const error = classifyError(status, "upstream_error", message);
   if (isCyberPolicyCode(error.code)) return "stop";
   // A local input-admission refusal (#1524) says "this candidate cannot fit the request",

package/src/combos/types.ts

@@ -203,6 +203,16 @@ export function comboConfigIssues(
   }
 
   const body = raw as Record<string, unknown>;
+  if (typeof body.alias === "string") {
+    const alias = body.alias.toLowerCase();
+    for (const [providerName, provider] of Object.entries(providers)) {
+      if (provider.alias?.toLowerCase() === alias) {
+        issues.push({ path: ["alias"], message: `alias "${body.alias}" is already used by provider "${providerName}"` });
+      }
+      const model = Object.entries(provider.modelAliases ?? {}).find(([, value]) => value.toLowerCase() === alias);
+      if (model) issues.push({ path: ["alias"], message: `alias "${body.alias}" is already used by model "${providerName}/${model[0]}"` });
+    }
+  }
   if (body.strategy !== undefined
     && body.strategy !== "failover"
     && body.strategy !== "round-robin") {

package/src/compatibility/index.ts

@@ -0,0 +1,26 @@
+import { OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST } from "./openai-responses";
+import type { CompatibilityManifestV1 } from "./manifest";
+
+export {
+  COMPATIBILITY_DISPOSITIONS,
+  COMPATIBILITY_MANIFEST_SCHEMA_VERSION,
+  compatibilityManifestIssues,
+  defineCompatibilityManifest,
+} from "./manifest";
+export type {
+  CompatibilityClaimV1,
+  CompatibilityDisposition,
+  CompatibilityEvidenceKind,
+  CompatibilityEvidenceRefV1,
+  CompatibilityManifestV1,
+  CompatibilitySubjectV1,
+} from "./manifest";
+export { OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST } from "./openai-responses";
+
+export const COMPATIBILITY_MANIFESTS: readonly CompatibilityManifestV1[] = Object.freeze([
+  OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST,
+]);
+
+export function getCompatibilityManifest(id: string): CompatibilityManifestV1 | undefined {
+  return COMPATIBILITY_MANIFESTS.find(manifest => manifest.id === id);
+}