@bitkyc08/opencodex 2.46.0 → 2.47.0

package/src/clients/config-export.ts

@@ -695,6 +695,7 @@ export interface PiProviderBlock {
   baseUrl: string;
   api: string;
   apiKey: string;
+  compat?: { sendSessionAffinityHeaders: boolean };
   models: PiModelEntry[];
 }
 
@@ -816,7 +817,7 @@ export interface GajaeGeneratedConfig {
  * model. The rest of this contract (omitting `cost`) is still ours rather than
  * a claim about Pi's acceptance.
  */
-function buildPiClientConfig(ctx: ExportContext): PiGeneratedConfig {
+function buildPiClientConfig(ctx: ExportContext, sendSessionAffinityHeaders = false): PiGeneratedConfig {
   const models: PiModelEntry[] = [];
   for (const model of normalizeExportModels(ctx.models)) {
     // Text is the one modality every routed model supports; anything richer must come
@@ -859,6 +860,7 @@ function buildPiClientConfig(ctx: ExportContext): PiGeneratedConfig {
         baseUrl: ctx.baseUrl,
         api: PI_API_DIALECT,
         apiKey: LOOPBACK_API_KEY_PLACEHOLDER,
+        ...(sendSessionAffinityHeaders ? { compat: { sendSessionAffinityHeaders: true } } : {}),
         models,
       },
     },
@@ -1031,7 +1033,7 @@ function buildOpencodeContribution(ctx: ExportContext): ManagedContribution {
 }
 
 function buildPiContribution(ctx: ExportContext): ManagedContribution {
-  const doc = buildPiClientConfig(ctx);
+  const doc = buildPiClientConfig(ctx, true);
   return singleFragment("pi", ["providers", OPENCODE_PROVIDER_ID], doc.providers[OPENCODE_PROVIDER_ID]);
 }
 
@@ -1127,7 +1129,7 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     destination: env => piConfigPath(env),
     apiKeyEnv: "",
     exportHint: "Pi reads a non-secret placeholder from models.json; loopback needs no key.",
-    build: buildPiClientConfig,
+    build: ctx => buildPiClientConfig(ctx, true),
     format: "json",
     summarize: summarizePi,
     buildContribution: buildPiContribution,

package/src/codex/auth-api.ts

@@ -1835,6 +1835,42 @@ export async function listCodexAuthAccountsSnapshot(
   };
 }
 
+/** One opted-in account's metadata; reuse the bounded WHAM 401 recovery and generation fence. */
+export async function refreshCodexQuotaForActivation(config: OcxConfig, accountId: string): Promise<void> {
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) {
+    const lease = tryAcquireNativeMainProfileClaim();
+    if (!lease) return;
+    try {
+      reconcileMainCodexAccountRuntimeState();
+      if (isAccountNeedsReauth(accountId)) return;
+      const identityGeneration = captureMainAccountIdentityGeneration();
+      const writerGeneration = captureConfigGeneration();
+      try {
+        // Refresh may need an exclusive claim; prepare before WHAM takes its shared claim.
+        if (!await getValidMainAccountToken({ preserveReauth: true })) return;
+      } catch (error) {
+        if (error instanceof MainAccountTokenRefreshError && error.reason === "reauth"
+          && isMainAccountIdentityGenerationLive(identityGeneration)) {
+          markAccountNeedsReauth(accountId, writerGeneration);
+        }
+        return;
+      }
+      if (isAccountNeedsReauth(accountId)) return;
+      await fetchMainAccountInfoAttempt(true, 1, lease, false, false);
+    } finally {
+      lease.release();
+    }
+    return;
+  }
+  const account = configuredPoolAccount(config, accountId);
+  if (!account) return;
+  const writerGeneration = captureConfigGeneration();
+  const result = await fetchPoolAccountQuota(accountId, true, account.plan);
+  if (result.needsReauth && result.credentialGeneration !== undefined) {
+    markAccountNeedsReauth(accountId, writerGeneration, result.credentialGeneration);
+  }
+}
+
 export async function listCodexAuthAccounts(config: OcxConfig, forceRefresh = false): Promise<CodexAuthAccountDto[]> {
   return (await listCodexAuthAccountsSnapshot(config, forceRefresh)).accounts;
 }

package/src/codex/catalog/provider-fetch.ts

@@ -1335,7 +1335,8 @@ function modelInputModalities(
     item.input_modalities
       ?? item.modalities
       ?? metadata?.input_modalities
-      ?? capabilityRecord?.input_modalities,
+      ?? capabilityRecord?.input_modalities
+      ?? plainRecord(item.architecture)?.input_modalities,
     8,
     24,
   )?.filter(value => (

package/src/codex/quota-auto-refresh-state.ts

@@ -4,13 +4,21 @@ export type CodexQuotaAutoRefreshWindows = { fiveHour?: number; weekly?: number
 
 export const completedByAccount = new Map<string, CodexQuotaAutoRefreshWindows>();
 export const retryAfterByAccount = new Map<string, number>();
+export const scheduledByAccount = new Map<string, CodexQuotaAutoRefreshWindows>();
+export const quotaRefreshAfterByAccount = new Map<string, number>();
 
+/** Drop every activation record when its account is removed. */
 export function forgetCodexQuotaAutoRefreshAccount(accountId: string): void {
   completedByAccount.delete(accountId);
   retryAfterByAccount.delete(accountId);
+  scheduledByAccount.delete(accountId);
+  quotaRefreshAfterByAccount.delete(accountId);
 }
 
+/** Clear the dependency-free activation bookkeeping for isolated tests. */
 export function resetCodexQuotaAutoRefreshStateForTests(): void {
   completedByAccount.clear();
   retryAfterByAccount.clear();
+  scheduledByAccount.clear();
+  quotaRefreshAfterByAccount.clear();
 }

package/src/codex/quota-auto-refresh.ts

@@ -1,5 +1,5 @@
 import { mutatePersistedConfig } from "../config";
-import { registerStateSweepAfterTick } from "../lib/state-store-sweeper";
+import { captureConfigGeneration, registerStateSweepAfterTick } from "../lib/state-store-sweeper";
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { normalizeResetAt } from "../providers/quota-wire";
 import { providerCodexAccountMode } from "../providers/registry";
@@ -7,17 +7,20 @@ import type { OcxConfig } from "../types";
 import { isSelectableCodexPoolAccount } from "./account-id";
 import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
 import { isCodexAccountPaused } from "./account-pause";
-import { isAccountNeedsReauth } from "./account-runtime-state";
-import { getValidCodexToken } from "./account-store";
+import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
+import { getValidCodexToken, isCodexAccountGenerationLive } from "./account-store";
+import { codexAccountLogLabel } from "./account-label";
 import { getMainAccountToken, getValidMainAccountToken, MAIN_CODEX_ACCOUNT_ID } from "./main-account";
 import { isMainAccountHardLocked } from "./main-account-hard-lock";
 import { tryAcquireNativeMainProfileClaim } from "./native-main-admission";
 import { withNativeMainSharedClaim } from "./native-main-claim";
 import { resolveNativeProfileContext } from "./native-profile-store";
-import { getAccountQuota, type StoredAccountQuota } from "./quota";
-import { warmCodexAccount } from "./warmup";
+import { getMainQuotaCredentialGeneration, observeMainQuotaCredential } from "./main-account-cache";
+import { applyAccountQuotaFromUpstreamHeaders, getAccountQuota, type StoredAccountQuota } from "./quota";
+import { CodexWarmupError, codexWarmupFailureReason, warmCodexAccount } from "./warmup";
 import {
-  completedByAccount, retryAfterByAccount, resetCodexQuotaAutoRefreshStateForTests,
+  completedByAccount, retryAfterByAccount, scheduledByAccount, quotaRefreshAfterByAccount,
+  resetCodexQuotaAutoRefreshStateForTests,
   type CodexQuotaAutoRefreshWindows,
 } from "./quota-auto-refresh-state";
 export type { CodexQuotaAutoRefreshWindows } from "./quota-auto-refresh-state";
@@ -36,6 +39,7 @@ export interface CodexQuotaAutoRefreshStatus {
 
 export interface CodexQuotaAutoRefreshRunDeps {
   getQuota?: (accountId: string) => StoredAccountQuota | null;
+  refreshQuota?: (config: OcxConfig, accountId: string) => Promise<void>;
   /** Only false means skipped; existing void callbacks still report a successful warmup. */
   warmAccount?: (config: OcxConfig, accountId: string) => Promise<void | false>;
   persistCompleted?: (
@@ -47,6 +51,7 @@ export interface CodexQuotaAutoRefreshRunDeps {
 
 let inFlight: Promise<void> | null = null;
 
+/** Report upstream window availability separately from persisted spending intent. */
 export function codexQuotaAutoRefreshStatus(
   config: OcxConfig,
   accountId: string,
@@ -62,6 +67,7 @@ export function codexQuotaAutoRefreshStatus(
   };
 }
 
+/** Select retained, enabled boundaries newer than both durable and in-memory completions. */
 export function dueCodexQuotaAutoRefreshWindows(
   config: OcxConfig,
   accountId: string,
@@ -69,38 +75,110 @@ export function dueCodexQuotaAutoRefreshWindows(
   now: number,
   completed = completedByAccount.get(accountId),
 ): CodexQuotaAutoRefreshWindows | null {
-  if (!quota) return null;
   const saved = config.codexQuotaAutoRefresh?.[accountId];
+  const scheduled = scheduledByAccount.get(accountId) ?? (
+    saved?.nextFiveHourResetAt !== undefined || saved?.nextWeeklyResetAt !== undefined
+      ? { fiveHour: saved.nextFiveHourResetAt, weekly: saved.nextWeeklyResetAt } : undefined
+  );
   const due: CodexQuotaAutoRefreshWindows = {};
-  const shortResetAt = normalizeResetAt(quota.shortResetAt);
-  const weeklyResetAt = normalizeResetAt(quota.weeklyResetAt);
+  const shortResetAt = normalizeResetAt(scheduled ? scheduled.fiveHour : quota?.shortResetAt);
+  const weeklyResetAt = normalizeResetAt(scheduled ? scheduled.weekly : quota?.weeklyResetAt);
   if (saved?.fiveHour === true
-    && quota.shortWindowSeconds === FIVE_HOUR_WINDOW_SECONDS
+    && (scheduled?.fiveHour !== undefined || saved.nextFiveHourResetAt !== undefined
+      || quota?.shortWindowSeconds === FIVE_HOUR_WINDOW_SECONDS)
     && shortResetAt !== undefined
     && shortResetAt <= now
-    && normalizeResetAt(saved.lastFiveHourResetAt) !== shortResetAt
-    && normalizeResetAt(completed?.fiveHour) !== shortResetAt) {
+    && shortResetAt > (normalizeResetAt(saved.lastFiveHourResetAt) ?? -1)
+    && shortResetAt > (normalizeResetAt(completed?.fiveHour) ?? -1)) {
     due.fiveHour = shortResetAt;
   }
   if (saved?.weekly === true
     && weeklyResetAt !== undefined
     && weeklyResetAt <= now
-    && normalizeResetAt(saved.lastWeeklyResetAt) !== weeklyResetAt
-    && normalizeResetAt(completed?.weekly) !== weeklyResetAt) {
+    && weeklyResetAt > (normalizeResetAt(saved.lastWeeklyResetAt) ?? -1)
+    && weeklyResetAt > (normalizeResetAt(completed?.weekly) ?? -1)) {
     due.weekly = weeklyResetAt;
   }
   return due.fiveHour === undefined && due.weekly === undefined ? null : due;
 }
 
+/** Retain the earliest uncompleted observation, including across process restarts. */
+function rememberWindows(config: OcxConfig, accountId: string, quota: StoredAccountQuota | null): void {
+  const saved = config.codexQuotaAutoRefresh?.[accountId];
+  if (!saved) return;
+  const completed = completedByAccount.get(accountId);
+  const previous = scheduledByAccount.get(accountId) ?? {
+    fiveHour: normalizeResetAt(saved.nextFiveHourResetAt),
+    weekly: normalizeResetAt(saved.nextWeeklyResetAt),
+  };
+  const next: CodexQuotaAutoRefreshWindows = {};
+  for (const window of ["fiveHour", "weekly"] as const) {
+    if (!saved[window]) continue;
+    const done = normalizeResetAt(completed?.[window]
+      ?? (window === "fiveHour" ? saved.lastFiveHourResetAt : saved.lastWeeklyResetAt));
+    const observed = normalizeResetAt(window === "fiveHour"
+      ? quota?.shortWindowSeconds === FIVE_HOUR_WINDOW_SECONDS ? quota.shortResetAt : undefined
+      : quota?.weeklyResetAt);
+    const candidates = [normalizeResetAt(previous[window]), observed]
+      .filter((value): value is number => value !== undefined && (done === undefined || value > done));
+    if (candidates.length) next[window] = Math.min(...candidates);
+  }
+  scheduledByAccount.set(accountId, next);
+  if (normalizeResetAt(saved.nextFiveHourResetAt) === next.fiveHour
+    && normalizeResetAt(saved.nextWeeklyResetAt) === next.weekly) return;
+  try {
+    const outcome = mutatePersistedConfig(persisted => {
+      const current = persisted.codexQuotaAutoRefresh?.[accountId];
+      if (!current) return { changed: false, value: null };
+      const setting = { ...current };
+      // A settings change that raced this sweep remains authoritative.
+      delete setting.nextFiveHourResetAt;
+      delete setting.nextWeeklyResetAt;
+      if (current.fiveHour && next.fiveHour !== undefined) setting.nextFiveHourResetAt = next.fiveHour;
+      if (current.weekly && next.weekly !== undefined) setting.nextWeeklyResetAt = next.weekly;
+      persisted.codexQuotaAutoRefresh = { ...persisted.codexQuotaAutoRefresh, [accountId]: setting };
+      return { changed: true, value: setting };
+    });
+    if (outcome.status !== "unavailable" && outcome.value) {
+      config.codexQuotaAutoRefresh = { ...config.codexQuotaAutoRefresh, [accountId]: outcome.value };
+    }
+  } catch {
+    // Keep the in-memory deadline and retry its narrow persistence on the next tick.
+  }
+}
+
+/** Load metadata recovery only when an opted-in account actually needs a probe. */
+async function refreshQuota(config: OcxConfig, accountId: string): Promise<void> {
+  const { refreshCodexQuotaForActivation } = await import("./auth-api");
+  await refreshCodexQuotaForActivation(config, accountId);
+}
+
+/** Keep billable main-account work behind the current pause, reauth and hard-lock policy. */
 function mainWarmupRestricted(config: OcxConfig): boolean {
   return isMainAccountHardLocked(config)
     || isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
     || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
 }
 
+/** Warm the exact account and fence quota/reauth publication to the dispatched credential. */
 async function warmAccount(config: OcxConfig, accountId: string): Promise<void | false> {
+  const writerGeneration = captureConfigGeneration();
   if (accountId !== MAIN_CODEX_ACCOUNT_ID) {
-    await warmCodexAccount(await getValidCodexToken(accountId));
+    const token = await getValidCodexToken(accountId);
+    if (isCodexAccountPaused(config, accountId) || isAccountNeedsReauth(accountId)) return false;
+    try {
+      await warmCodexAccount({ ...token, onCompleted: headers => {
+        if (isCodexAccountGenerationLive(accountId, token.generation)) {
+          applyAccountQuotaFromUpstreamHeaders(accountId, headers, writerGeneration);
+        }
+      } });
+    } catch (error) {
+      if (error instanceof CodexWarmupError && error.status === 401) {
+        markAccountNeedsReauth(accountId, writerGeneration, token.generation);
+      }
+      throw error;
+    }
+    if (!isCodexAccountGenerationLive(accountId, token.generation)) return false;
     return;
   }
   const lease = tryAcquireNativeMainProfileClaim();
@@ -116,13 +194,36 @@ async function warmAccount(config: OcxConfig, accountId: string): Promise<void |
       if (!token || token.accessToken !== prepared.accessToken
         || token.chatgptAccountId !== prepared.chatgptAccountId) return false;
       if (mainWarmupRestricted(config)) return false;
-      await warmCodexAccount(token);
+      const writer = observeMainQuotaCredential(token.accessToken, token.chatgptAccountId);
+      const credentialGeneration = getMainQuotaCredentialGeneration();
+      const credentialStillLive = () => {
+        reconcileMainCodexAccountRuntimeState();
+        const current = getMainAccountToken();
+        return current?.accessToken === token.accessToken
+          && current.chatgptAccountId === token.chatgptAccountId
+          && getMainQuotaCredentialGeneration() === credentialGeneration;
+      };
+      try {
+        await warmCodexAccount({ ...token, onCompleted: headers => {
+          if (writer && credentialStillLive()) {
+            applyAccountQuotaFromUpstreamHeaders(accountId, headers, writerGeneration, writer);
+          }
+        } });
+      } catch (error) {
+        if (error instanceof CodexWarmupError && error.status === 401
+          && credentialStillLive()) {
+          markAccountNeedsReauth(accountId, writerGeneration);
+        }
+        throw error;
+      }
+      if (!credentialStillLive()) return false;
     });
   } finally {
     lease.release();
   }
 }
 
+/** Patch completion markers without replacing concurrent account-setting changes. */
 function persistCompleted(
   config: OcxConfig,
   accountId: string,
@@ -148,6 +249,7 @@ function persistCompleted(
   }
 }
 
+/** Retry failed marker persistence without sending another billable warmup. */
 function retryPendingMarkers(
   config: OcxConfig,
   persist: NonNullable<CodexQuotaAutoRefreshRunDeps["persistCompleted"]>,
@@ -163,6 +265,7 @@ function retryPendingMarkers(
   }
 }
 
+/** Coalesce sweeps, refresh stale metadata and activate due accounts with bounded concurrency. */
 export async function runCodexQuotaAutoRefresh(
   config: OcxConfig,
   now = Date.now(),
@@ -175,30 +278,55 @@ export async function runCodexQuotaAutoRefresh(
   const quotaFor = deps.getQuota ?? getAccountQuota;
   const warm = deps.warmAccount ?? warmAccount;
   const persist = deps.persistCompleted ?? persistCompleted;
+  const refresh = deps.refreshQuota ?? refreshQuota;
   inFlight = (async () => {
     retryPendingMarkers(config, persist);
     const accountIds = [
       MAIN_CODEX_ACCOUNT_ID,
       ...(config.codexAccounts ?? []).filter(isSelectableCodexPoolAccount).map(account => account.id),
     ];
-    const due = accountIds.flatMap(accountId => {
-      if (isCodexAccountPaused(config, accountId)
-        || isAccountNeedsReauth(accountId)
-        || (accountId === MAIN_CODEX_ACCOUNT_ID && isMainAccountHardLocked(config))
-        || (retryAfterByAccount.get(accountId) ?? 0) > now) return [];
-      const windows = dueCodexQuotaAutoRefreshWindows(config, accountId, quotaFor(accountId), now);
-      return windows ? [{ accountId, windows }] : [];
-    });
-    for (let index = 0; index < due.length; index += CONCURRENCY) {
-      await Promise.all(due.slice(index, index + CONCURRENCY).map(async ({ accountId, windows }) => {
+    /** Recheck spending authorization after asynchronous metadata work. */
+    const eligible = (accountId: string) => {
+      const setting = config.codexQuotaAutoRefresh?.[accountId];
+      const provider = config.providers[OPENAI_CODEX_PROVIDER_ID];
+      return provider?.disabled !== true && isCanonicalOpenAiForwardProvider(provider)
+        && providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, provider) === "pool"
+        && (accountId === MAIN_CODEX_ACCOUNT_ID || config.codexAccounts?.some(
+          account => account.id === accountId && isSelectableCodexPoolAccount(account)))
+        && (setting?.fiveHour === true || setting?.weekly === true)
+        && !isCodexAccountPaused(config, accountId) && !isAccountNeedsReauth(accountId)
+        && !(accountId === MAIN_CODEX_ACCOUNT_ID && isMainAccountHardLocked(config));
+    };
+    for (let index = 0; index < accountIds.length; index += CONCURRENCY) {
+      await Promise.all(accountIds.slice(index, index + CONCURRENCY).map(async accountId => {
+        if (!eligible(accountId)) return;
+        // Capture before WHAM can move an idle window's reset into the future.
+        rememberWindows(config, accountId, quotaFor(accountId));
+        const quota = quotaFor(accountId);
+        if ((!quota || now - quota.updatedAt >= RETRY_MS)
+          && (quotaRefreshAfterByAccount.get(accountId) ?? 0) <= now) {
+          quotaRefreshAfterByAccount.set(accountId, now + RETRY_MS);
+          try { await refresh(config, accountId); } catch { /* Retry metadata at the bounded cadence. */ }
+        }
+        if (!eligible(accountId)) return;
+        rememberWindows(config, accountId, quotaFor(accountId));
+        if ((retryAfterByAccount.get(accountId) ?? 0) > now) return;
+        const windows = dueCodexQuotaAutoRefreshWindows(config, accountId, quotaFor(accountId), now);
+        if (!windows) return;
         try {
           if (await warm(config, accountId) === false) return;
           retryAfterByAccount.delete(accountId);
           const completed = { ...completedByAccount.get(accountId), ...windows };
           completedByAccount.set(accountId, completed);
           persist(config, accountId, completed);
-        } catch {
+          rememberWindows(config, accountId, quotaFor(accountId));
+        } catch (error) {
           retryAfterByAccount.set(accountId, now + RETRY_MS);
+          const account = config.codexAccounts?.find(candidate => candidate.id === accountId);
+          const label = account ? codexAccountLogLabel(account) : "main";
+          console.warn(`[codex-quota-auto-refresh] ${label}: ${codexWarmupFailureReason(error)}; ${
+            isAccountNeedsReauth(accountId) ? "reauthentication required" : "retry in five minutes"
+          }`);
         }
       }));
     }
@@ -206,6 +334,7 @@ export async function runCodexQuotaAutoRefresh(
   return inFlight;
 }
 
+/** Attach activation to the shared minute sweep and return its owner-scoped cleanup. */
 export function registerCodexQuotaAutoRefreshWorker(config: OcxConfig): () => void {
   return registerStateSweepAfterTick({
     name: "codex-quota-auto-refresh",
@@ -213,6 +342,7 @@ export function registerCodexQuotaAutoRefreshWorker(config: OcxConfig): () => vo
   });
 }
 
+/** Clear scheduling and single-flight state between isolated test cases. */
 export function resetCodexQuotaAutoRefreshForTests(): void {
   inFlight = null;
   resetCodexQuotaAutoRefreshStateForTests();

package/src/codex/warmup.ts

@@ -22,6 +22,8 @@ export interface CodexWarmupOptions {
   chatgptAccountId: string;
   model?: string;
   timeoutMs?: number;
+  /** Publish quota headers only after a completed inference, never on a failed stream. */
+  onCompleted?: (headers: Headers) => void;
 }
 
 const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
@@ -213,6 +215,7 @@ async function drainWarmupSse(body: ReadableStream<Uint8Array>, signal: AbortSig
   }
 }
 
+/** Bound one inference attempt and publish metadata only after a successful terminal event. */
 async function tryWarmup(options: CodexWarmupOptions, model: string): Promise<void> {
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > MAX_TIMEOUT_MS) {
@@ -263,6 +266,8 @@ async function tryWarmup(options: CodexWarmupOptions, model: string): Promise<vo
 
     try {
       await drainWarmupSse(body, signal);
+      // Metadata publication must not turn completed inference into another billable retry.
+      try { options.onCompleted?.(res.headers); } catch { /* The caller can refresh metadata later. */ }
     } finally {
       try {
         void body.cancel().catch(() => {});

package/src/config/provider-validation.ts

@@ -4,7 +4,7 @@ import {
   isValidModelDiscoveryModelId,
   MODEL_DISCOVERY_MAX_MODELS,
 } from "../providers/model-discovery-limits";
-import { modelRecordValue } from "../reasoning-effort";
+import { isDeclaredReasoningEffort, modelRecordValue } from "../reasoning-effort";
 import {
   isWirePinnedModel,
   MODEL_ADAPTER_OVERRIDE_ALLOWED,
@@ -27,6 +27,75 @@ const REASONING_SUMMARY_DELIVERY_SET = new Set<string>(REASONING_SUMMARY_DELIVER
 const DISPLAY_NAME_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
 const MAX_MODEL_DISPLAY_NAME_LENGTH = 128;
 
+/** Operator pins share one strict boundary across config and management writes. */
+export function pinnedReasoningEffortConfigError(value: unknown, allowClear = false): string | null {
+  if (value === undefined || (allowClear && (value === null || value === ""))) return null;
+  return typeof value === "string" && isDeclaredReasoningEffort(value)
+    ? null : "pinnedReasoningEffort must be a declared reasoning effort";
+}
+
+export function modelPinnedEffortsConfigError(
+  value: unknown,
+  field = "modelPinnedEfforts",
+  allowTombstones = false,
+): string | null {
+  if (value === undefined || (allowTombstones && value === null)) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    return `${field} must be a plain object`;
+  }
+  const keys = new Set<string>();
+  for (const [key, effort] of Object.entries(value)) {
+    const normalized = key.trim();
+    if (!normalized || ["__proto__", "prototype", "constructor"].includes(normalized)) {
+      return `${field} keys must be nonblank model ids and must not be reserved object keys`;
+    }
+    if (keys.has(normalized)) return `${field} keys must be unique after trimming`;
+    keys.add(normalized);
+    if (allowTombstones && (effort === null || effort === "")) continue;
+    if (typeof effort !== "string" || !isDeclaredReasoningEffort(effort)) {
+      return `${field} values must be declared reasoning efforts`;
+    }
+  }
+  return null;
+}
+
+/** Apply a validated map patch; null clears the field, entry tombstones remove one key. */
+export function mergeModelPinnedEfforts(
+  current: Record<string, string> | undefined,
+  patch: unknown,
+): Record<string, string> | undefined {
+  if (patch === undefined) return current === undefined ? undefined : { ...current };
+  if (patch === null) return undefined;
+  const next = Object.fromEntries(Object.entries(current ?? {}).map(([key, value]) => [key.trim(), value]));
+  for (const [key, effort] of Object.entries(patch as Record<string, string | null>)) {
+    if (effort === null || effort === "") delete next[key.trim()];
+    else next[key.trim()] = effort;
+  }
+  return Object.keys(next).length ? next : undefined;
+}
+
+export function providerReasoningPinsConfigError(provider: Record<string, unknown>): string | null {
+  return pinnedReasoningEffortConfigError(provider.pinnedReasoningEffort)
+    ?? modelPinnedEffortsConfigError(provider.modelPinnedReasoningEfforts, "modelPinnedReasoningEfforts");
+}
+
+/** Validate only pin fields, including callers that bypass the whole-config schema. */
+export function configReasoningPinsConfigError(value: unknown): string | null {
+  if (!value || typeof value !== "object") return null;
+  const raw = value as Record<string, unknown>;
+  const globalError = modelPinnedEffortsConfigError(raw.modelPinnedEfforts);
+  if (globalError) return globalError;
+  if (raw.providers && typeof raw.providers === "object") {
+    for (const provider of Object.values(raw.providers)) {
+      if (!provider || typeof provider !== "object") continue;
+      const error = providerReasoningPinsConfigError(provider as Record<string, unknown>);
+      if (error) return error;
+    }
+  }
+  return null;
+}
+
 /** Validate a provider destination without coupling DTO callers to config persistence. */
 export function providerBaseUrlConfigError(baseUrl: string): string | null {
   try {