@bitkyc08/opencodex 2.86.0 → 2.87.0

package/src/codex/inject/routing-classify.ts

@@ -1,3 +1,4 @@
+import { isApprovedCodexProviderUrl } from "../provider-routing";
 import { existsSync, readFileSync } from "node:fs";
 import {
   hasInjectedCodexRouting,
@@ -54,7 +55,7 @@ export function classifyRoutingEndpoint(value: string): RoutingEndpointKind {
 }
 
 /** Classify actual routing dependency separately from opencodex ownership. */
-export function classifyCodexRouting(content: string): CodexRoutingKind {
+export function classifyCodexRouting(content: string, approvedProviderUrl?: (id: string, url: string) => boolean): CodexRoutingKind {
   const rootBaseUrl = rootTomlString(content, "openai_base_url");
   if (rootBaseUrl) {
     const endpoint = classifyRoutingEndpoint(rootBaseUrl);
@@ -74,7 +75,7 @@ export function classifyCodexRouting(content: string): CodexRoutingKind {
     if (providerBaseUrl) {
       const endpoint = classifyRoutingEndpoint(providerBaseUrl);
       if (endpoint === "unknown") return "unknown";
-      if (rootProvider === "opencodex") return "opencodex-local";
+      if (rootProvider === "opencodex" || endpoint === "local" && approvedProviderUrl?.(rootProvider, providerBaseUrl)) return "opencodex-local";
       return endpoint === "local" ? "custom-local" : "custom-remote";
     }
     if (
@@ -102,7 +103,7 @@ export function getCodexRoutingKind(): CodexRoutingKind {
   const path = CODEX_CONFIG_PATH;
   if (!existsSync(path)) return "native";
   try {
-    return classifyCodexRouting(readFileSync(path, "utf8"));
+    return classifyCodexRouting(readFileSync(path, "utf8"), isApprovedCodexProviderUrl);
   } catch {
     return "unknown";
   }

package/src/codex/inject.ts

@@ -1,3 +1,4 @@
+import { injectApprovedCodexProvider } from "./provider-routing";
 import { beginCodexWriteSection, cleanExternalProviderJournal, publishCodexArtifact } from "./inject/config-write-section";
 import { closeSync, existsSync, openSync, readFileSync, statSync } from "node:fs";
 import { dirname } from "node:path";
@@ -46,8 +47,8 @@ import {
   writeJournal,
 } from "./journal";
 import { HISTORY_RELABEL_STANDS_DOWN } from "./history-provider";
+import { formatApplyHistoryFailure } from "./inject/history-failure";
 import {
-  describeHistoryJobFailure,
   deriveCodexHistoryOperation,
   resolveCodexHistoryJobTarget,
   runCodexHistoryJob,
@@ -142,6 +143,8 @@ export interface CodexInjectResult {
   message: string;
   /** False when injection intentionally preserves configuration owned by another provider. */
   configApplied?: false;
+  /** True only after a successful configuration transaction changes config.toml bytes. */
+  configChanged?: boolean;
   /**
    * Structured read-only history preflight refusal; never parsed from display text.
    *
@@ -240,6 +243,10 @@ async function injectCodexConfigImpl(
   const rawContent = missingConfig ? "" : readFileSync(CODEX_CONFIG_PATH, "utf-8");
   const activeProvider = externalCodexModelProvider(rawContent);
   if (activeProvider) {
+    const approved = injectApprovedCodexProvider(activeProvider, routingTarget, options.beforeClientWrite ? () => runClientWriteGuard(options.beforeClientWrite) : undefined, options.validateOnly);
+    if (approved) {
+      return { success: true, configChanged: approved.configChanged, ...(options.validateOnly ? { configApplied: false as const } : {}), message: `Approved Codex provider ${tomlString(activeProvider)} routes through OpenCodex; provider identity and transport settings preserved.` };
+    }
     // A launcher may have journaled before the provider manager took ownership. Never let shutdown
     // replay that stale snapshot over externally managed config.
     if (!options.validateOnly) {
@@ -258,7 +265,7 @@ async function injectCodexConfigImpl(
         : {}),
       message:
         `⚠️ Codex routing NOT injected: config.toml selects the external model_provider ${tomlString(activeProvider)}.\n` +
-        `  OpenCodex preserves external provider configuration so existing ${tomlString(activeProvider)} session history stays visible.\n` +
+        `  OpenCodex preserves external provider configuration so existing ${tomlString(activeProvider)} session history stays visible.\n  To authorize URL-only management, run ocx codex-provider allow ${tomlString(activeProvider)} and confirm.\n` +
         `  Configure that provider for Responses passthrough at ${routingTarget.baseUrl}` +
         `${routingTarget.requiresAdmissionToken ? ` with x-opencodex-api-key from ${routingTarget.tokenEnv}` : ""}.\n` +
         `  For direct injection, switch to the built-in openai provider, remove any user-owned root openai_base_url, and rerun 'ocx start'.`,
@@ -717,6 +724,11 @@ async function injectCodexConfigImpl(
     releaseConfigWriteLock(configLock.handle);
     heldConfigWriteLock = undefined;
   }
+  // Both write paths have committed, including the coordinator's post-callback checks.
+  // Compare against the admitted original, not post-v1-reconcile input: the native
+  // feature transition is part of this transaction too. Refusals/rollbacks return
+  // above and must never publish this receipt. No filesystem reread after unlock.
+  const configChanged = Boolean(missingConfig) || effectivePlan.content !== rawContent;
   // Legacy mode still forward-tags history so re-tagged threads stay listable. Design B needs
   // the opposite: a one-time migration of previously re-tagged threads BACK to openai (restore
   // machinery; cheap no-op when there is nothing to migrate). The client-compaction opt-in keeps
@@ -799,6 +811,7 @@ async function injectCodexConfigImpl(
   if (effectivePlan.keptUserBaseUrl && effectivePlan.keepRootOverrideAlongsideTable) {
     return {
       success: true,
+      configChanged,
       ...(effectivePlan.nativeSubagentDefaultsWarning ? { nativeSubagentDefaultsWarning: effectivePlan.nativeSubagentDefaultsWarning } : {}),
       ...(effectivePlan.historyRelabelRefusal ? { historyPreflightFailureReason: effectivePlan.historyRelabelRefusal } : {}),
       message:
@@ -817,6 +830,7 @@ async function injectCodexConfigImpl(
   if (effectivePlan.keptUserBaseUrl) {
     return {
       success: true,
+      configChanged,
       ...(effectivePlan.nativeSubagentDefaultsWarning
         ? { nativeSubagentDefaultsWarning: effectivePlan.nativeSubagentDefaultsWarning }
         : {}),
@@ -839,6 +853,7 @@ async function injectCodexConfigImpl(
       : `Pointed Codex's built-in openai provider at the opencodex proxy (openai_base_url + realtime sideband override).\n`;
   return {
     success: true,
+    configChanged,
     ...(effectivePlan.nativeSubagentDefaultsWarning ? { nativeSubagentDefaultsWarning: effectivePlan.nativeSubagentDefaultsWarning } : {}),
     ...(effectivePlan.historyRelabelRefusal ? { historyPreflightFailureReason: effectivePlan.historyRelabelRefusal } : {}),
     message:
@@ -860,31 +875,7 @@ export function getCodexConfigPath(): string {
   return CODEX_CONFIG_PATH;
 }
 
-/**
- * Frame one failed apply history job honestly.
- *
- * A genuine lock keeps the established deferred/SKIPPED wording; any other
- * reason names itself instead of blaming the Codex app/IDE.
- */
-export function formatApplyHistoryFailure(outcome: CodexHistoryJobOutcome, legacyMode: boolean): string {
-  // A busy database is a deferral no matter which half observed it: the lock
-  // contended (blocked/busy), or the worker acquired the lock and then found
-  // SQLite busy (failed with a busy history reason). Only those keep the
-  // deferred headline; every other failure is a real "NOT changed".
-  const busy =
-    (outcome.kind === "blocked" && outcome.reason === "busy") ||
-    (outcome.kind === "failed" && outcome.historyFailureReason === "busy");
-  const partiallyChanged = outcome.kind === "failed"
-    && ((outcome.rows ?? 0) > 0 || (outcome.files ?? 0) > 0);
-  const headline = partiallyChanged
-    ? "Codex resume history changed but did not converge"
-    : legacyMode
-      ? "Codex resume history sync SKIPPED"
-      : busy
-      ? "Codex resume history metadata restore deferred"
-      : "Codex resume history NOT changed";
-  return `  ⚠️ ${headline}: ${describeHistoryJobFailure(outcome, "apply", legacyMode)}\n`;
-}
+export { formatApplyHistoryFailure };
 
 export {
   providerBaseHost,

package/src/codex/main-account-hard-lock.ts

@@ -1,4 +1,7 @@
 import type { OcxConfig } from "../types";
+import { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+import { codexAccountUsesRemainingQuota } from "./account-use-remaining";
+import { isDeclaredReasoningEffort } from "../reasoning-effort";
 import { getMainPolicyQuota } from "./quota";
 import { MAIN_ACCOUNT_HARD_LOCK_PERCENT, MAIN_ACCOUNT_HARD_LOCK_SHORT_PERCENT, MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT } from "./quota-types";
 
@@ -13,9 +16,35 @@ export interface MainAccountHardLockStatus {
   window?: "short" | "long";
 }
 
-type PolicyConfig = Pick<OcxConfig, "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds">;
+type PolicyConfig = Pick<OcxConfig, "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds" | "codexMainAccountHardLockFallback" | "codexUseRemainingQuotaAccountIds">;
+
+/** The reroute destination for requests the lock blocks, when one is configured and readable. */
+export interface MainAccountHardLockFallback {
+  model: string;
+  reasoningEffort?: string;
+}
+
+/**
+ * The configured fallback, or `undefined` when nothing qualifies. The dashboard row keeps
+ * the configured model while its switch is off, so `enabled: false` pauses the reroute
+ * without forgetting the destination. A malformed hand edit — blank or padded model,
+ * undeclared effort — disables the reroute entirely rather than degrading into a
+ * half-applied one: the request path must never guess which part of a broken setting to
+ * keep. This is the same disable-don't-widen reading the compaction override takes, and
+ * the load/write boundaries report the malformation separately.
+ */
+export function resolveMainAccountHardLockFallback(config: PolicyConfig | undefined): MainAccountHardLockFallback | undefined {
+  const raw = config?.codexMainAccountHardLockFallback;
+  if (!raw || raw.enabled === false) return undefined;
+  const model = typeof raw.model === "string" ? raw.model : "";
+  if (model.length === 0 || model !== model.trim() || /\s/.test(model)) return undefined;
+  if (raw.reasoningEffort !== undefined
+    && (typeof raw.reasoningEffort !== "string" || !isDeclaredReasoningEffort(raw.reasoningEffort))) return undefined;
+  return raw.reasoningEffort !== undefined ? { model, reasoningEffort: raw.reasoningEffort } : { model };
+}
 
 export function resolveMainAccountHardLockThresholds(config: PolicyConfig | undefined): { short: number; long: number } {
+  if (codexAccountUsesRemainingQuota(config, MAIN_CODEX_ACCOUNT_ID)) return { short: 100, long: 100 };
   const valid = (value: unknown, fallback: number): number => typeof value === "number"
     && Number.isInteger(value) && value >= MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT && value <= 100 ? value : fallback;
   const long = valid(config?.codexMainAccountHardLockThresholds?.long, MAIN_ACCOUNT_HARD_LOCK_PERCENT);

package/src/codex/native-profile-startup.ts

@@ -3,7 +3,7 @@ import { loadConfig } from "../config";
 import { initializeMainAccountPolicyBinding } from "./account-lifecycle";
 import { isMainAccountHardLockEnabled } from "./main-account-hard-lock";
 import { clearAccountNeedsReauth } from "./account-runtime-state";
-import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
+import { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
 import {
   probeNativeProfileRecoveryState,
   resolveNativeProfileContext,

package/src/codex/ocx-compaction-history.ts

@@ -26,6 +26,7 @@ import {
   isCompactionItemType,
   SUMMARY_PREFIX,
 } from "../responses/compaction";
+import { decodeRetainedCompaction } from "../responses/retained-compaction";
 import { resolveCodexHomeDir } from "./home";
 import { resolveCodexStateDbPath } from "./paths";
 
@@ -96,21 +97,22 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-function lowerCompactionItem(item: unknown): { item: unknown; changed: boolean } {
+function lowerCompactionItem(item: unknown): { items: unknown[]; changed: boolean } {
   if (!isRecord(item) || !isCompactionItemType(item.type)) {
-    return { item, changed: false };
+    return { items: [item], changed: false };
   }
   if (typeof item.encrypted_content !== "string") {
-    return { item, changed: false };
+    return { items: [item], changed: false };
   }
-  const summary = decodeCompactionSummary(item.encrypted_content);
-  if (summary === null) return { item, changed: false };
+  const retained = decodeRetainedCompaction(item.encrypted_content);
+  const summary = retained?.summary ?? decodeCompactionSummary(item.encrypted_content);
+  if (summary === null) return { items: [item], changed: false };
   return {
-    item: {
+    items: [{
       type: "message",
       role: "user",
       content: [{ type: "input_text", text: `${SUMMARY_PREFIX}\n${summary}` }],
-    },
+    }, ...(retained?.reasoning ?? []).map(text => ({ type: "message", role: "user", content: [{ type: "input_text", text }] }))],
     changed: true,
   };
 }
@@ -129,10 +131,10 @@ function rewriteJsonlLine(line: string): { line: string; replaced: number } {
   if (!Array.isArray(history)) return { line, replaced: 0 };
 
   let replaced = 0;
-  const replacementHistory = history.map(item => {
+  const replacementHistory = history.flatMap(item => {
     const lowered = lowerCompactionItem(item);
     if (lowered.changed) replaced += 1;
-    return lowered.item;
+    return lowered.items;
   });
   if (replaced === 0) return { line, replaced: 0 };
 
@@ -146,7 +148,7 @@ function rewriteJsonlLine(line: string): { line: string; replaced: number } {
 }
 
 /**
- * Convert OpenCodeX-owned `ocx1:` compaction items into ordinary replayable user messages.
+ * Convert OpenCodeX-owned `ocx1:`/`ocx2:` compaction items into ordinary replayable user messages.
  *
  * Only the authoritative `compacted.payload.replacement_history` snapshot is changed. Earlier
  * response-item events are historical output and are deliberately preserved byte-for-byte.

package/src/codex/paths.ts

@@ -1,4 +1,4 @@
-import { readFileSync, realpathSync, statSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { expandUserPath } from "../config";
 import { defaultCodexHome } from "./home";
@@ -144,3 +144,88 @@ export function readRootTomlString(content: string, key: string): string | null
 export function resolveCodexConfigPath(path: string): string {
   return isAbsolute(path) ? path : join(CODEX_HOME, path);
 }
+
+// ---------------------------------------------------------------------------
+// Active Codex home resolution.
+//
+// These resolve `CODEX_HOME` at call time rather than at import time, which is
+// what lets a test or a sibling-home probe point fixture state somewhere else
+// after this module has already loaded. They live here, next to the constants
+// they fall back to, so a caller that only needs a path never has to reach the
+// catalog parser.
+// ---------------------------------------------------------------------------
+
+export function samePath(a: string, b: string): boolean {
+  const left = resolve(a);
+  const right = resolve(b);
+  return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+export function activeCodexHome(): string | null {
+  const raw = process.env.CODEX_HOME?.trim();
+  if (!raw) return null;
+  const path = resolve(expandUserPath(raw));
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return path;
+  }
+}
+
+export function activeCodexConfigPath(): string {
+  const home = activeCodexHome();
+  return home ? join(home, "config.toml") : CODEX_CONFIG_PATH;
+}
+
+export function activeDefaultCatalogPath(): string {
+  const home = activeCodexHome();
+  return home ? join(home, "opencodex-catalog.json") : DEFAULT_CATALOG_PATH;
+}
+
+export function activeCodexModelsCachePath(): string {
+  const home = activeCodexHome();
+  return home ? join(home, "models_cache.json") : CODEX_MODELS_CACHE_PATH;
+}
+
+export function resolveActiveCodexConfigPath(path: string): string {
+  const home = activeCodexHome();
+  return home ? resolve(home, path) : resolveCodexConfigPath(path);
+}
+
+export function isDefaultCatalogPath(path: string): boolean {
+  return samePath(path, activeDefaultCatalogPath());
+}
+
+export function readCodexCatalogPath(): string {
+  const home = activeCodexHome();
+  if (home) return readCodexCatalogPathForHome(home);
+  try {
+    const configPath = activeCodexConfigPath();
+    if (existsSync(configPath)) {
+      const toml = readFileSync(configPath, "utf-8");
+      const path = readRootTomlString(toml, "model_catalog_json");
+      if (path) return resolveActiveCodexConfigPath(path);
+    }
+  } catch { /* ignore */ }
+  return activeDefaultCatalogPath();
+}
+
+/**
+ * Resolve the configured catalog without consulting ambient CODEX_HOME again.
+ *
+ * `configText` is for a caller that has already read that same `config.toml` under
+ * its own constraints - the prompt-text probe reads it bounded, on the request
+ * thread - so resolving the catalog does not cost a second, unbounded read of the
+ * file the caller is holding. Omitting it keeps the original behaviour.
+ */
+export function readCodexCatalogPathForHome(codexHome: string, configText?: string): string {
+  try {
+    const configPath = join(codexHome, "config.toml");
+    if (configText !== undefined || existsSync(configPath)) {
+      const toml = configText ?? readFileSync(configPath, "utf-8");
+      const path = readRootTomlString(toml, "model_catalog_json");
+      if (path) return resolve(codexHome, path);
+    }
+  } catch { /* ignore */ }
+  return join(codexHome, "opencodex-catalog.json");
+}

package/src/codex/provider-routing.ts

@@ -0,0 +1,174 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { loadConfig } from "../config";
+import { shouldSyncCodexOnStart } from "./desired-state";
+import { atomicWriteFile } from "../config/atomic-write";
+import { withConfigMutationLockSync } from "../config/mutation-lock";
+import { getConfigDir } from "../config/paths";
+import { assertCodexHomeOwner } from "./codex-home-owner";
+import { ConfigWriteLockRefusal, publishConfigWriteTarget, watchConfigWriteTargets, withConfigWriteLockHeld, type LockHandle } from "./config-write-lock";
+import { providerTableStart } from "./injected-marker";
+import { CODEX_CONFIG_PATH, getCodexHome, tomlString } from "./paths";
+import { rootSourceLines, sourceAssignment, sourceText } from "./toml-source-lines";
+import { JOURNAL_PATH, removeJournal } from "./journal";
+import { externalCodexModelProvider } from "./inject/config-toml";
+import { readBoundedCodexConfig } from "./inject/bounded-config-reader";
+import { isLoopbackHostname } from "./loopback-target";
+import { validateCodexRoutingTarget, type CodexRoutingTarget } from "./inject/routing-target";
+
+const approval = z.object({ original: z.string(), originalUrl: z.string().url(), managedUrls: z.array(z.string().url()).max(2) }).strict();
+const recordSchema = z.object({ version: z.literal(1), codexHome: z.string(), providers: z.record(z.string(), approval) }).strict();
+type RoutingRecord = z.infer<typeof recordSchema>;
+type Approval = z.infer<typeof approval>;
+let beforePublishForTests: (() => void) | undefined;
+export function setBeforeProviderRoutingPublishForTests(hook: typeof beforePublishForTests): void { beforePublishForTests = hook; }
+
+function recordPath(): string {
+  const homeId = createHash("sha256").update(getCodexHome()).digest("hex");
+  return join(getConfigDir(), `codex-provider-routing-${homeId}.json`);
+}
+
+function readRecord(): RoutingRecord {
+  const content = readBoundedCodexConfig(recordPath());
+  if (content === null) return { version: 1, codexHome: getCodexHome(), providers: {} };
+  const record = recordSchema.parse(JSON.parse(content));
+  if (record.codexHome !== getCodexHome()) throw new Error("Codex provider routing consent belongs to another home.");
+  for (const saved of Object.values(record.providers)) {
+    const parsed = Bun.TOML.parse(saved.original) as Record<string, unknown>;
+    if (Object.keys(parsed).length !== 1 || parsed.base_url !== saved.originalUrl
+      || saved.managedUrls.some(url => !isLoopbackHostname(new URL(url).hostname))) {
+      throw new Error("Codex provider routing recovery evidence is invalid; existing files were preserved.");
+    }
+  }
+  return record;
+}
+
+/** Only regular Responses provider tables with no separate credential transport are eligible. */
+function providerUrl(content: string, id: string, checkCredentials = true) {
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(id) || ["__proto__", "constructor", "prototype", "openai", "opencodex", "ollama", "lmstudio"].includes(id)) {
+    throw new Error("Select a custom provider ID using letters, digits, hyphens or underscores.");
+  }
+  const parsed = Bun.TOML.parse(content) as Record<string, unknown>;
+  const table = (parsed.model_providers as Record<string, Record<string, unknown>> | undefined)?.[id];
+  if (!table || checkCredentials && ((table.wire_api !== undefined && table.wire_api !== "responses")
+    || table.requires_openai_auth !== true
+    || ["env_key", "experimental_bearer_token", "auth", "http_headers", "env_http_headers"].some(key => Object.hasOwn(table, key)))) {
+    throw new Error("Routing consent requires a Responses provider using OpenAI authentication without custom credentials or headers.");
+  }
+  const { bom, lines } = rootSourceLines(content);
+  const start = providerTableStart(lines.map(line => line.structural ? line.text : ""), id);
+  if (start < 0) throw new Error("Routing consent requires an explicit provider table.");
+  let end = start + 1;
+  while (end < lines.length && !(lines[end]!.structural && /^\s*\[/.test(lines[end]!.text))) end++;
+  for (let i = start + 1; i < end; i++) {
+    const field = sourceAssignment(lines, i, end);
+    if (field?.key !== "base_url") continue;
+    if (typeof field.value !== "string") break;
+    const url = new URL(field.value);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) break;
+    return { url: field.value, assignment: field.text, replace: (text: string) =>
+      bom + sourceText(lines.slice(0, field.start)) + text + lines[field.end - 1]!.eol + sourceText(lines.slice(field.end)) };
+  }
+  throw new Error("Routing consent requires a credential-free HTTP(S) base_url assignment.");
+}
+
+function inWriteSection<T>(run: (held: LockHandle, content: string, record: RoutingRecord) => T): T {
+  assertCodexHomeOwner(getCodexHome());
+  const result = withConfigWriteLockHeld(CODEX_CONFIG_PATH, undefined, held => {
+    watchConfigWriteTargets(held, [CODEX_CONFIG_PATH, recordPath(), JOURNAL_PATH]);
+    const content = readFileSync(CODEX_CONFIG_PATH, "utf8");
+    return run(held, content, readRecord());
+  });
+  if (!result.ok) throw new ConfigWriteLockRefusal(result);
+  return result.value;
+}
+
+function publish(path: string, content: string, held: LockHandle): void {
+  publishConfigWriteTarget(CODEX_CONFIG_PATH, held, path, (destination, hooks) => atomicWriteFile(destination, content, undefined, hooks));
+}
+
+function save(record: RoutingRecord, held: LockHandle): void {
+  publish(recordPath(), JSON.stringify(record, null, 2) + "\n", held);
+}
+
+/** Read-only ownership evidence: consent alone never claims a URL we did not publish. */
+export function isApprovedCodexProviderUrl(id: string, url: string): boolean {
+  const record = readRecord();
+  return Object.hasOwn(record.providers, id) && record.providers[id]!.managedUrls.includes(url);
+}
+
+export function approvedCodexProviders(): string[] {
+  return Object.keys(readRecord().providers);
+}
+
+/** Capture the exact source before asking; commit refuses a changed provider after the prompt. */
+export function previewCodexProviderConsent(id: string): string {
+  return providerUrl(readFileSync(CODEX_CONFIG_PATH, "utf8"), id).assignment;
+}
+
+export function allowCodexProviderRouting(id: string, expected: string): void {
+  inWriteSection((held, content, record) => {
+    const field = providerUrl(content, id);
+    if (field.assignment !== expected) throw new Error("Provider changed after confirmation; review it and retry.");
+    if (Object.hasOwn(record.providers, id)) throw new Error("Provider is already approved; revoke it before granting new consent.");
+    record.providers[id] = { original: field.assignment, originalUrl: field.url, managedUrls: [] };
+    save(record, held);
+  });
+}
+
+function accepts(fieldUrl: string, saved: Approval): boolean {
+  return fieldUrl === saved.originalUrl || saved.managedUrls.includes(fieldUrl);
+}
+
+/** Called by start/sync, never prompts and never broadens the approved provider set. */
+export function injectApprovedCodexProvider(id: string, target: CodexRoutingTarget, beforeWrite?: () => void, validateOnly = false): false | { configChanged: boolean } {
+  return inWriteSection((held, content, record) => {
+    if (!Object.hasOwn(record.providers, id)) return false;
+    const apply = () => {
+      target = validateCodexRoutingTarget(target);
+      if (target.requiresAdmissionToken || target.desktopAuthless || target.clientCompaction || !isLoopbackHostname(new URL(target.baseUrl).hostname)) {
+        throw new Error("Approved custom providers support only authenticated Codex on a local loopback proxy without client compaction.");
+      }
+      if (externalCodexModelProvider(content) !== id) throw new Error("Active provider changed; routing was not applied.");
+      const field = providerUrl(content, id), saved = record.providers[id]!;
+      if (!accepts(field.url, saved)) throw new Error("Approved provider base_url changed outside OpenCodex; revoke and approve it again.");
+      if (validateOnly) return { configChanged: false };
+      beforeWrite?.();
+      if (!shouldSyncCodexOnStart(loadConfig())) return false;
+      if (readFileSync(CODEX_CONFIG_PATH, "utf8") !== content) throw new Error("Codex config changed before publication; retry sync.");
+      publishConfigWriteTarget(CODEX_CONFIG_PATH, held, JOURNAL_PATH, (_destination, hooks) => removeJournal(hooks));
+      if (field.url === target.baseUrl) return { configChanged: false };
+      // Write recovery evidence first. Both the previous and candidate URL remain restorable
+      // if publication fails or the process exits between these two atomic renames.
+      saved.managedUrls = [...new Set([field.url, target.baseUrl])].filter(url => url !== saved.originalUrl);
+      save(record, held);
+      beforePublishForTests?.();
+      publish(CODEX_CONFIG_PATH, field.replace(`base_url = ${tomlString(target.baseUrl)}`), held);
+      return { configChanged: true };
+    };
+    return validateOnly ? apply() : withConfigMutationLockSync(apply);
+  });
+}
+
+/** Restore only our URLs; unrelated edits and provider IDs/history are never rewritten. */
+export function restoreApprovedCodexProviders(revokeId?: string): boolean {
+  const ids = approvedCodexProviders();
+  if (revokeId !== undefined && !ids.includes(revokeId)) throw new Error("Provider has no routing consent to revoke.");
+  if (!ids.length) return false;
+  return inWriteSection((held, content, record) => {
+    let next = content;
+    for (const id of revokeId === undefined ? Object.keys(record.providers) : [revokeId]) {
+      const saved = record.providers[id]!;
+      const parsed = Bun.TOML.parse(next) as Record<string, unknown>;
+      const table = (parsed.model_providers as Record<string, Record<string, unknown>> | undefined)?.[id];
+      if (!table || !saved.managedUrls.includes(table.base_url as string)) continue;
+      const field = providerUrl(next, id, false);
+      if (saved.managedUrls.includes(field.url)) next = field.replace(saved.original);
+    }
+    if (next !== content) publish(CODEX_CONFIG_PATH, next, held);
+    if (revokeId !== undefined) { delete record.providers[revokeId]; save(record, held); }
+    return next !== content;
+  });
+}

package/src/codex/refresh.ts

@@ -1,12 +1,12 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { invalidateCodexModelsCache, syncCatalogModels } from "./catalog";
+import { invalidateCodexModelsCache, syncCatalogModels } from "./catalog/retained-sync";
 import type { ComboCatalogOmission } from "./catalog/aggregation";
 import { getCodexHome } from "./paths";
 import { withCatalogWriteSerialization, CatalogWritePermitRefusal } from "./catalog-write-serialization";
 import { replaceCodexModelsCache } from "./internal/catalog-writer";
 import type { OcxConfig } from "../types";
-import type { CodexCatalogSyncOptions } from "./catalog/sync";
+import type { CodexCatalogSyncOptions } from "./catalog/retained-sync";
 
 export interface CodexCatalogRefreshResult {
   added: number;

package/src/codex/routing/health-store.ts

@@ -1,6 +1,6 @@
 import { isCodexAccountGenerationLive } from "../account-store";
 import { NATIVE_RESERVE_MODEL } from "../catalog/native-models";
-import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
+import { MAIN_CODEX_ACCOUNT_ID } from "../account-id";
 import { POOL_KEY_CODEX } from "../pool-rotation";
 import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
 import type { OcxConfig } from "../../types";

package/src/codex/routing/selection.ts

@@ -1,7 +1,8 @@
 import { getEffectiveCodexAutoSwitchThreshold } from "../account-auto-switch";
 import { codexAccountUsesCreditsAfterLimit, isCodexAccountHeldForCredits } from "../account-credit-use";
 import { isCodexAccountPaused } from "../account-pause";
-import { codexAccountPriorityLookup, pinnedCodexAccountId } from "../account-priority";
+import { pinnedCodexAccountId } from "../account-priority";
+import { codexSelectionPriorityLookup } from "../account-preservation";
 import { isSelectableCodexPoolAccount } from "../account-id";
 import { isAccountNeedsReauth } from "../account-runtime-state";
 import { isCodexAccountUsable, type CodexAccountUsabilityOptions } from "../account-usability";
@@ -248,7 +249,7 @@ export function getEligiblePoolAccounts(
   const pinned = pinnedCodexAccountId(config);
   return selectPriorityTier(
     withoutModelDeniedAccounts(ids, selectionOptions?.deniedModelAccountIds, pinned),
-    codexAccountPriorityLookup(config),
+    codexSelectionPriorityLookup(config),
     id => hasCodexQuotaHeadroom(config, id, selectionOptions, now),
     pinned,
   );
@@ -767,7 +768,7 @@ export function pickPriorityPreemption(
     && eligible.includes(pinned)
     && hasCodexQuotaHeadroom(config, pinned, selectionOptions, now)
   ) return null;
-  const priorityOf = codexAccountPriorityLookup(config);
+  const priorityOf = codexSelectionPriorityLookup(config);
   if (priorityOf(eligible[0]!) <= priorityOf(active)) return null;
   // Members without headroom are in the tier only because a sibling has some;
   // picking one would hand the request straight back to a drained account.

package/src/codex/routing/thread-affinity.ts

@@ -1,5 +1,5 @@
 import { isCodexAccountGenerationLive, readCodexAccountRecord } from "../account-store";
-import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
+import { MAIN_CODEX_ACCOUNT_ID } from "../account-id";
 import { retainedUtf8Bytes } from "../../lib/admission";
 import { clearAllCodexPoolRefreshFailures } from "../pool-refresh-backoff";
 import type { CodexThreadLineage } from "../lineage";

package/src/codex/signed-in-identity.ts

@@ -0,0 +1,43 @@
+import { extractEmail, inspectChatGptDomainClaim } from "../oauth/chatgpt";
+import type { CodexTokens } from "./auth-collision";
+
+export type CodexLoginIdentity = Readonly<{ accountId: string; email: string }>;
+let observed: CodexLoginIdentity | undefined;
+
+export function codexLoginIdentity(accountId: unknown, email: unknown): CodexLoginIdentity | undefined {
+  const member = typeof email === "string" ? email.trim().toLowerCase() : "";
+  const workspace = typeof accountId === "string" ? accountId.trim() : "";
+  return workspace && member ? { accountId: workspace, email: member } : undefined;
+}
+
+/** Undefined is insufficient evidence; null means conflicting or malformed token evidence. */
+export function codexTokenIdentity(tokens: CodexTokens): CodexLoginIdentity | undefined | null {
+  if (typeof tokens.access_token !== "string" || typeof tokens.account_id !== "string"
+    || (tokens.id_token !== undefined && typeof tokens.id_token !== "string")) return null;
+  const claims = [tokens.id_token, tokens.access_token]
+    .filter((token): token is string => typeof token === "string")
+    .map(inspectChatGptDomainClaim);
+  if (claims.some(claim => claim.kind === "invalid")) return null;
+  const claimIds = claims.flatMap(claim => claim.kind === "valid" ? [claim.accountId] : []);
+  const accountId = tokens.account_id.trim() || claimIds[0];
+  if (claimIds.some(claim => claim !== accountId)) return null;
+  const emails = new Set([extractEmail(tokens.id_token), extractEmail(undefined, tokens.access_token)]
+    .flatMap(email => email?.trim() ? [email.trim().toLowerCase()] : []));
+  if (emails.size > 1) return null;
+  return codexLoginIdentity(accountId, [...emails][0]);
+}
+
+/** Publish only from an existing physical-login observation, never an incoming bearer. */
+export function observeSignedInCodexIdentity(tokens?: CodexTokens): void {
+  if (!tokens) { observed = undefined; return; }
+  const next = codexTokenIdentity(tokens);
+  // Conflicting claims can be a partial external write, never proof of a new login.
+  if (next !== null) observed = next;
+}
+
+/** Routing reads memory only, including while the native profile is fenced. */
+export function getSignedInCodexIdentity(): CodexLoginIdentity | undefined { return observed; }
+
+export function sameCodexLogin(a: CodexLoginIdentity, b: CodexLoginIdentity | undefined): boolean {
+  return a.accountId === b?.accountId && a.email === b.email;
+}

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

@@ -591,7 +591,7 @@ export function maybePrimeSubagentQuota(
       if (subagentQuotaPrimeForTests) {
         await subagentQuotaPrimeForTests(config, "subagent-spawn");
       } else {
-        const { primeCodexPoolQuotas } = await import("./auth-api");
+        const { primeCodexPoolQuotas } = await import("./auth-api/pool-mode-gate");
         await primeCodexPoolQuotas(config, "subagent-spawn");
       }
       quotaPrimedAt.set("global", Date.now());