@bitkyc08/opencodex 2.50.0 → 2.51.0

package/src/codex/catalog/sync.ts

@@ -42,6 +42,8 @@ import {
   resolveCodexModelEntitlements,
   type CodexModelEntitlementSnapshot,
 } from "../model-entitlements";
+import { isAccountNeedsReauth } from "../account-runtime-state";
+import { codexAccountLogLabel, fallbackCodexAccountLogLabel } from "../account-label";
 
 
 import { CODEX_CUSTOM_MODEL_CATALOG_KIND, CODEX_PROVIDER_MODEL_CATALOG_KIND, activeCodexModelsCachePath, applyCatalogMetadata, applyMultiAgentMode, applyNativeOpenAiContextOverride, applyRoutedCodexToolMode, catalogBackupPathFor, catalogHasRoutedEntries, catalogModelSlug, ensureStrictCatalogFields, findNativeTemplate, findSupportedNativeTemplate, isDefaultCatalogPath, isRoutedModelCompatibilityExcluded, legacyCatalogBackupPath, normalizeRoutedCatalogEntry, normalizeServiceTiers, readCatalog, readCatalogBackup, readCodexCatalogPath, readCodexCatalogPathForHome, readConfiguredAutoReviewModel, readNativeBaseline } from "./parsing";
@@ -1708,6 +1710,75 @@ export function finalizeAutoReviewModelOverride(
   return applyAutoReviewModelOverride(models, readConfiguredAutoReviewModel(), sourceModels);
 }
 
