@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/codex/routing.ts

@@ -3,6 +3,7 @@ import { saveConfigPreservingClaudeCode } from "../config";
 import { isCodexAccountGenerationLive, readCodexAccountRecord } from "./account-store";
 import { codexAccountLogLabel } from "./account-label";
 import { isCodexAccountPaused } from "./account-pause";
+import { clearCodexAccountPin, codexAccountPriorityLookup, pinnedCodexAccountId } from "./account-priority";
 import { isCodexAccountUsable, type CodexAccountUsabilityOptions } from "./account-usability";
 import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
 import {
@@ -14,6 +15,7 @@ import {
   peekRoundRobinAccount,
   pickRoundRobinAccount,
   seedPoolRotationAccount,
+  selectPriorityTier,
 } from "./pool-rotation";
 import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota";
 import { MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan } from "./main-account";
@@ -904,7 +906,7 @@ function getEligiblePoolAccounts(
   now = Date.now(),
   quotaScope?: CodexQuotaScope,
   selectionOptions?: CodexAccountUsabilityOptions,
-): string[] {
+): readonly string[] {
   const ids = (config.codexAccounts ?? [])
     .filter(account => isSelectableCodexPoolAccount(account)
       && account.id !== excludeId
@@ -926,7 +928,15 @@ function getEligiblePoolAccounts(
   ) {
     ids.unshift(MAIN_CODEX_ACCOUNT_ID);
   }
-  return ids;
+  // Single choke point for selection order: every strategy, failover, and preview
+  // reaches the pool through here, so tiering applies once rather than per picker.
+  // Eligibility above is unchanged — this only narrows an already-eligible list.
+  return selectPriorityTier(
+    ids,
+    codexAccountPriorityLookup(config),
+    id => hasCodexQuotaHeadroom(config, id),
+    pinnedCodexAccountId(config),
+  );
 }
 
 function listEligibleCodexAccountIds(
@@ -934,7 +944,7 @@ function listEligibleCodexAccountIds(
   now: number,
   quotaScope?: CodexQuotaScope,
   selectionOptions?: CodexAccountUsabilityOptions,
-): string[] {
+): readonly string[] {
   return getEligiblePoolAccounts(config, undefined, now, quotaScope, selectionOptions);
 }
 
@@ -942,11 +952,20 @@ function stickyLimitForConfig(config: OcxConfig): number {
   return normalizeAccountPoolStickyLimit(config.accountPoolStickyLimit);
 }
 
-function isActiveUnderFillFirstThreshold(config: OcxConfig, accountId: string): boolean {
+/**
+ * Whether an account still has quota to give under the auto-switch threshold.
+ *
+ * Fill-first and the priority tier filter share this predicate, and share both of
+ * its escape hatches. A disabled threshold means only health, pause, and reauth
+ * may drain an account; unknown usage is a guess, so it must neither force
+ * fill-first off the active account nor drain a tier that was simply never
+ * primed. A genuinely exhausted account 429s into cooldown and leaves
+ * eligibility on its own.
+ */
+function hasCodexQuotaHeadroom(config: OcxConfig, accountId: string): boolean {
   const threshold = config.autoSwitchThreshold ?? 80;
   if (threshold <= 0) return true;
   const usage = computeCodexUsageScore(getAccountQuota(accountId), getPoolAccountPlan(config, accountId));
-  // Unknown usage must not force fill-first to abandon the active account.
   if (isUnknownUsage(usage)) return true;
   return usage < threshold;
 }
@@ -965,7 +984,7 @@ function pickFillFirstCodexAccount(
   if (eligible.length === 0) return null;
 
   const active = getEffectiveActiveCodexAccountId(config);
-  if (active && eligible.includes(active) && isActiveUnderFillFirstThreshold(config, active)) {
+  if (active && eligible.includes(active) && hasCodexQuotaHeadroom(config, active)) {
     return active;
   }
 
@@ -976,7 +995,7 @@ function pickFillFirstCodexAccount(
 function pickNextFillFirstCodexAccount(
   config: OcxConfig,
   afterId: string | null,
-  eligible = listEligibleCodexAccountIds(config, Date.now()),
+  eligible: readonly string[] = listEligibleCodexAccountIds(config, Date.now()),
   _now = Date.now(),
   selectionOptions?: CodexAccountUsabilityOptions,
 ): string | null {
@@ -985,7 +1004,7 @@ function pickNextFillFirstCodexAccount(
   if (!afterId) {
     // Prefer an under-threshold account when starting with no active cursor.
     for (const id of ordered) {
-      if (isActiveUnderFillFirstThreshold(config, id)) return id;
+      if (hasCodexQuotaHeadroom(config, id)) return id;
     }
     return ordered[0] ?? null;
   }
@@ -1000,7 +1019,7 @@ function pickNextFillFirstCodexAccount(
   const startIdx = stableAll.indexOf(afterId);
   if (startIdx < 0) {
     for (const id of ordered) {
-      if (isActiveUnderFillFirstThreshold(config, id)) return id;
+      if (hasCodexQuotaHeadroom(config, id)) return id;
     }
     return ordered[0] ?? null;
   }
@@ -1011,7 +1030,7 @@ function pickNextFillFirstCodexAccount(
     const candidate = stableAll[(startIdx + step) % stableAll.length]!;
     if (!eligible.includes(candidate)) continue;
     if (!fallback) fallback = candidate;
-    if (isActiveUnderFillFirstThreshold(config, candidate)) return candidate;
+    if (hasCodexQuotaHeadroom(config, candidate)) return candidate;
   }
   return fallback ?? ordered[0] ?? null;
 }
@@ -1097,16 +1116,11 @@ function pickLowerUsageAccount(
   return best;
 }
 
-export function pickLowestUsageCodexAccount(
-  config: OcxConfig,
-  excludeId?: string,
-  now = Date.now(),
-  quotaScope?: CodexQuotaScope,
-  selectionOptions?: CodexAccountUsabilityOptions,
-): string | null {
+/** Coolest account in an already-selected candidate list; first index wins ties. */
+function pickLowestUsageAmong(config: OcxConfig, ids: readonly string[]): string | null {
   let best: string | null = null;
   let bestUsage = Number.POSITIVE_INFINITY;
-  for (const id of getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions)) {
+  for (const id of ids) {
     const usage = computeCodexUsageScore(getAccountQuota(id), getPoolAccountPlan(config, id));
     if (usage < bestUsage) {
       best = id;
@@ -1116,6 +1130,16 @@ export function pickLowestUsageCodexAccount(
   return best;
 }
 
+export function pickLowestUsageCodexAccount(
+  config: OcxConfig,
+  excludeId?: string,
+  now = Date.now(),
+  quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
+): string | null {
+  return pickLowestUsageAmong(config, getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions));
+}
+
 /**
  * Strategy-aware alternate after a cooled/excluded account (same-request 429 retry
  * and active promotion). Quota keeps lowest-usage; fill-first advances stable order;
@@ -1129,12 +1153,16 @@ export function pickAlternateCodexAccount(
   selectionOptions?: CodexAccountUsabilityOptions,
 ): string | null {
   const strategy = normalizeAccountPoolStrategy(config.accountPoolStrategy);
+  // The exclusion is passed into eligibility rather than post-filtered off its
+  // result: when the excluded account is the only healthy member of the top
+  // tier, the tier walk must be free to descend instead of selecting that tier
+  // and then handing back an empty list.
   if (strategy === "round-robin") {
-    const eligible = listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions).filter(id => id !== excludeId);
+    const eligible = getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions);
     return pickRoundRobinAccount(codexPoolKeyForScope(quotaScope), eligible, stickyLimitForConfig(config));
   }
   if (strategy === "fill-first") {
-    const eligible = listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions).filter(id => id !== excludeId);
+    const eligible = getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions);
     return pickNextFillFirstCodexAccount(config, excludeId, eligible, now, selectionOptions);
   }
   return pickLowestUsageCodexAccount(config, excludeId, now, quotaScope, selectionOptions);
@@ -1145,6 +1173,17 @@ export function getEffectiveActiveCodexAccountId(config: OcxConfig): string | un
   return runtimeActiveCodexAccountId ?? config.activeCodexAccountId;
 }
 
+/**
+ * Whether the account routing is currently on is there because an operator asked
+ * for it, rather than because a strategy landed on it. Surfaces read this instead
+ * of comparing the stored pin themselves, which would report a pin that a later
+ * automatic pick has already moved past.
+ */
+export function isEffectiveCodexAccountPinned(config: OcxConfig): boolean {
+  const pinned = pinnedCodexAccountId(config);
+  return pinned !== undefined && pinned === getEffectiveActiveCodexAccountId(config);
+}
+
 /**
  * Automatic strategy / failover cursor only — never mutates `config.activeCodexAccountId`
  * so an unrelated `saveConfig` cannot persist transient rotation as operator selection.
@@ -1153,10 +1192,22 @@ function rememberActiveCodexAccount(_config: OcxConfig, accountId: string): void
   runtimeActiveCodexAccountId = accountId;
 }
 
+/**
+ * End the manual pin when routing moves to a different account. Returns whether
+ * the pin changed so the caller can fold it into a write it was already making.
+ */
+function releaseCodexAccountPinFor(config: OcxConfig, accountId: string): boolean {
+  const pinned = pinnedCodexAccountId(config);
+  if (pinned === undefined || pinned === accountId) return false;
+  clearCodexAccountPin(config);
+  return true;
+}
+
 /** Persist operator (or quota-strategy) active selection to config + disk. */
 function setActiveCodexAccount(config: OcxConfig, accountId: string): void {
   runtimeActiveCodexAccountId = undefined;
-  if (config.activeCodexAccountId === accountId) return;
+  const releasedPin = releaseCodexAccountPinFor(config, accountId);
+  if (config.activeCodexAccountId === accountId && !releasedPin) return;
   config.activeCodexAccountId = accountId;
   saveConfigPreservingClaudeCode(config);
 }
@@ -1167,6 +1218,10 @@ function promoteActiveCodexAccount(config: OcxConfig, accountId: string): void {
     setActiveCodexAccount(config, accountId);
     return;
   }
+  // Runtime-only, like the cursor itself: a caller that persists (pause, delete)
+  // saves this release with its own write; a transient failover does not, so the
+  // pin survives a restart that also clears the failure history behind it.
+  releaseCodexAccountPinFor(config, accountId);
   rememberActiveCodexAccount(config, accountId);
 }
 
@@ -1185,6 +1240,10 @@ export function reconcileCodexActiveAfterExclusion(
   if (config.activeCodexAccountId === excludedAccountId) {
     config.activeCodexAccountId = undefined;
   }
+  // Excluding an account revokes any manual pin on it even when it was not the
+  // effective active — otherwise a paused account keeps acting as a tier ceiling,
+  // suppressing every higher-ordered account while being unusable itself.
+  clearCodexAccountPin(config, excludedAccountId);
   if (!wasEffective) return getEffectiveActiveCodexAccountId(config) ?? null;
 
   runtimeActiveCodexAccountId = undefined;
@@ -1197,6 +1256,54 @@ function isUnknownUsage(usage: number): boolean {
   return usage >= CODEX_UNKNOWN_USAGE_SCORE;
 }
 
+/**
+ * Move an unbound request back up when a higher tier regains headroom — the
+ * weekly-reset case. Returns null when nothing should change.
+ *
+ * Downward moves are deliberately left to {@link applyQuotaAutoSwitch}: this only
+ * fires when the tier filter has already excluded `active`, and only toward a
+ * tier that strictly outranks it. Threads bound by affinity never reach here.
+ */
+function pickPriorityPreemption(
+  config: OcxConfig,
+  active: string,
+  now: number,
+  quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
+): string | null {
+  const eligible = getEligiblePoolAccounts(config, undefined, now, quotaScope, selectionOptions);
+  if (eligible.length === 0 || eligible.includes(active)) return null;
+  const pinned = pinnedCodexAccountId(config);
+  // A live pin already lowered the tier ceiling; never preempt past an explicit
+  // operator choice. Same liveness test the tier filter applies, so preview and
+  // resolve agree even before the pin is garbage-collected.
+  if (pinned !== undefined && eligible.includes(pinned) && hasCodexQuotaHeadroom(config, pinned)) return null;
+  const priorityOf = codexAccountPriorityLookup(config);
+  if (priorityOf(eligible[0]!) <= priorityOf(active)) return null;
+  // Members without headroom are in the tier only because a sibling has some;
+  // picking one would hand the request straight back to a drained account.
+  return pickLowestUsageAmong(config, eligible.filter(id => hasCodexQuotaHeadroom(config, id)));
+}
+
+/**
+ * Release a pin whose account is durably drained. "Use this account now" ends
+ * when the account crosses the auto-switch threshold or stops being selectable
+ * at all — never on a transient cooldown or soft-avoid, which it recovers from
+ * on its own. Clearing the pin also removes the condition, so this writes at
+ * most once per pin.
+ */
+function releaseDrainedCodexAccountPin(config: OcxConfig): void {
+  const pinned = pinnedCodexAccountId(config);
+  if (pinned === undefined) return;
+  const drained = !isCodexAccountUsable(config, pinned)
+    || isAccountNeedsReauth(pinned)
+    || isCodexAccountPaused(config, pinned)
+    || !hasCodexQuotaHeadroom(config, pinned);
+  if (!drained) return;
+  clearCodexAccountPin(config);
+  saveConfigPreservingClaudeCode(config);
+}
+
 function applyQuotaAutoSwitch(
   config: OcxConfig,
   active: string,
@@ -1233,12 +1340,19 @@ function applyFailureFailover(
   config: OcxConfig,
   active: string,
   now: number,
+  quotaScope?: CodexQuotaScope,
   selectionOptions?: CodexAccountUsabilityOptions,
 ): string {
   if (!shouldFailover(config, active, now)) return active;
-  const best = pickAlternateCodexAccount(config, active, now, undefined, selectionOptions);
+  const best = pickAlternateCodexAccount(config, active, now, quotaScope, selectionOptions);
   if (best) {
-    promoteActiveCodexAccount(config, best);
+    // The scope still routes away from the failing account — that is this request's
+    // own decision — but an independent one must not persist a new shared active
+    // account. recordCodexUpstreamOutcome only suppresses the promotion it makes at
+    // the moment of the failure; the streak outlives the soft avoid, so a later
+    // scoped resolve reaches here with the streak still tripped and would otherwise
+    // move the shared cursor after all.
+    if (!isIndependentCodexQuotaScope(quotaScope)) promoteActiveCodexAccount(config, best);
     return best;
   }
   return active;
@@ -1328,6 +1442,7 @@ export function previewCodexAccountForRequest(
     ) return active;
     else return null;
   }
+  active = pickPriorityPreemption(config, active, now, quotaScope, selectionOptions) ?? active;
 
   const threshold = config.autoSwitchThreshold ?? 80;
   if (threshold > 0) {
@@ -1357,6 +1472,12 @@ export function resolveCodexAccountForThreadDetailed(
   quotaScope?: CodexQuotaScope,
   selectionOptions?: CodexAccountUsabilityOptions,
 ): CodexThreadResolution {
+  // Retiring a spent manual pin is independent of affinity: an existing thread
+  // keeps its account below, but the operator's tier ceiling must not silently
+  // revive after quota resets. Independent model scopes must never persist a
+  // change to shared routing state.
+  if (!isIndependentCodexQuotaScope(quotaScope)) releaseDrainedCodexAccountPin(config);
+
   const entry = threadId ? getThreadAffinity(threadId, quotaScope) : undefined;
   if (threadId && entry) {
     if (isThreadAffinityExpired(entry, now)) {
@@ -1430,8 +1551,19 @@ export function resolveCodexAccountForThreadDetailed(
       return { status: "none" };
     }
   }
+  // Before applyQuotaAutoSwitch: its sync disk write would otherwise persist a
+  // move inside the drained tier that preemption immediately overrides.
+  const preempted = pickPriorityPreemption(config, active, now, quotaScope, selectionOptions);
+  if (preempted) {
+    // Runtime-only, like every other automatic pick: config.activeCodexAccountId
+    // stays the operator's selection and getEffectiveActiveCodexAccountId is what
+    // surfaces this to the API and dashboard. An independent quota group must not
+    // move the shared cursor at all — its ordering decision is its own.
+    if (!isIndependentCodexQuotaScope(quotaScope)) rememberActiveCodexAccount(config, preempted);
+    active = preempted;
+  }
   active = applyQuotaAutoSwitch(config, active, now, quotaScope, selectionOptions);
-  active = applyFailureFailover(config, active, now, selectionOptions);
+  active = applyFailureFailover(config, active, now, quotaScope, selectionOptions);
   if (!isCodexAccountUsable(config, active, selectionOptions)) {
     return hasConfiguredPoolAccount(config, active, selectionOptions)
       ? { status: "selected", accountId: active }
@@ -1634,16 +1766,21 @@ export function recordCodexUpstreamOutcome(
     });
     if (!meta.fixedAccount) {
       clearThreadAccountMapForAccount(accountId);
-      notePoolRotationFailure(POOL_KEY_CODEX, accountId);
-      const effectiveActive = getEffectiveActiveCodexAccountId(config);
-      if (effectiveActive === accountId) {
-        // Same-request 429 retry already picked via excludeAccountId — reuse it so
-        // round-robin does not advance the ring a second time.
-        const reused = meta.promoteAccountId && meta.promoteAccountId !== accountId
-          ? meta.promoteAccountId
-          : null;
-        const fallback = reused ?? pickAlternateCodexAccount(config, accountId, now);
-        if (fallback) promoteActiveCodexAccount(config, fallback);
+      // An independent native quota request may discover an account-wide throttle,
+      // but it still must not advance the shared RR ring or active cursor. The next
+      // shared request observes the cooldown and chooses its own fallback.
+      if (!isIndependentCodexQuotaScope(quotaScope)) {
+        notePoolRotationFailure(POOL_KEY_CODEX, accountId);
+        const effectiveActive = getEffectiveActiveCodexAccountId(config);
+        if (effectiveActive === accountId) {
+          // Same-request 429 retry already picked via excludeAccountId — reuse it so
+          // round-robin does not advance the ring a second time.
+          const reused = meta.promoteAccountId && meta.promoteAccountId !== accountId
+            ? meta.promoteAccountId
+            : null;
+          const fallback = reused ?? pickAlternateCodexAccount(config, accountId, now, quotaScope);
+          if (fallback) promoteActiveCodexAccount(config, fallback);
+        }
       }
     }
     return;
@@ -1697,8 +1834,12 @@ export function recordCodexUpstreamOutcome(
   if (!meta.fixedAccount && shouldFailover(config, accountId, now)) {
     clearThreadAccountMapForAccount(accountId);
   }
-  if (!meta.fixedAccount && getEffectiveActiveCodexAccountId(config) === accountId) {
-    applyFailureFailover(config, accountId, now);
+  if (
+    !meta.fixedAccount
+    && !isIndependentCodexQuotaScope(quotaScope)
+    && getEffectiveActiveCodexAccountId(config) === accountId
+  ) {
+    applyFailureFailover(config, accountId, now, quotaScope);
   }
 }
 

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

@@ -18,6 +18,7 @@ import {
   codexQuotaScopeForModel,
   computeCodexUsageScore,
   getCodexQuotaHealthSnapshot,
+  getEffectiveActiveCodexAccountId,
   getPoolAccountPlan,
   isCodexAccountInCooldown,
 } from "./routing";
@@ -29,12 +30,23 @@ import { isCodexAccountPaused } from "./account-pause";
 import { slugEquals } from "../providers/slug-codec";
 import { isThreadSpawnRequest } from "../server/effort-policy";
 import { PROVIDER_REGISTRY } from "../providers/registry";
-import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
+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 {
+  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>;
 let subagentQuotaPrimeForTests: SubagentQuotaPrimeFn | null = null;
 let quotaPrimeInFlight: Promise<void> | null = null;
@@ -131,8 +143,14 @@ function quotaThreshold(config: OcxConfig): number {
   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 config.activeCodexAccountId ?? null;
+  return getEffectiveActiveCodexAccountId(config) ?? null;
 }
 
 /**
@@ -393,11 +411,19 @@ export function resolveAgentModelFallbackForPrimary(
   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;
+}
+
 /**
  * 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.
+ * 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,
@@ -405,11 +431,15 @@ export function maybePrimeSubagentQuota(
   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 {
@@ -527,4 +557,4 @@ export function listCodexAgentRoles(codexHome = CODEX_HOME): string[] {
 export function shouldPrimeSubagentQuota(config: OcxConfig, now = Date.now()): boolean {
   const last = quotaPrimedAt.get("global") ?? 0;
   return now - last >= pollIntervalMs(config);
-}
+}

package/src/codex/sync.ts

@@ -5,9 +5,16 @@ import { applyProxyEnv, loadConfig } from "../config";
 import type { OcxConfig } from "../types";
 import { collectOrcaCodexHomeDiagnostic } from "./home";
 import { summarizeComboCatalogOmissions, type ComboCatalogOmission } from "./catalog/aggregation";
+import { shouldSyncCodexOnStart } from "./desired-state";
+import { admitCodexWrite, type CodexAdmission } from "./admission";
 
 export interface CodexSyncResult {
+  /** `skipped` is policy truth, never evidence that Codex was written. */
+  status: "applied" | "skipped" | "refused";
   ok: boolean;
+  skippedReason?: "desired_disabled";
+  /** Present when unattended convergence refused another service's native home. */
+  authority?: "service-home";
   added: number;
   catalogPath: string | null;
   catalogExists: boolean;
@@ -21,9 +28,13 @@ export interface CodexSyncResult {
   projectConfigGrouped?: { path: string; issues: string[]; bypass: string }[];
 }
 
+type CodexSyncAdmission = Extract<CodexAdmission, { kind: "refused" }> | { readonly kind: "admitted" };
+
 interface CodexSyncDeps {
   refreshCodexModelCatalog: typeof refreshCodexModelCatalog;
   injectCodexConfig: typeof injectCodexConfig;
+  /** The sync entry only needs this admission's service-home verdict. */
+  admitCodexWrite?: () => CodexSyncAdmission;
   currentExternalCodexModelProvider?: typeof currentExternalCodexModelProvider;
   collectCodexHomeDiagnostic?: typeof collectOrcaCodexHomeDiagnostic;
 }
@@ -52,6 +63,40 @@ export async function syncModelsToCodex(
   log: Pick<Console, "log" | "error"> | null = console,
   deps: CodexSyncDeps = defaultDeps,
 ): Promise<CodexSyncResult> {
+  // `config` can be the server's startup object. The decision, however, is a
+  // durable user switch and must be read again at this production boundary: a
+  // PUT OFF while provider discovery is in flight cannot be allowed to commit
+  // through an older captured object.
+  if (!shouldSyncCodexOnStart(loadConfig())) {
+    return {
+      status: "skipped",
+      skippedReason: "desired_disabled",
+      ok: true,
+      added: 0,
+      catalogPath: null,
+      catalogExists: false,
+      catalogWritten: false,
+      cacheSynced: false,
+      message: "Codex integration is OFF; no Codex config, catalog, cache, or history was changed.",
+    };
+  }
+  // Catalog gathering precedes injection and can itself write the native
+  // catalog/cache. It therefore needs the same unattended service-home veto as
+  // the injector, before it gets a chance to create any artifact.
+  const admission = (deps.admitCodexWrite ?? admitCodexWrite)();
+  if (admission.kind === "refused" && admission.authority === "service-home") {
+    return {
+      status: "refused",
+      authority: "service-home",
+      ok: false,
+      added: 0,
+      catalogPath: null,
+      catalogExists: false,
+      catalogWritten: false,
+      cacheSynced: false,
+      message: admission.message,
+    };
+  }
   const p = port ?? config.port ?? 10100;
   const externalProvider = (deps.currentExternalCodexModelProvider ?? currentExternalCodexModelProvider)();
   if (externalProvider) {
@@ -59,6 +104,7 @@ export async function syncModelsToCodex(
     log?.log(result.message);
     reportCodexHomeTarget(log, deps.collectCodexHomeDiagnostic ?? collectOrcaCodexHomeDiagnostic);
     return {
+      status: "applied",
       ok: result.success,
       added: 0,
       catalogPath: null,
@@ -108,10 +154,25 @@ export async function syncModelsToCodex(
   }
 
   const result = await deps.injectCodexConfig(p, config, { catalogPath: catalogPathForInjection });
+  if (result.status === "skipped") {
+    return {
+      status: "skipped",
+      // The apply direction's only under-lock policy skip is desired OFF.
+      skippedReason: "desired_disabled",
+      ok: true,
+      added: 0,
+      catalogPath: null,
+      catalogExists: false,
+      catalogWritten: false,
+      cacheSynced: false,
+      message: result.message,
+    };
+  }
   log?.log(result.message);
   reportCodexHomeTarget(log, deps.collectCodexHomeDiagnostic ?? collectOrcaCodexHomeDiagnostic);
   const projectConfigWarnings = printProjectCodexConfigWarnings(log, { cwd: process.cwd() });
   return {
+    status: "applied",
     ok: result.success,
     added,
     catalogPath,