@bitkyc08/opencodex 2.49.0 → 2.51.0

package/src/codex/inject.ts

@@ -9,7 +9,11 @@ import {
   withConfigMutationLockSync,
 } from "../config";
 import { CodexWriteLockSkipped, withCodexWriteLock } from "./codex-write-lock";
-import { shouldSyncCodexOnStart } from "./desired-state";
+import {
+  localClientSkipMessage,
+  localClientSkipReason,
+  shouldSyncCodexOnStart,
+} from "./desired-state";
 import { resolveCodexHistoryTransition } from "./history-transition";
 import {
   buildInjectWitness,
@@ -79,9 +83,9 @@ import {
   type ManagedSubagentDefaults,
 } from "./subagent-defaults";
 import type { OcxConfig } from "../types";
-import { isLoopbackHostname, shouldInjectApiAuthHeader } from "./loopback-target";
+import { effectiveLoopbackListenerPort, isLoopbackHostname, shouldInjectApiAuthHeader } from "./loopback-target";
 
-export { isLoopbackHostname, shouldInjectApiAuthHeader } from "./loopback-target";
+export { effectiveLoopbackListenerPort, isLoopbackHostname, shouldInjectApiAuthHeader } from "./loopback-target";
 
 // Ownership predicates live in `./injected-marker` so `journal.ts` can reach them
 // without importing this module back. Re-exported for existing external callers.
@@ -214,8 +218,11 @@ export function standaloneCodexRoutingTarget(
     "hostname" | "unauthenticatedLoopbackListener" | "codexDesktopAuthless" | "codexClientCompaction"
   >,
 ): CodexRoutingTarget {
+  // An enabled listener with no `port` is the companion form: it answers on `port` itself,
+  // bound to 127.0.0.1 (#4236). Resolving it through the shared helper is what makes the
+  // one-port hub work without every writer repeating `?? port`.
   const loopback = config?.unauthenticatedLoopbackListener;
-  const effectivePort = loopback?.enabled ? loopback.port : port;
+  const effectivePort = effectiveLoopbackListenerPort(config, port) ?? port;
   const hostname = loopback?.enabled ? undefined : config?.hostname;
   const requiresAdmissionToken = loopback?.enabled ? false : shouldInjectApiAuthHeader(config);
   return {
@@ -887,7 +894,8 @@ export interface CodexInjectResult {
   success: boolean;
   message: string;
   status?: "skipped";
-  skippedReason?: "desired_disabled" | "desired_enabled";
+  /** `hub-gated` is the hub-role gate (#4236), distinct from the user's own OFF switch. */
+  skippedReason?: "desired_disabled" | "desired_enabled" | "hub-gated";
   nativeSubagentDefaultsWarning?: string;
 }
 
@@ -1261,12 +1269,17 @@ export async function injectCodexConfig(
 
   if (eligibility.kind === "legacy-uncoordinated") {
     const applyLegacy = (): CodexInjectResult | undefined => {
-      if (!shouldSyncCodexOnStart(loadConfig())) {
+      const legacyGateSnapshot = loadConfig();
+      if (!shouldSyncCodexOnStart(legacyGateSnapshot)) {
         return {
           success: true,
           status: "skipped",
-          skippedReason: "desired_disabled",
-          message: "Codex integration is OFF; no Codex config, catalog, cache, or history was changed.",
+          skippedReason: localClientSkipReason(legacyGateSnapshot),
+          message: localClientSkipMessage(
+            legacyGateSnapshot,
+            "Codex integration is OFF; no Codex config, catalog, cache, or history was changed.",
+            "No Codex config, catalog, cache, or history was changed.",
+          ),
         };
       }
       runClientWriteGuard(options.beforeClientWrite);
@@ -1295,8 +1308,11 @@ export async function injectCodexConfig(
         }),
       },
       (ctx) => {
-        if (!shouldSyncCodexOnStart(loadConfig())) {
-          throw new CodexWriteLockSkipped("desired_disabled");
+        const gateSnapshot = loadConfig();
+        if (!shouldSyncCodexOnStart(gateSnapshot)) {
+          // Carry WHY under the lock: "the hub does not write its own clients" and "the user
+          // turned Codex off" produce the same no-write and must not produce the same sentence.
+          throw new CodexWriteLockSkipped(localClientSkipReason(gateSnapshot));
         }
         // N and C are held here. Reject stale client work before publishing a
         // transition or capturing preimages; rejection must not compensate over
@@ -1430,7 +1446,7 @@ export async function injectCodexConfig(
   const historyMessage =
     keepRootOverrideAlongsideTable
       ? (keptUserBaseUrl
-        ? `  Codex resume history: left unchanged; threads already tagged openai follow your own root openai_base_url, not the proxy.\n`
+        ? `  Codex resume history: left unchanged; threads already tagged openai follow your configured root openai_base_url.\n`
         : `  Codex resume history: left unchanged; existing threads keep reaching the proxy through the retained openai_base_url override.\n`)
       : config?.syncResumeHistory === false
       ? `  Codex resume history: left unchanged (syncResumeHistory=false).\n`
@@ -1447,6 +1463,7 @@ export async function injectCodexConfig(
   // The client-compaction form writes a provider table as well, so "nothing was injected" would
   // misdescribe the file it just produced: new threads do use the injected table. Report that
   // mixed result on its own terms, and never tell the operator to delete a setting of theirs.
+  // Ownership alone says nothing about destination: their line may already target this proxy.
   if (keptUserBaseUrl && keepRootOverrideAlongsideTable) {
     return {
       success: true,
@@ -1459,7 +1476,7 @@ export async function injectCodexConfig(
         managedDefaultsMessage +
         `  New threads use the injected opencodex provider and route through the proxy.\n` +
         `  Threads already tagged openai resolve through Codex's built-in provider, which your root openai_base_url points at.\n` +
-        `  Remove that line and rerun 'ocx start' only if you want those threads on the proxy too.\n` +
+        `  No root URL change is required to enable client-side compaction for new threads.\n` +
         `  Fallback: codex --profile opencodex (same behavior)`,
     };
   }

package/src/codex/loopback-target.ts

@@ -36,6 +36,51 @@ export function isLoopbackHostname(hostname: string | undefined): boolean {
   );
 }
 
+/**
+ * Bind scope again, from the other side: a wildcard listener already answers on 127.0.0.1.
+ *
+ * This matters only for the port-less "companion" loopback listener. On `0.0.0.0`/`::` the
+ * public socket owns loopback on that port, so a companion bound to the same port would
+ * collide; on a specific non-loopback address (a tailnet or LAN IP) 127.0.0.1 is free.
+ */
+export function isWildcardHostname(hostname: string | undefined): boolean {
+  const normalized = (hostname ?? "").trim().toLowerCase().replace(/\.$/, "").replace(/^\[(.*)\]$/, "$1");
+  if (normalized === "*" || normalized === "0") return true;
+  // Every spelling of the IPv4 unspecified address ("0.0.0.0", "00.0.0.000", …).
+  if (/^(0+\.){3}0+$/.test(normalized)) return true;
+  // Every spelling of the IPv6 unspecified address ("::", "::0", "0::", "0:0:0:0:0:0:0:0", …):
+  // nothing but zero groups and colons. A dual-stack `::` bind answers on 127.0.0.1 as well.
+  return normalized.includes(":") && /^[0:]+$/.test(normalized);
+}
+
+/**
+ * Is `{ enabled: true }` with no port legal for this bind address?
+ *
+ * The companion form binds `127.0.0.1:<proxy port>`, which is exactly the one-port hub shape:
+ * remote clients dial `hostname:port`, local processes dial `127.0.0.1:port`, and every
+ * hardcoded `http://127.0.0.1:<proxy port>` integration works with no rewriting. It is legal
+ * only when the public listener is NOT already holding that loopback address.
+ */
+export function loopbackCompanionAllowed(hostname: string | undefined): boolean {
+  return !isLoopbackHostname(hostname) && !isWildcardHostname(hostname);
+}
+
+/**
+ * The port local callers reach the unauthenticated listener on, or null when it is off.
+ *
+ * One resolver for every reader (#4236): an enabled listener with no `port` is the companion
+ * form and answers on the public port. Callers must not repeat `?? port` — the day the default
+ * changes, a forgotten site points a client config at a closed socket.
+ */
+export function effectiveLoopbackListenerPort(
+  config: Pick<OcxConfig, "unauthenticatedLoopbackListener"> | undefined,
+  publicPort: number,
+): number | null {
+  const listener = config?.unauthenticatedLoopbackListener;
+  if (!listener?.enabled) return null;
+  return listener.port ?? publicPort;
+}
+
 export function shouldInjectApiAuthHeader(
   config: Pick<OcxConfig, "hostname" | "unauthenticatedLoopbackListener"> | undefined,
 ): boolean {

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

@@ -8,7 +8,7 @@ import { isSelectableCodexPoolAccount } from "./account-id";
 import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
 import { isCodexAccountPaused } from "./account-pause";
 import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
-import { getValidCodexToken, isCodexAccountGenerationLive } from "./account-store";
+import { getValidCodexToken, isCodexAccountGenerationLive, readCodexAccountRecord } 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";
@@ -164,7 +164,11 @@ function mainWarmupRestricted(config: OcxConfig): boolean {
 async function warmAccount(config: OcxConfig, accountId: string): Promise<void | false> {
   const writerGeneration = captureConfigGeneration();
   if (accountId !== MAIN_CODEX_ACCOUNT_ID) {
+    if (readCodexAccountRecord(accountId)?.codexValidationPending) return false;
     const token = await getValidCodexToken(accountId);
+    const record = readCodexAccountRecord(accountId);
+    if (!record?.credential || record.deletedAt != null || record.codexValidationPending
+      || record.generation !== token.generation) return false;
     if (isCodexAccountPaused(config, accountId) || isAccountNeedsReauth(accountId)) return false;
     try {
       await warmCodexAccount({ ...token, onCompleted: headers => {
@@ -294,6 +298,7 @@ export async function runCodexQuotaAutoRefresh(
         && (accountId === MAIN_CODEX_ACCOUNT_ID || config.codexAccounts?.some(
           account => account.id === accountId && isSelectableCodexPoolAccount(account)))
         && (setting?.fiveHour === true || setting?.weekly === true)
+        && !(accountId !== MAIN_CODEX_ACCOUNT_ID && readCodexAccountRecord(accountId)?.codexValidationPending)
         && !isCodexAccountPaused(config, accountId) && !isAccountNeedsReauth(accountId)
         && !(accountId === MAIN_CODEX_ACCOUNT_ID && isMainAccountHardLocked(config));
     };

package/src/codex/quota.ts

@@ -407,7 +407,20 @@ export function flushQuotaObservationsForTests(): Promise<void> {
   return pendingObservation;
 }
 
-export function parseUpstreamQuotaHeaders(headers: Headers): Omit<StoredAccountQuota, "updatedAt"> | null {
+/** Wire marker shared by Spark-family models, whose upstream limit family is model-specific. */
+const SPARK_MODEL_MARKER = "codex-spark";
+/**
+ * Custom-window label for the Spark 5h window. The WHAM parser and the response-header path
+ * must write the SAME label so a header refresh replaces the WHAM reading instead of doubling it.
+ */
+const SPARK_SHORT_WINDOW_LABEL = "GPT-5.3-Codex-Spark 5h";
+
+/** True when the routed model belongs to the Spark family, which carries its own rate limit. */
+function isCodexSparkModel(modelId: string | undefined): boolean {
+  return typeof modelId === "string" && modelId.includes(SPARK_MODEL_MARKER);
+}
+
+export function parseUpstreamQuotaHeaders(headers: Headers, options?: { modelId?: string }): Omit<StoredAccountQuota, "updatedAt"> | null {
   const primaryRaw = headers.get("x-codex-primary-used-percent");
   const secondaryRaw = headers.get("x-codex-secondary-used-percent");
   const tertiaryRaw = headers.get("x-codex-tertiary-used-percent");
@@ -430,6 +443,10 @@ export function parseUpstreamQuotaHeaders(headers: Headers): Omit<StoredAccountQ
   // it into weeklyPercent both discards the real weekly reading and leaves the account looking
   // exhausted long after the burst window resets. Duration decides, exactly as parseUsageQuota
   // already does for the WHAM payload — the two parsers must not disagree about the same data.
+  // One more attribution layer (#4122): on a Spark-family model response the sub-day primary is
+  // the MODEL-SPECIFIC limit, not an account window. Filing it as the account short tuple made
+  // one pool account display a 5h bar its identically-limited peers did not have, and fed a
+  // model limit to the account-policy readers (main-account hard lock, five-hour auto-refresh).
   const primaryIsShort = isExplicitShortWindowMinutes(primaryWindowMinutes);
 
   if (primaryIsMonthly) {
@@ -446,10 +463,21 @@ export function parseUpstreamQuotaHeaders(headers: Headers): Omit<StoredAccountQ
       if (secondaryResetAt !== undefined) quota.weeklyResetAt = secondaryResetAt;
     }
   } else if (primaryIsShort) {
-    if (primaryPercent !== undefined) quota.shortPercent = primaryPercent;
-    if (primaryResetAt !== undefined) quota.shortResetAt = primaryResetAt;
-    const minutes = windowMinutes_(primaryWindowMinutes);
-    if (minutes !== undefined) quota.shortWindowSeconds = Math.round(minutes * 60);
+    if (isCodexSparkModel(options?.modelId)) {
+      if (primaryPercent !== undefined) {
+        const sparkWindow: { label: string; percent: number; resetAt?: number } = {
+          label: SPARK_SHORT_WINDOW_LABEL,
+          percent: primaryPercent,
+        };
+        if (primaryResetAt !== undefined) sparkWindow.resetAt = primaryResetAt;
+        quota.customWindows = [sparkWindow];
+      }
+    } else {
+      if (primaryPercent !== undefined) quota.shortPercent = primaryPercent;
+      if (primaryResetAt !== undefined) quota.shortResetAt = primaryResetAt;
+      const minutes = windowMinutes_(primaryWindowMinutes);
+      if (minutes !== undefined) quota.shortWindowSeconds = Math.round(minutes * 60);
+    }
     // The burst window vacates the primary slot, so the weekly reading is the secondary — which
     // is where it was all along. Without this the true weekly value is silently dropped.
     if (secondaryPercent !== undefined) {
@@ -480,13 +508,31 @@ export function applyAccountQuotaFromUpstreamHeaders(
   headers: Headers,
   writerGeneration = captureConfigGeneration(),
   mainWriter?: MainQuotaWriter,
+  options?: { modelId?: string },
 ): void {
-  const quota = parseUpstreamQuotaHeaders(headers);
+  const quota = parseUpstreamQuotaHeaders(headers, options);
   if (!quota) return;
   const policyQuota = [
     "x-codex-primary-used-percent", "x-codex-secondary-used-percent", "x-codex-tertiary-used-percent",
   ].some(name => isInvalidPolicyUsagePercent(headers.get(name))) ? null : filterMainPolicyMonthlyQuota(quota);
-  setAccountQuotaFromParsed(accountId, quota, writerGeneration, mainWriter, policyQuota);
+  // A header-observed Spark window is a partial update against the WHAM-recorded custom windows:
+  // merge by label so the weekly Spark entry survives, and hydrate first so the first call in a
+  // process does not merge against an empty map. The merged list goes only to the legacy
+  // snapshot — the identity-bound policy evidence keeps exactly what this response said.
+  let legacyQuota = quota;
+  if (quota.customWindows !== undefined) {
+    hydrateAccountQuotasFromDisk();
+    const existing = accountQuota.get(accountId)?.customWindows;
+    if (existing !== undefined) {
+      const incoming = new Map(quota.customWindows.map(window => [window.label, window]));
+      const merged = existing.map(window => incoming.get(window.label) ?? window);
+      for (const window of quota.customWindows) {
+        if (!existing.some(entry => entry.label === window.label)) merged.push(window);
+      }
+      legacyQuota = { ...quota, customWindows: merged };
+    }
+  }
+  setAccountQuotaFromParsed(accountId, legacyQuota, writerGeneration, mainWriter, policyQuota);
 }
 
 export function updateAccountQuota(
@@ -812,7 +858,7 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
   });
   const sparkCustomWindows: Array<{ label: string; percent: number; resetAt?: number }> = [];
   for (const [label, window] of [
-    ["GPT-5.3-Codex-Spark 5h", sparkShort],
+    [SPARK_SHORT_WINDOW_LABEL, sparkShort],
     ["GPT-5.3-Codex-Spark Weekly", sparkWeekly],
   ] as const) {
     const percent = normalizeUsagePercent(window?.used_percent);

package/src/codex/routing.ts

@@ -19,7 +19,7 @@ import {
   selectPriorityTier,
 } from "./pool-rotation";
 import { CODEX_EXHAUSTED_USAGE_PERCENT, CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota";
-import { isThirtyDayOnlyCodexPlan } from "./plan";
+import { codexPlanKey, isThirtyDayOnlyCodexPlan } from "./plan";
 import {
   MAIN_CODEX_ACCOUNT_ID,
   getMainAccountPlan,
@@ -1004,6 +1004,50 @@ export function isCodexAccountSoftAvoided(accountId: string, now = Date.now()):
   return getCodexAccountSoftAvoidUntil(accountId, now) !== null;
 }
 
+/**
+ * Plan keys the operator excluded from automatic rotation. Absent or empty means no policy, so an
+ * existing install rotates exactly as before. Compared with `codexPlanKey` because the stored plan
+ * is an unrestricted provider string whose casing this repository does not control.
+ */
+function excludedCodexPoolPlanKeys(config: OcxConfig): ReadonlySet<string> | undefined {
+  const configured = config.codexPool?.excludedPlans;
+  if (!configured?.length) return undefined;
+  const keys = configured
+    .map(plan => codexPlanKey(plan))
+    .filter((key): key is string => key !== undefined);
+  return keys.length > 0 ? new Set(keys) : undefined;
+}
+
+/**
+ * Whether the operator's plan policy removes this account from automatic selection.
+ *
+ * Modelled on pause rather than usability: an excluded account keeps its credential, quota history,
+ * and affinity, stays visible on the account surface, and is still reachable by explicit account
+ * selection. Only automatic rotation skips it, which is the distinction #4211 asked for.
+ *
+ * It is checked in the same two places pause is checked, and that is not redundancy. The eligible
+ * list is consulted only when routing picks a NEW account; an already-active or already-affined
+ * account is served straight from {@link isCodexAccountSelectable}. A lapsed subscription leaves
+ * behind exactly that account, so a policy that filtered only the eligible list would miss the case
+ * it exists for.
+ *
+ * `__main__` is exempt. {@link getPoolAccountPlanForSelection} withholds the main plan during a
+ * selection-only drain so routing never reads the fenced native credential for it, so a rule that
+ * covered main would disagree with itself between drain and ordinary routing.
+ */
+function isCodexAccountPlanExcluded(
+  config: OcxConfig,
+  accountId: string,
+  precomputed?: ReadonlySet<string>,
+): boolean {
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) return false;
+  // Callers that test a whole list pass the set once rather than rebuilding it per row.
+  const excluded = precomputed ?? excludedCodexPoolPlanKeys(config);
+  if (!excluded) return false;
+  const plan = codexPlanKey(getPoolAccountPlan(config, accountId));
+  return plan !== undefined && excluded.has(plan);
+}
+
 function isCodexAccountSelectable(
   config: OcxConfig,
   accountId: string,
@@ -1012,6 +1056,7 @@ function isCodexAccountSelectable(
   selectionOptions?: CodexAccountUsabilityOptions,
 ): boolean {
   return !isCodexAccountPaused(config, accountId)
+    && !isCodexAccountPlanExcluded(config, accountId)
     && getCodexQuotaHealthSnapshot(accountId, quotaScope, now) === null
     && !isCodexAccountSoftAvoided(accountId, now)
     && isCodexAccountUsable(config, accountId, selectionOptions);
@@ -1242,10 +1287,12 @@ function getEligiblePoolAccounts(
   selectionOptions?: CodexAccountUsabilityOptions,
   skipFailoverReadyCandidates = false,
 ): readonly string[] {
+  const excludedPlans = excludedCodexPoolPlanKeys(config);
   const ids = (config.codexAccounts ?? [])
     .filter(account => isSelectableCodexPoolAccount(account)
       && account.id !== excludeId
       && !isCodexAccountPaused(config, account.id)
+      && !isCodexAccountPlanExcluded(config, account.id, excludedPlans)
       && !isAccountNeedsReauth(account.id)
       && (!skipFailoverReadyCandidates || !shouldFailover(config, account.id, now)))
     .filter(account => getCodexQuotaHealthSnapshot(account.id, quotaScope, now) === null)

package/src/codex/runtime.ts

@@ -427,13 +427,47 @@ function sameRuntimeCommand(a: string, b: string): boolean {
   return a.trim().toLowerCase() === b.trim().toLowerCase();
 }
 
-/** True when a persisted clamp diagnostic still applies to the currently selected runtime. */
+/**
+ * Rungs OpenCodex no longer lets the observed-runtime intersection remove, so a persisted
+ * diagnostic naming only these describes a policy that is gone rather than a live restriction.
+ * This is the single copy of the exemption: `catalog/effort.ts` imports it for the clamp
+ * predicate, and a leftover file written before the exemption must not keep warning about
+ * rungs the next sync will stop removing.
+ */
+export const UNCLAMPABLE_REASONING_EFFORTS: ReadonlySet<string> = new Set(["max", "ultra"]);
+
+/** Removals that still describe a real restriction, ignoring rungs nothing clamps any more. */
+export function liveRemovedEfforts(
+  diagnostic: EffortClampDiagnostic | null | undefined,
+): readonly string[] {
+  if (!diagnostic) return [];
+  return diagnostic.removedEfforts.filter(effort => !UNCLAMPABLE_REASONING_EFFORTS.has(effort));
+}
+
+/**
+ * True when a persisted clamp diagnostic still applies to the currently selected runtime.
+ *
+ * Two ways a stored diagnostic stops describing reality:
+ *
+ * 1. Every rung it names is one nothing clamps any more, so the file is inert until the next
+ *    sync unlinks it.
+ * 2. The binary at that path was upgraded in place. Windows updates Codex without moving the
+ *    executable, so path equality alone kept a 0.135.0 observation "current" for a 0.154.0
+ *    runtime whose own bundled catalog carried the rungs the diagnostic claimed were missing.
+ *    A known version mismatch therefore wins over a path match; an unknown version on either
+ *    side stays conservative, because absence of a version is not evidence of an upgrade.
+ */
 export function effortClampAppliesToRuntime(
   diagnostic: EffortClampDiagnostic | null | undefined,
   runtime: Pick<ResolvedCodexRuntime, "command" | "version">,
 ): boolean {
-  if (!diagnostic || diagnostic.removedEfforts.length === 0) return false;
-  if (sameRuntimeCommand(diagnostic.runtimePath, runtime.command)) return true;
+  if (!diagnostic || liveRemovedEfforts(diagnostic).length === 0) return false;
+  if (sameRuntimeCommand(diagnostic.runtimePath, runtime.command)) {
+    if (diagnostic.runtimeVersion && runtime.version) {
+      return diagnostic.runtimeVersion === runtime.version;
+    }
+    return true;
+  }
   return Boolean(
     diagnostic.runtimeVersion
     && runtime.version

package/src/codex/sync.ts

@@ -5,7 +5,12 @@ 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 {
+  localClientSkipMessage,
+  localClientSkipReason,
+  shouldSyncCodexOnStart,
+  type LocalClientSkipReason,
+} from "./desired-state";
 import { admitCodexWrite, type CodexAdmission } from "./admission";
 import type { CodexCatalogSyncOptions } from "./catalog/sync";
 import { resetCodexAppServerCatalogStateCache } from "./app-server-processes";
@@ -18,7 +23,8 @@ export interface CodexSyncResult {
    */
   status: "applied" | "skipped" | "catalog-only" | "refused";
   ok: boolean;
-  skippedReason?: "desired_disabled";
+  /** `hub-gated` is the hub-role gate, not the user's toggle — the two read very differently. */
+  skippedReason?: LocalClientSkipReason;
   /** Present when unattended convergence refused another service's native home. */
   authority?: "service-home";
   added: number;
@@ -85,19 +91,24 @@ export async function syncModelsToCodex(
   // 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.
-  const desiredDisabled = !shouldSyncCodexOnStart(loadConfig());
+  const gateSnapshot = loadConfig();
+  const desiredDisabled = !shouldSyncCodexOnStart(gateSnapshot);
   const catalogEvenWhenNotInjected = options.catalogEvenWhenNotInjected === true;
   if (desiredDisabled && !catalogEvenWhenNotInjected) {
     return {
       status: "skipped",
-      skippedReason: "desired_disabled",
+      skippedReason: localClientSkipReason(gateSnapshot),
       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.",
+      message: localClientSkipMessage(
+        gateSnapshot,
+        "Codex integration is OFF; no Codex config, catalog, cache, or history was changed.",
+        "No Codex config, catalog, cache, or history was changed.",
+      ),
     };
   }
   // Catalog gathering precedes injection and can itself write the native
@@ -131,8 +142,16 @@ export async function syncModelsToCodex(
     applyProxyEnv(config);
     const refreshed = await refreshCatalogForSync(config, deps, { allowWhenDesiredDisabled: true }, log);
     const message = refreshed.catalogWritten || refreshed.cacheSynced
-      ? "Codex integration is OFF; catalog and models cache refreshed, Codex config untouched."
-      : "Codex integration is OFF; catalog refresh skipped, Codex config untouched.";
+      ? localClientSkipMessage(
+        gateSnapshot,
+        "Codex integration is OFF; catalog and models cache refreshed, Codex config untouched.",
+        "Catalog and models cache refreshed, Codex config untouched.",
+      )
+      : localClientSkipMessage(
+        gateSnapshot,
+        "Codex integration is OFF; catalog refresh skipped, Codex config untouched.",
+        "Catalog refresh skipped, Codex config untouched.",
+      );
     return {
       status: "catalog-only",
       ok: true,
@@ -242,8 +261,9 @@ export async function syncModelsToCodex(
   if (result.status === "skipped") {
     return {
       status: "skipped",
-      // The apply direction's only under-lock policy skip is desired OFF.
-      skippedReason: "desired_disabled",
+      // The apply direction's only under-lock policy skips are desired OFF and the hub gate;
+      // carry whichever the injector reported so the caller can say the honest thing.
+      skippedReason: result.skippedReason === "hub-gated" ? "hub-gated" : "desired_disabled",
       ok: true,
       added: 0,
       catalogPath: null,

package/src/codex/warmup.ts

@@ -28,7 +28,8 @@ export interface CodexWarmupOptions {
 
 const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
 const DEFAULT_MODEL = "gpt-5.4-mini";
-const FALLBACK_MODELS = ["gpt-5.5"];
+const FALLBACK_MODELS = ["gpt-5.5", "gpt-5.6-luna"];
+const isRetryableWarmupStatus = (status?: number): boolean => status === 400 || status === 404;
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 0x7fff_ffff;
 const MAX_ERROR_BODY_BYTES = 2048;
@@ -63,6 +64,17 @@ export function codexWarmupFailureReason(err: unknown): string {
   return safeWarmupReason(err);
 }
 
+/**
+ * 400 and 404 mean the model or the account is not provisioned for this request, not that the
+ * credential is bad. Sharing the retry predicate keeps the operator-facing diagnostic from
+ * disagreeing with the fallback policy that produced the final error.
+ */
+export function isCodexWarmupProvisioningFailure(err: unknown): boolean {
+  return err instanceof CodexWarmupError
+    && err.code === "http_status"
+    && isRetryableWarmupStatus(err.status);
+}
+
 function eventTypeFromData(data: unknown): string | undefined {
   if (!data || typeof data !== "object") return undefined;
   const record = data as Record<string, unknown>;
@@ -286,8 +298,8 @@ export async function warmCodexAccount(options: CodexWarmupOptions): Promise<voi
     await tryWarmup(options, primaryModel);
     return;
   } catch (err) {
-    // Retry with fallback models on 400 (model may not be available for this account).
-    if (!(err instanceof CodexWarmupError) || err.status !== 400) throw err;
+    // Retry with fallback models on 400 or 404 (model may not be provisioned or available for this account).
+    if (!(err instanceof CodexWarmupError) || !isRetryableWarmupStatus(err.status)) throw err;
     let lastErr = err;
     for (const fallback of FALLBACK_MODELS) {
       if (fallback === primaryModel) continue;
@@ -295,7 +307,12 @@ export async function warmCodexAccount(options: CodexWarmupOptions): Promise<voi
         await tryWarmup(options, fallback);
         return;
       } catch (retryErr) {
-        if (retryErr instanceof CodexWarmupError) lastErr = retryErr;
+        if (retryErr instanceof CodexWarmupError) {
+          lastErr = retryErr;
+          if (!isRetryableWarmupStatus(retryErr.status)) throw retryErr;
+        } else {
+          throw retryErr;
+        }
       }
     }
     throw lastErr;

package/src/combos/index.ts

@@ -27,9 +27,11 @@ export {
   noteComboSuccess,
   pickComboTarget,
   pickComboTargetWithWait,
+  quotaInactiveReason,
   tryPickComboModel,
   UnknownComboError,
   type ComboPick,
+  type QuotaInactiveReason,
 } from "./resolve";
 export {
   clearComboTargetCooldowns,

package/src/combos/resolve.ts

@@ -92,6 +92,58 @@ export function cachedProviderQuotaIsExhausted(
   return false;
 }
 
+/**
+ * Why a catalog row is offered but cannot currently serve a request (#1711).
+ *
+ * Only one reason exists today. It is a string rather than a boolean so a later cause — a
+ * cooldown, a revoked key — can be told apart by a consumer that already reads the field.
+ */
+export type QuotaInactiveReason = "no_credit";
+
+/**
+ * `"no_credit"` when every USABLE target of a catalog row has positive exhaustion evidence
+ * (#1711), otherwise undefined.
+ *
+ * This deliberately reuses the runtime rules in `targetProviderIsUsable` above rather than the
+ * Dashboard's `quotaStateFromReport`, which is harsher: it treats `remaining <= 0` as exhausted
+ * without requiring `percent >= 100` and ignores an elapsed `resetAt`. A catalog row marked
+ * inactive on the harsher rule would contradict the router, which would still happily send the
+ * request.
+ *
+ * Three rules carry the correctness, all inherited rather than restated:
+ *
+ * - A target the operator has removed or disabled is not usable and is not evidence either way;
+ *   it drops out before the vote. If nothing is left, the row is unavailable for an operator
+ *   reason rather than a quota one, so this returns undefined.
+ * - The canonical ChatGPT forward provider is exempt. Native account selection owns model-scoped
+ *   quota, and a provider-level summary cannot veto it.
+ * - A stale cache is NOT exhaustion. `getCachedProviderQuota` returns null past its 30-minute
+ *   window, and a null reading ends the vote rather than counting as evidence, so an unprobed
+ *   provider is never marked inactive.
+ *
+ * "Every" is the bar on purpose: one target that can still serve makes the row serviceable, which
+ * is exactly what the combo loop concludes at request time.
+ */
+export function quotaInactiveReason(
+  config: OcxConfig,
+  targets: readonly { provider: string }[],
+  now = Date.now(),
+): QuotaInactiveReason | undefined {
+  const usable = targets.filter(target => {
+    if (!Object.hasOwn(config.providers, target.provider)) return false;
+    const provider = config.providers[target.provider];
+    return !!provider && provider.disabled !== true;
+  });
+  if (usable.length === 0) return undefined;
+  for (const target of usable) {
+    const provider = config.providers[target.provider]!;
+    if (isCanonicalOpenAiForwardProvider(provider)) return undefined;
+    const quota = getCachedProviderQuota(target.provider, now);
+    if (!quota || !cachedProviderQuotaIsExhausted(quota, now)) return undefined;
+  }
+  return "no_credit";
+}
+
 function smoothWeightedIndex(
   targets: Required<OcxComboTarget>[],
   state: SelectionState,

package/src/config/pending-teardown.ts

@@ -175,7 +175,7 @@ export function listPendingTeardowns(): OutstandingTeardown[] {
   }
   const out: OutstandingTeardown[] = [];
   for (const name of names) {
-    // One naming rule, shared with the npm launcher: the two lanes drifting apart is
+    // One naming rule, shared with the package launcher: the two lanes drifting apart is
     // exactly how the Node updater stopped seeing receipts at all.
     if (!isPendingTeardownFileName(name)) continue;
     const nonce = pendingTeardownNonceFromFileName(name)!;