+/**
+ * Why an account-gated native model stopped being offered, but only when the answer is one the
+ * operator can act on.
+ *
+ * Suppression is an omission: the row is never built, so there is no catalog entry for a reason
+ * to ride on and no downstream consumer that could explain it later. #4212's reporter watched
+ * their models disappear and reasonably concluded the proxy was broken, because every surface
+ * that changed said nothing about the account that caused it.
+ *
+ * Returns `undefined` for the ordinary case — an account that is simply not entitled to a gated
+ * model. That is the default state for most installations, it is not news, and warning about it
+ * on every sync would bury the one case that matters. A credential the operator must repair is
+ * the case that matters, so that is the only one this speaks up about.
+ *
+ * Accounts are named with the durable `p`-prefixed log label, the same identifier the dashboard
+ * shows, never the raw pool id or the email.
+ */
+export function gatedNativeReauthSuppressionReason(args: {
+  snapshot: CodexModelEntitlementSnapshot;
+  slug: string;
+  eligibleAccountIds?: ReadonlySet<string>;
+  needsReauth: (accountId: string) => boolean;
+  label: (accountId: string) => string;
+}): string | undefined {
+  const observed = [...args.snapshot.modelsByAccount.keys()]
+    .filter(accountId => !args.eligibleAccountIds || args.eligibleAccountIds.has(accountId))
+    // Only accounts that could actually have served THIS model. An account upstream positively
+    // denied is not why the model is missing, and blaming it would send the operator to repair a
+    // credential that was never going to help. `unknown` has to stay in: an account whose roster
+    // could not be confirmed reports `unknown` rather than `granted`, and a credential stuck on
+    // a failed refresh is exactly that account.
+    .filter(accountId => (
+      codexModelEntitlementStateForAccount(args.snapshot, accountId, args.slug) !== "denied"
+    ));
+  const stuck = observed.filter(accountId => args.needsReauth(accountId));
+  if (stuck.length === 0) return undefined;
+  const names = stuck.map(accountId => args.label(accountId)).sort().join(", ");
+  return stuck.length === observed.length
+    ? `every Codex account that could serve it needs reauthentication (${names})`
+    : `${stuck.length} of ${observed.length} Codex accounts that could serve it need reauthentication (${names})`;
+}
+
+/** Durable, operator-facing label for a pool account id; never the raw id or the email. */
+function gatedNativeAccountLabel(config: OcxConfig, accountId: string): string {
+  // Direct mode narrows eligibility to the native main credential, so this is the account most
+  // likely to be named here. `codexAuthContextLogLabel` calls it "main" everywhere else; hashing
+  // it into a `p`-prefixed digest would name the one account the operator cannot look up.
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) return "main";
+  const account = (config.codexAccounts ?? []).find(candidate => candidate.id === accountId);
+  return account ? codexAccountLogLabel(account) : fallbackCodexAccountLogLabel(accountId);
+}
+
+const warnedGatedNativeSuppression = new Set<string>();
+
+/** Test seam: the warn-once memory is process-global, so a case needs to be able to clear it. */
+export function resetGatedNativeSuppressionWarningsForTests(): void {
+  warnedGatedNativeSuppression.clear();
+}
+
+function warnGatedNativeSuppressedOnce(slug: string, reason: string): void {
+  const signature = `${slug}\u0000${reason}`;
+  if (warnedGatedNativeSuppression.has(signature)) return;
+  warnedGatedNativeSuppression.add(signature);
+  console.warn(
+    `[opencodex] catalog sync: ${slug} is not being offered because ${reason}. `
+      + "Sign in again to restore it.",
+  );
+}
+
 /**
  * Mescla o catálogo retido com os modelos visíveis e as configurações atuais,
  * incluindo os nomes nativos. Tenta preservar o backup original e usa a permissão
@@ -1777,6 +1848,20 @@ function writeRetainedCatalogSync({
   const unavailableGatedNativeSlugs = new Set([...ACCOUNT_GATED_NATIVE_OPENAI_MODELS].filter(slug => (
     !availableBareGatedNativeSlugs.has(slug)
   )));
+  // #4212: this set is the whole record of a model vanishing, and it is a set of strings that
+  // nothing downstream ever asks a question of. Explain it here, while the entitlement snapshot
+  // that produced it is still in scope, because after this point the model is simply absent and
+  // no later surface can tell "never entitled" apart from "the account broke this morning".
+  for (const slug of unavailableGatedNativeSlugs) {
+    const reason = gatedNativeReauthSuppressionReason({
+      snapshot: modelEntitlements,
+      slug,
+      eligibleAccountIds: bareEligibleAccountIds,
+      needsReauth: isAccountNeedsReauth,
+      label: accountId => gatedNativeAccountLabel(config, accountId),
+    });
+    if (reason) warnGatedNativeSuppressedOnce(slug, reason);
+  }
   const suppressedBareNativeSlugs = new Set([
     ...desktopAllowlistSuppressedNativeSlugs(config),
     ...unavailableGatedNativeSlugs,

package/src/codex/codex-write-lock.ts

@@ -66,7 +66,7 @@ export type CodexWriteLockRefusalReason =
 
 export type CodexWriteLockResult<T> =
   | { status: "acquired"; value: T; waitedMs: number; lockId: string }
-  | { status: "skipped"; reason: "desired_disabled" | "desired_enabled"; waitedMs: number }
+  | { status: "skipped"; reason: CodexWriteLockSkipReason; waitedMs: number }
   | { status: "busy"; reason: "deadline" | "cancelled"; retryable: true; waitedMs: number; lockId: string }
   | {
       status: "refused";
@@ -127,9 +127,18 @@ export interface CodexWriteCommitContext {
   readonly coordinator: CodexCoordinatorTransaction;
 }
 
+/**
+ * Why an under-lock policy re-read refused the write.
+ *
+ * `hub-gated` is not the user's switch: a hub declines to rewrite its own local clients, and
+ * reporting that as "integration is OFF" sent operators hunting for a toggle they never set
+ * (#4236).
+ */
+export type CodexWriteLockSkipReason = "desired_disabled" | "desired_enabled" | "hub-gated";
+
 /** A synchronous under-lock policy re-read proved the requested apply stale. */
 export class CodexWriteLockSkipped extends Error {
-  constructor(readonly reason: "desired_disabled" | "desired_enabled") {
+  constructor(readonly reason: CodexWriteLockSkipReason) {
     super(reason);
     this.name = "CodexWriteLockSkipped";
   }

package/src/codex/desired-state.ts

@@ -76,11 +76,57 @@ type LocalClientSyncConfig = Pick<
   "clientIntegrations" | "runtimeRole" | "unauthenticatedLoopbackListener"
 >;
 
-function localClientSyncAllowed(config: LocalClientSyncConfig): boolean {
+export function localClientSyncAllowed(config: LocalClientSyncConfig): boolean {
   return config.runtimeRole !== "hub"
     || config.unauthenticatedLoopbackListener?.enabled === true;
 }
 
+/**
+ * The one sentence every hub-gated skip says (#4236).
+ *
+ * The gate is a reasonable decision; reporting it as "Codex integration is OFF" was not. An
+ * operator whose `clientIntegrations` says nothing — or says `true` — was told their own switch
+ * was off, and `ocx restore back` went further and blamed a competing writer that did not
+ * exist. Name the gate and name the key that opens it.
+ */
+export const HUB_GATED_SKIP_MESSAGE =
+  "This machine is a hub; it does not rewrite its own Codex/Grok/Claude configs unless "
+  + "unauthenticatedLoopbackListener is enabled.";
+
+/** Why a local-client write was skipped. The gate outranks the toggle: it is the surprising one. */
+export type LocalClientSkipReason = "desired_disabled" | "hub-gated";
+
+/**
+ * "hub-gated" is claimed only when the toggle is ON and the gate is what stopped the write.
+ * With the toggle OFF the gate is moot: telling that operator to enable the loopback listener
+ * would send them to a key that cannot make the sync happen — the mirror image of the defect
+ * this reason exists to fix.
+ */
+export function localClientSkipReason(
+  config: LocalClientSyncConfig,
+  client: DurableIntentClientId = "codex",
+): LocalClientSkipReason {
+  return integrationEnabled(config, client) && !localClientSyncAllowed(config)
+    ? "hub-gated"
+    : "desired_disabled";
+}
+
+/**
+ * Pick the skip message for a snapshot: today's toggle text, or the hub-gate sentence.
+ *
+ * `hubSuffix` states what the hub-gated path still did (a catalog refresh, say) so the
+ * composed line stays as informative as the toggle one it replaces.
+ */
+export function localClientSkipMessage(
+  config: LocalClientSyncConfig,
+  integrationOffMessage: string,
+  hubSuffix?: string,
+  client: DurableIntentClientId = "codex",
+): string {
+  if (localClientSkipReason(config, client) !== "hub-gated") return integrationOffMessage;
+  return hubSuffix ? `${HUB_GATED_SKIP_MESSAGE} ${hubSuffix}` : HUB_GATED_SKIP_MESSAGE;
+}
+
 export function shouldSyncCodexOnStart(config: LocalClientSyncConfig): boolean {
   // A hub is a server for OTHER machines: it must not rewrite its own host's
   // Codex/Claude/Grok client configs on startup (interview decision Q6, and the

package/src/codex/inject-coordination.ts

@@ -8,7 +8,8 @@ import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 
 import { atomicWriteFile } from "../config";
-import type { CodexWriteLockResult } from "./codex-write-lock";
+import type { CodexWriteLockResult, CodexWriteLockSkipReason } from "./codex-write-lock";
+import { HUB_GATED_SKIP_MESSAGE } from "./desired-state";
 import { inspectCodexCoordinatorPath } from "./coordinator-doctor";
 import { JOURNAL_PATH } from "./journal";
 import { updateIntegrationRecord } from "./integration-record";
@@ -443,16 +444,20 @@ export function recomputeInjectWitness(options: {
 export function codexInjectLockOutcome(
   result: Exclude<CodexWriteLockResult<unknown>, { status: "acquired" }>,
 ): { success: false; message: string; retryable: boolean } | {
-  success: true; status: "skipped"; skippedReason: "desired_disabled" | "desired_enabled"; message: string;
+  success: true; status: "skipped"; skippedReason: CodexWriteLockSkipReason; message: string;
 } {
   if (result.status === "skipped") {
     return {
       success: true,
       status: "skipped",
       skippedReason: result.reason,
-      message: result.reason === "desired_disabled"
-        ? "Codex integration is OFF; no Codex config, catalog, cache, or history was changed."
-        : "Codex integration was re-enabled; native restore was skipped.",
+      // Three distinct facts, three sentences. The hub gate in particular must not borrow the
+      // toggle's wording — that is the phantom "integration is OFF" report from #4236.
+      message: result.reason === "hub-gated"
+        ? `${HUB_GATED_SKIP_MESSAGE} No Codex config, catalog, cache, or history was changed.`
+        : result.reason === "desired_disabled"
+          ? "Codex integration is OFF; no Codex config, catalog, cache, or history was changed."
+          : "Codex integration was re-enabled; native restore was skipped.",
     };
   }
   if (result.status === "busy") {

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

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/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/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)!;