@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/codex/quota-types.ts

@@ -1,4 +1,69 @@
 /** Quota wire/storage shapes. This leaf must not import credential or config owners. */
+export const MAIN_ACCOUNT_HARD_LOCK_PERCENT = 99;
+
+/**
+ * How recently a 100% burst reading must have been observed to exclude an account when it
+ * carries no reset timestamp (#3425). This is deliberately far tighter than the disk-hydration
+ * horizon so a persisted reading cannot strand a recovered account. Routing and UI share this
+ * value because both must answer whether the same short-window observation is still current.
+ */
+export const TERMINAL_SHORT_WINDOW_FRESHNESS_MS = 5 * 60_000;
+
+/**
+ * A window reading at or above this is a measured refusal, not a position on a scale.
+ *
+ * Separate from `CODEX_UNKNOWN_USAGE_SCORE` because they mean opposite things: unknown is
+ * "we have not observed this account", 100 is "we observed it and it is full". It lives on
+ * this leaf, next to the freshness window, because the dashboard has to answer the same
+ * question and cannot import the routing or disk-cache owners to do it.
+ */
+export const CODEX_EXHAUSTED_USAGE_PERCENT = 100;
+
+/**
+ * Above this a value is already milliseconds; at or below it, it is Unix seconds.
+ *
+ * Both reach storage, so the split has to live somewhere every reader can see. It lives on this
+ * leaf rather than beside the merge that uses it because the dashboard reads the same stored
+ * value and cannot import the disk-cache owner.
+ */
+const RESET_AT_SECONDS_MAX = 10_000_000_000;
+
+/** Normalize a stored reset instant to milliseconds. */
+export function resetAtToMs(resetAt: number): number {
+  return resetAt < RESET_AT_SECONDS_MAX ? resetAt * 1000 : resetAt;
+}
+
+/**
+ * A short-only reading that proves the account is blocked NOW.
+ *
+ * Routing and the dashboard's account-switch warning must answer this identically for the same
+ * snapshot, or the warning tells an operator an account is usable while the router refuses it.
+ * They did not: the dashboard compared a stored reset against `Date.now()` without normalizing
+ * units, so a seconds-form future reset looked expired there and live here, and it treated a
+ * fresh observation as sufficient even when an ELAPSED reset was present, where routing treats
+ * the reset as authoritative once it exists (#5045).
+ *
+ * Freshness is not optional in the reset-less branch. `getAccountQuota` performs no expiry
+ * check, partial updates carry a still-open short tuple forward, and disk hydration accepts a
+ * persisted reading for hours, so scoring exhausted from `shortPercent` alone would keep
+ * excluding an account whose burst window has since reset.
+ */
+export function isTerminalShortWindow(
+  quota: Pick<StoredAccountQuota, "shortPercent" | "shortResetAt" | "shortObservedAt">,
+  now: number,
+): boolean {
+  const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+  if (!finite(quota.shortPercent) || quota.shortPercent < CODEX_EXHAUSTED_USAGE_PERCENT) return false;
+  const resetAt = quota.shortResetAt;
+  if (!finite(resetAt) || resetAt <= 0) {
+    const observedAt = quota.shortObservedAt;
+    if (!finite(observedAt)) return false;
+    const age = now - observedAt;
+    return age >= 0 && age <= TERMINAL_SHORT_WINDOW_FRESHNESS_MS;
+  }
+  return resetAtToMs(resetAt) > now;
+}
+
 export type StoredAccountQuota = {
   weeklyPercent?: number;
   monthlyPercent?: number;

package/src/codex/quota.ts

@@ -8,8 +8,11 @@ import { getObservedMainQuotaIdentityKey, isMainQuotaWriterLive, type MainQuotaW
 
 import { CodexQuotaHistory, QUOTA_HISTORY_LIMITS, type QuotaHistoryWindow } from "./quota-history";
 import { isPoolQuotaWriterLive, poolQuotaHistoryIdentity } from "./account-store";
+import { CODEX_EXHAUSTED_USAGE_PERCENT, MAIN_ACCOUNT_HARD_LOCK_PERCENT, resetAtToMs } from "./quota-types";
 import type { PoolQuotaWriter, StoredAccountQuota, WhamUsageResponse, WhamUsageWindow } from "./quota-types";
+
 export type { StoredAccountQuota, WhamUsageResponse } from "./quota-types";
+export { CODEX_EXHAUSTED_USAGE_PERCENT } from "./quota-types";
 
 /** Disk snapshot: quota, private non-secret publication UUIDs and policy identity; never token-derived fingerprints. */
 const QUOTA_CACHE_FILENAME = "codex-quota-cache.json";
@@ -54,14 +57,13 @@ const WEEKLY_WINDOW_MIN_MINUTES = WEEKLY_WINDOW_MIN_SECONDS / 60;
  * Both units reach storage — `normalizeResetAt` does not scale, and the GUI disambiguates by
  * magnitude at read time — so a comparison written against one assumption is off by 1000x
  * against the other. In the seconds-read-as-milliseconds direction every reading looks like it
- * elapsed in 1970, which is a check that passes its own test and does nothing. Exported so
- * `isTerminalShortWindow` in routing.ts shares this one split instead of repeating the literal.
+ * elapsed in 1970, which is a check that passes its own test and does nothing.
+ *
+ * The split now lives on `./quota-types`, the leaf the dashboard can also import, because the
+ * dashboard was the reader that did not have it (#5045). Re-exported here so the existing
+ * callers of this module keep their import path.
  */
-const RESET_AT_SECONDS_MAX = 10_000_000_000;
-
-export function resetAtToMs(resetAt: number): number {
-  return resetAt < RESET_AT_SECONDS_MAX ? resetAt * 1000 : resetAt;
-}
+export { resetAtToMs };
 
 const accountQuota = new Map<string, StoredAccountQuota>();
 const quotaHistory = new CodexQuotaHistory();
@@ -75,14 +77,6 @@ function mayCommitAccountQuota(accountId: string, writerGeneration: number): boo
 // Valid upstream percentages are normalized to 0..100. Keep "unknown" outside that domain so an
 // actually exhausted account is still eligible for threshold rotation.
 export const CODEX_UNKNOWN_USAGE_SCORE = 101;
-/**
- * A window reading at or above this is a measured refusal, not a position on a scale.
- *
- * Separate from `CODEX_UNKNOWN_USAGE_SCORE` because they mean opposite things: unknown is
- * "we have not observed this account", 100 is "we observed it and it is full".
- */
-export const CODEX_EXHAUSTED_USAGE_PERCENT = 100;
-
 export function isCodexQuotaExhausted(
   quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "shortPercent"> | null,
   plan?: unknown,
@@ -146,7 +140,7 @@ export function isCompleteCodexQuotaRecoverySnapshot(
   return quota.monthlyIsPrimaryWindow === true && finitePercent(quota.monthlyPercent);
 }
 
-function finitePercent(value: number | undefined): boolean {
+function finitePercent(value: number | undefined): value is number {
   return typeof value === "number" && Number.isFinite(value);
 }
 
@@ -245,14 +239,20 @@ function shortResetHasElapsed(resetAt: number | undefined, now: number): boolean
   return resetAtToMs(resetAt) <= now;
 }
 
-/** Display/rotation carry expires; a reset clock cannot retract hard-lock evidence. */
+/** Display/rotation carry expires; a reset clock cannot retract blocking hard-lock evidence. */
 function assignCarriedShort(
   next: StoredAccountQuota,
   existing: StoredAccountQuota | undefined,
   now: number,
   policyEvidence = false,
 ): void {
-  if (!existing || (!policyEvidence && shortResetHasElapsed(existing.shortResetAt, now))) return;
+  if (!existing) return;
+  const existingShortPercent = existing.shortPercent;
+  const preserveBlockingEvidence = policyEvidence
+    && finitePercent(existingShortPercent)
+    && existingShortPercent >= MAIN_ACCOUNT_HARD_LOCK_PERCENT
+    && existingShortPercent <= 100;
+  if (!preserveBlockingEvidence && shortResetHasElapsed(existing.shortResetAt, now)) return;
   if (existing.shortPercent !== undefined) next.shortPercent = existing.shortPercent;
   if (existing.shortObservedAt !== undefined) next.shortObservedAt = existing.shortObservedAt;
   if (existing.shortResetAt !== undefined) next.shortResetAt = existing.shortResetAt;
@@ -363,7 +363,12 @@ function mergeAccountQuota(
     if (existing.monthlyIsPrimaryWindow === true) next.monthlyIsPrimaryWindow = true;
   }
 
-  const preserveKnownShort = policyEvidence && quota.shortPercent === undefined && finitePercent(existing?.shortPercent);
+  const existingShortPercent = existing?.shortPercent;
+  const preserveKnownShort = policyEvidence
+    && quota.shortPercent === undefined
+    && finitePercent(existingShortPercent)
+    && existingShortPercent >= MAIN_ACCOUNT_HARD_LOCK_PERCENT
+    && existingShortPercent <= 100;
   if (snapshotHasShort(quota) && !preserveKnownShort) {
     if (quota.shortPercent !== undefined) {
       next.shortPercent = quota.shortPercent;

package/src/codex/routing/cooldown-math.ts

@@ -1,12 +1,14 @@
 import {
   CODEX_EXHAUSTED_USAGE_PERCENT,
   CODEX_UNKNOWN_USAGE_SCORE,
-  resetAtToMs,
 } from "../quota";
 import { isThirtyDayOnlyCodexPlan } from "../plan";
+import { isTerminalShortWindow } from "../quota-types";
 import type { CodexQuotaScope } from "./health-store";
 import type { TransientProbeGrant } from "./thread-affinity";
 
+export { TERMINAL_SHORT_WINDOW_FRESHNESS_MS } from "../quota-types";
+
 export const CODEX_DEFAULT_QUOTA_COOLDOWN_MS = 60_000;
 export const CODEX_MAX_QUOTA_COOLDOWN_MS = 24 * 60 * 60_000;
 /**
@@ -25,14 +27,6 @@ export const CODEX_MAX_QUOTA_AVOID_MS = 6 * 60 * 60_000;
 /** Minimum gap between probe leases for one cooled-down account. */
 export const CODEX_QUOTA_PROBE_INTERVAL_MS = 5 * 60_000;
 export const CODEX_FAILURE_WINDOW_MS = 5 * 60_000;
-/**
- * How recently a 100% burst reading must have been OBSERVED to exclude an account when it
- * carries no reset timestamp (#3425). Deliberately far tighter than the 6h disk-hydration
- * horizon in `quota.ts`: shorter than any plausible five-hour burst window, so a persisted
- * reading can never strand a recovered account, and long enough that a snapshot taken at
- * admission is still fresh when selection reads it.
- */
-export const TERMINAL_SHORT_WINDOW_FRESHNESS_MS = 5 * 60_000;
 /** How long a transient failure keeps the account out of pool selection. */
 export const CODEX_TRANSIENT_SOFT_AVOID_MS = 30_000;
 export const CODEX_TRANSIENT_SOFT_AVOID_ESCALATION_MS = [
@@ -138,44 +132,11 @@ export function computeCodexUsageScore(quota: {
   return Math.max(...values);
 }
 
-/**
- * A short-only reading that proves the account is blocked NOW.
- *
- * Freshness is not optional. `getAccountQuota` performs no expiry check, partial updates
- * carry a still-open short tuple forward, and disk hydration accepts a persisted reading for
- * hours — so scoring 100 from `shortPercent` alone would keep excluding an account whose
- * five-hour window has since reset. Merge no longer carries an elapsed shortResetAt, but an
- * explicit incoming elapsed tuple is still stored, and a missing reset cannot be aged there.
- * That is #3029 pointed the other way: the issue is that
- * an exhausted account stays selected, and "a recovered account stays excluded" trades one
- * unusable pool for another.
- *
- * A reading with no `shortResetAt` cannot be aged, so it stays unknown. The conservative
- * direction here is the one that keeps an account selectable: a wrongly-selected account
- * fails one request, while a wrongly-excluded one is invisible until someone reads the pool
- * by hand.
- *
- * A missing reset can instead be aged by shortObservedAt (#3425). General updatedAt is not
- * sufficient: credit-only updates preserve the old short tuple but advance that timestamp.
- * Old disk snapshots without short-window provenance remain unknown.
- */
-function isTerminalShortWindow(
-  quota: { shortPercent?: number; shortResetAt?: number; shortObservedAt?: number },
-  now: number,
-): boolean {
-  if (typeof quota.shortPercent !== "number" || !Number.isFinite(quota.shortPercent)) return false;
-  if (quota.shortPercent < CODEX_EXHAUSTED_USAGE_PERCENT) return false;
-  const resetAt = quota.shortResetAt;
-  if (typeof resetAt !== "number" || !Number.isFinite(resetAt) || resetAt <= 0) {
-    const observedAt = quota.shortObservedAt;
-    if (typeof observedAt !== "number" || !Number.isFinite(observedAt)) return false;
-    const age = now - observedAt;
-    return age >= 0 && age <= TERMINAL_SHORT_WINDOW_FRESHNESS_MS;
-  }
-  // Seconds and milliseconds both reach storage, so the split lives in one place next to the
-  // merge that also ages a stored reset instant (`resetAtToMs`, src/codex/quota.ts).
-  return resetAtToMs(resetAt) > now;
-}
+// `isTerminalShortWindow` moved to ../quota-types, the leaf the dashboard can import. Routing
+// and the account-switch warning have to answer this identically for the same snapshot, and
+// they did not: see the note on the shared function (#5045). Its #3029 and #3425 reasoning —
+// why freshness is not optional, and why a reading with no reset and no observation stays
+// unknown rather than exhausted — moved with it.
 
 export function classifyCodexUpstreamOutcome(
   outcome: CodexUpstreamOutcome,

package/src/codex/routing/pin-drain.ts

@@ -0,0 +1,57 @@
+import type { OcxConfig } from "../../types";
+import { isCodexAccountPaused } from "../account-pause";
+import { isAccountNeedsReauth } from "../account-runtime-state";
+import type { CodexAccountUsabilityOptions } from "../account-usability";
+import { isCodexAccountUsable } from "../account-usability";
+import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
+import { hasCodexQuotaHeadroom } from "./selection";
+
+/** Why routing would drop a manual pin, or undefined when the pin survives. */
+export type CodexPinDrainReason = "needs_reauth" | "paused" | "unusable" | "quota_threshold";
+
+/**
+ * Would routing release a pin on this account the next time it resolves?
+ *
+ * This lives beside selection rather than inside `routing.ts` for the same reason
+ * {@link ./cache-affinity} does: it is a policy question asked by two callers that must answer
+ * identically. One is `releaseDrainedCodexAccountPin`, which acts on it. The other is
+ * `PUT /api/codex-auth/active`, which reports it.
+ *
+ * The two-step contradiction in #4521 is what happens when only the first exists. That route
+ * validates existence, pause and pending validation, answers 200, and says nothing about quota;
+ * the very next resolve runs this rule and drops the pin. The operator sees a setting accepted
+ * and then ignored. Reporting it from the same predicate, rather than from a second copy on the
+ * accepting surface, is what keeps the answer and the action from drifting -- a client-side
+ * re-derivation of the usage score has to track {@link ./cooldown-math} exactly, including the
+ * Free/Go plan windows and short-window freshness.
+ *
+ * Ordering is load-bearing. Cached reauth and configured pause are classified FIRST, because
+ * they hold for the main account even while its fenced native profile is unreadable; a
+ * selection-only caller then makes every later classification answer "no drain", so reading
+ * reauth after that guard would make a pin on a signed-out main look durable.
+ *
+ * This answers only whether the pin survives. It is not an admission check: the caller that
+ * acts on it releases a preference, and every involuntary release -- quota refusal, failover
+ * streak, cooldown, lost generation, affinity expiry -- is decided elsewhere and earlier.
+ */
+export function codexAccountPinDrainReason(
+  config: OcxConfig,
+  accountId: string,
+  selectionOptions?: Pick<
+    CodexAccountUsabilityOptions,
+    "nativeMainSelectionOnly" | "isMainAccountTokenLive"
+  >,
+  now: number = Date.now(),
+): CodexPinDrainReason | undefined {
+  if (isAccountNeedsReauth(accountId)) return "needs_reauth";
+  if (isCodexAccountPaused(config, accountId)) return "paused";
+  // Temporary drain deliberately forbids every native-main read. A pin on main cannot be
+  // classified by credential liveness or quota until the fenced profile is readable. Cached
+  // reauth and configured pause state were handled above.
+  if (accountId === MAIN_CODEX_ACCOUNT_ID && selectionOptions?.nativeMainSelectionOnly === true) {
+    return undefined;
+  }
+  if (!isCodexAccountUsable(config, accountId, selectionOptions)) return "unusable";
+  if (!hasCodexQuotaHeadroom(config, accountId, selectionOptions, now)) return "quota_threshold";
+  return undefined;
+}

package/src/codex/routing.ts

@@ -1,10 +1,12 @@
 import { saveConfigPreservingClaudeCode } from "../config";
-import { isCodexAccountGenerationLive } from "./account-store";
+import { isCodexAccountGenerationLive, registerCodexRefreshGenerationHandoff } from "./account-store";
+import { handOffThreadAffinityGeneration } from "./routing/thread-affinity";
 import { codexAccountLogLabel } from "./account-label";
 import { isCodexAccountPaused } from "./account-pause";
 import { clearCodexAccountPin, pinnedCodexAccountId } from "./account-priority";
 import { isCodexAccountUsable, type CodexAccountUsabilityOptions } from "./account-usability";
-import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
+import { markAccountNeedsReauth } from "./account-runtime-state";
+import { codexAccountPinDrainReason } from "./routing/pin-drain";
 import { POOL_KEY_CODEX, notePoolRotationFailure } from "./pool-rotation";
 import { getAccountQuota, isRetiredCodexSparkModel } from "./quota";
 import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
@@ -202,6 +204,13 @@ export {
   getEffectiveActiveCodexAccountId,
   isEffectiveCodexAccountPinned,
 } from "./routing/active-account";
+export { codexAccountPinDrainReason } from "./routing/pin-drain";
+export type { CodexPinDrainReason } from "./routing/pin-drain";
+
+// A shared refresh can outlive the request that opened it. Register the affinity
+// handoff with the flight so a detached G -> G+1 commit cannot strand bindings at G.
+registerCodexRefreshGenerationHandoff(handOffThreadAffinityGeneration);
+
 function hasConfiguredPoolAccount(
   config: OcxConfig,
   accountId: string,
@@ -392,7 +401,14 @@ function pickLineageServingAccount(
   selectionOptions?: CodexAccountUsabilityOptions,
   modelId?: string,
 ): { accountId: string; reason: CodexAffinityReason } | null {
-  if (lineage.parentConversationKey !== undefined) {
+  // Cohort keying (#4780) makes a tree share one key, so for a same-session family the parent's
+  // key IS this request's and the lookup below would re-ask a question the caller already
+  // answered by finding no binding entry. What remains is the case cohort keying cannot unify:
+  // a session-less chain whose parent this scope has not recorded, where the keys differ.
+  if (
+    lineage.parentConversationKey !== undefined
+    && lineage.parentConversationKey !== lineage.conversationKey
+  ) {
     const parent = lineageServingAccountId(
       lineage.parentConversationKey, config, now, quotaScope, selectionOptions, modelId,
     );
@@ -455,19 +471,7 @@ function releaseDrainedCodexAccountPin(
 ): void {
   const pinned = pinnedCodexAccountId(config);
   if (pinned === undefined) return;
-  const knownUnavailable = isAccountNeedsReauth(pinned) || isCodexAccountPaused(config, pinned);
-  if (knownUnavailable) {
-    clearCodexAccountPin(config);
-    saveConfigPreservingClaudeCode(config);
-    return;
-  }
-  // Temporary drain deliberately forbids every native-main read. A pin on main
-  // cannot be classified by credential liveness or quota until the fenced profile
-  // is readable. Cached reauth and configured pause state were handled above.
-  if (pinned === MAIN_CODEX_ACCOUNT_ID && selectionOptions?.nativeMainSelectionOnly === true) return;
-  const drained = !isCodexAccountUsable(config, pinned, selectionOptions)
-    || !hasCodexQuotaHeadroom(config, pinned, selectionOptions, now);
-  if (!drained) return;
+  if (codexAccountPinDrainReason(config, pinned, selectionOptions, now) === undefined) return;
   clearCodexAccountPin(config);
   saveConfigPreservingClaudeCode(config);
 }

package/src/codex/shim.ts

@@ -241,7 +241,7 @@ function backupPathFor(path: string): string {
  */
 function destroyedShimMessage(file: ShimFileState): string {
   const wrapper = existsSync(file.wrapperPath)
-    ? isShim(file.wrapperPath) ? "present but unusable" : "present but not an opencodex shim"
+    ? stableShimPathProbe(file.wrapperPath)?.prefix.includes(SHIM_MARKER) ? "present but unusable" : "present but not an opencodex shim"
     : "missing";
   const backup = existsSync(file.backupPath) ? "present" : "missing";
   const base = `Codex autostart shim not restored: wrapper ${wrapper} at ${file.wrapperPath}; original backup ${backup} at ${file.backupPath}.`;

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

@@ -905,8 +905,120 @@ export function hasCodexAgentModelFallbackField(role: string, codexHome = CODEX_
 }
 
 /** Roles whose TOML still carries `model_fallback`, including empty arrays. */
-export function scanCodexAgentRolesWithTomlModelFallback(codexHome = CODEX_HOME): string[] {
-  return listCodexAgentRoles(codexHome).filter(role => hasCodexAgentModelFallbackField(role, codexHome));
+export function scanCodexAgentRolesWithTomlModelFallback(
+  codexHome = CODEX_HOME,
+  onListError?: (cause: unknown) => void,
+): string[] {
+  try {
+    return listCodexAgentRoles(codexHome).filter(role => hasCodexAgentModelFallbackField(role, codexHome));
+  } catch (cause) {
+    onListError?.(cause);
+    return [];
+  }
+}
+
+const TOML_MODEL_KEY = /^\s*(?:model|"model"|'model')\s*=/;
+
+/**
+ * TOML-aware read of the root `model` pin, or null when there is none.
+ *
+ * Distinct from {@link readCodexAgentModel}, which matches one exact unindented double-quoted
+ * line. That is fine for resolving a fallback chain opencodex itself wrote, but it is the wrong
+ * question for a diagnostic: the file being judged was written by somebody else, so `model = 'x'`,
+ * an indented key, or a trailing comment are all valid TOML that Codex honours and that a
+ * stricter matcher would report as unpinned.
+ *
+ * It shares the scanner used for `model_fallback` for the reason that matters here: an imported
+ * role file keeps its instructions in a multiline string, and that string contains the very words
+ * this scan looks for. A line matcher would read a key out of prose.
+ *
+ * Table context is not tracked, matching the `model_fallback` parse. A `model` key under a later
+ * table header would be read as the root pin; Codex role files are flat in practice, and for a
+ * warning the conservative direction is to stay quiet.
+ */
+function parseTomlModelPin(content: string): string | null {
+  const lines = content.split(/\r?\n/);
+  const state: TomlScanState = { inMultilineString: null, arrayDepth: 0 };
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]!;
+    if (state.inMultilineString) {
+      const end = findTomlMultilineStringEnd(line, 0, state.inMultilineString[0]!);
+      if (end === -1) continue;
+      state.inMultilineString = null;
+      scanTomlLine(line.slice(end + 3), state);
+      continue;
+    }
+    if (state.arrayDepth === 0) {
+      const key = line.match(TOML_MODEL_KEY);
+      if (key) {
+        const rest = `${line.slice(key[0].length)}\n${lines.slice(i + 1).join("\n")}`;
+        let at = 0;
+        while (at < rest.length && (rest[at] === " " || rest[at] === "\t")) at += 1;
+        if (rest[at] !== '"' && rest[at] !== "'") return null;
+        const value = parseTomlStringAt(rest, at)?.value.trim() ?? "";
+        return value === "" ? null : value;
+      }
+    }
+    scanTomlLine(line, state);
+  }
+  return null;
+}
+
+/** Filename prefix opencodex gives the Claude agents it generates. */
+const OPENCODEX_DERIVED_ROLE_PREFIX = "ocx-";
+
+/**
+ * Body markers that survive the Codex desktop external-agent import.
+ *
+ * The import carries the generated Claude agent's instructions across, so both the provenance
+ * marker and the routing directive end up inside the role TOML. `ocx-route:` is matched without
+ * its `<!--` comment prefix on purpose: the same import text-replaces "Claude Code" with "Codex"
+ * inside that body, so anything around the directive should be assumed rewritten.
+ */
+const OPENCODEX_DERIVED_ROLE_MARKERS = ["generated-by: opencodex", "ocx-route:"] as const;
+
+/**
+ * Roles that look opencodex-derived but pin no model, so Codex runs them on the parent model.
+ *
+ * opencodex does not write Codex role TOMLs. These arrive when the Codex desktop external-agent
+ * import converts `~/.claude/agents/ocx-*.md` into `$CODEX_HOME/agents/ocx-*.toml`, dropping the
+ * `model:` frontmatter because a `claude-ocx-native--` id is not a Codex model and keeping only the
+ * instructions. The surviving `ocx-route` directive cannot make up the difference: it is honoured
+ * only on the Claude `/v1/messages` path and is inert on `/v1/responses`. So the role file names
+ * one model while every spawn runs on another, which is invisible until someone diffs
+ * `session_meta.agent_role` against `turn_context.model` (#4790).
+ *
+ * Detection is a heuristic for a warning, deliberately not an ownership claim. Nothing here
+ * authorizes writing to, repairing, or removing these files, and the marker-based ownership rules
+ * that govern the files opencodex does write are unchanged.
+ */
+export function scanOpencodexDerivedCodexAgentRolesWithoutModelPin(
+  codexHome = CODEX_HOME,
+  onListError?: (cause: unknown) => void,
+): string[] {
+  const findings: string[] = [];
+  let roles: string[];
+  try {
+    roles = listCodexAgentRoles(codexHome);
+  } catch (cause) {
+    onListError?.(cause);
+    return [];
+  }
+  for (const role of roles) {
+    let content: string;
+    try {
+      content = readFileSync(join(codexHome, "agents", `${role}.toml`), "utf8");
+    } catch {
+      // An unreadable file is not evidence of a missing pin.
+      continue;
+    }
+    const derived = role.startsWith(OPENCODEX_DERIVED_ROLE_PREFIX)
+      || OPENCODEX_DERIVED_ROLE_MARKERS.some(marker => content.includes(marker));
+    if (!derived) continue;
+    if (parseTomlModelPin(content) !== null) continue;
+    findings.push(role);
+  }
+  return findings.sort();
 }
 
 export function listCodexAgentRoles(codexHome = CODEX_HOME): string[] {