@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/codex/native-main-refresh-mode.ts

@@ -0,0 +1,217 @@
+/**
+ * Who refreshes the native main ChatGPT credential (#2999).
+ *
+ * Codex owns `CODEX_HOME/auth.json`. It rewrites the file in place and serializes its own
+ * refreshes only inside one process, so any second writer can race it, and a lost race
+ * retires the grant. In "codex" mode OpenCodex never writes the file: it asks the Codex
+ * binary to refresh through `app-server` `getAuthStatus` and uses the bearer that call
+ * returns. In "opencodex" mode the guarded writer in `main-account.ts` refreshes as before.
+ *
+ * The default is "codex" only when a version-checked binary is available. Without one, or
+ * when the operator sets `nativeMainRefresh: "opencodex"`, the guarded writer stays.
+ */
+import { codexExecInvocation } from "./exec-invocation";
+import { resolveCodexHomeDir } from "./home";
+import { compareCodexVersions, displayCodexRuntimePath, resolveCodexRuntimeAsync } from "./runtime";
+import type { ResolveCodexRuntimeResult } from "./runtime";
+import { isTestHomeGuardArmed } from "../lib/test-home-guard";
+import type { OcxConfig } from "../types/config";
+
+export type NativeMainRefreshMode = "codex" | "opencodex";
+
+/**
+ * Supported floor for app-server `getAuthStatus` with `includeToken`/`refreshToken` that
+ * withholds the token after a permanent refresh failure, the only reauth signal on the wire.
+ * Releases from about 0.118 already withhold it; 0.130.0 is the first with the handler in
+ * `request_processors/account_processor.rs` and is chosen conservatively.
+ */
+export const CODEX_AUTH_STATUS_MIN_VERSION = "0.130.0";
+
+export type NativeMainRefreshReason =
+  | "codex-compatible"
+  | "configured-opencodex"
+  | "codex-missing"
+  | "codex-too-old"
+  | "test-guard";
+
+export interface NativeMainRefreshResolution {
+  readonly mode: NativeMainRefreshMode;
+  readonly configured: NativeMainRefreshMode | "auto";
+  readonly reason: NativeMainRefreshReason;
+  readonly command?: string;
+  readonly version?: string | null;
+}
+
+export interface CodexAuthStatus {
+  readonly authMethod: string | null;
+  readonly authToken: string | null;
+  readonly requiresOpenaiAuth: boolean | null;
+}
+
+export class CodexAuthStatusError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CodexAuthStatusError";
+  }
+}
+
+let resolutionForTests: NativeMainRefreshResolution | null = null;
+
+/** Test seam: pin the resolution so no test spawns the developer's real Codex binary. */
+export function setNativeMainRefreshResolutionForTests(value: NativeMainRefreshResolution | null): void {
+  resolutionForTests = value;
+}
+
+function configuredMode(config: Pick<OcxConfig, "nativeMainRefresh"> | null | undefined): NativeMainRefreshMode | "auto" {
+  const value = config?.nativeMainRefresh;
+  return value === "codex" || value === "opencodex" ? value : "auto";
+}
+
+export async function resolveNativeMainRefreshMode(
+  config: Pick<OcxConfig, "nativeMainRefresh"> | null | undefined,
+  deps: { resolveRuntime?: () => Promise<ResolveCodexRuntimeResult> } = {},
+): Promise<NativeMainRefreshResolution> {
+  if (resolutionForTests) return resolutionForTests;
+  const configured = configuredMode(config);
+  if (configured === "opencodex") return { mode: "opencodex", configured, reason: "configured-opencodex" };
+  // Tests run against throwaway CODEX_HOMEs; delegating would spawn the real binary.
+  if (!deps.resolveRuntime && isTestHomeGuardArmed()) return { mode: "opencodex", configured, reason: "test-guard" };
+  const resolved = await (deps.resolveRuntime ?? (() => resolveCodexRuntimeAsync({ discoverAlternatives: false })))();
+  const { command, version, source } = resolved.runtime;
+  if (source === "fallback" && version === null) {
+    return { mode: "opencodex", configured, reason: "codex-missing" };
+  }
+  if (version === null || compareCodexVersions(version, CODEX_AUTH_STATUS_MIN_VERSION) < 0) {
+    return { mode: "opencodex", configured, reason: "codex-too-old", command, version };
+  }
+  return { mode: "codex", configured, reason: "codex-compatible", command, version };
+}
+
+/**
+ * One `getAuthStatus` round trip against a short-lived `codex app-server` on stdio.
+ *
+ * `model_provider="openai"` is forced because an authless Desktop injection sets
+ * `requires_openai_auth = false` on the OpenCodex provider, and then the server reports no
+ * credential at all. The process inherits CODEX_HOME so it reads the same login (file or
+ * keyring) Codex itself uses.
+ */
+export async function requestCodexAuthStatus(
+  command: string,
+  options: { refresh: boolean; signal: AbortSignal; codexHome?: string },
+): Promise<CodexAuthStatus> {
+  if (options.signal.aborted) throw options.signal.reason;
+  const invocation = codexExecInvocation(command, ["-c", 'model_provider="openai"', "app-server"]);
+  let proc: ReturnType<typeof Bun.spawn<"pipe", "pipe", "ignore">>;
+  try {
+    proc = Bun.spawn([invocation.file, ...invocation.args], {
+      env: { ...process.env, CODEX_HOME: options.codexHome ?? resolveCodexHomeDir() },
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "ignore",
+      windowsVerbatimArguments: invocation.options.windowsVerbatimArguments,
+      windowsHide: true,
+    });
+  } catch (cause) {
+    throw new CodexAuthStatusError("could not start codex app-server", { cause });
+  }
+  // Abort settles the call by itself. Waiting for stdout to close would hang on a child that
+  // ignores SIGTERM or a launcher descendant that keeps the pipe open.
+  let onAbort = () => {};
+  const aborted = new Promise<never>((_, reject) => {
+    onAbort = () => reject(options.signal.reason);
+    options.signal.addEventListener("abort", onAbort, { once: true });
+  });
+  aborted.catch(() => { /* observed through the race below */ });
+  try {
+    const send = (message: unknown) => proc.stdin.write(JSON.stringify(message) + "\n");
+    send({ id: 1, method: "initialize", params: { clientInfo: { name: "opencodex", title: null, version: "0" } } });
+    send({ method: "initialized" });
+    send({ id: 2, method: "getAuthStatus", params: { includeToken: true, refreshToken: options.refresh } });
+    await Promise.race([proc.stdin.flush(), aborted]);
+    const response = await Promise.race([readResponse(proc.stdout, 2), aborted]);
+    if (options.signal.aborted) throw options.signal.reason;
+    return parseAuthStatus(response);
+  } catch (cause) {
+    if (options.signal.aborted) throw options.signal.reason;
+    if (cause instanceof CodexAuthStatusError) throw cause;
+    throw new CodexAuthStatusError("codex app-server getAuthStatus failed", { cause });
+  } finally {
+    options.signal.removeEventListener("abort", onAbort);
+    stopAppServer(proc);
+  }
+}
+
+const APP_SERVER_KILL_GRACE_MS = 2_000;
+
+/** SIGTERM now, SIGKILL if the child is still alive after a grace period; never awaited. */
+function stopAppServer(proc: { stdin: { end(): unknown }; kill(signal?: number | NodeJS.Signals): void; exited: Promise<number> }): void {
+  try { proc.stdin.end(); } catch { /* already closed */ }
+  let exited = false;
+  void proc.exited.then(() => { exited = true; }, () => { exited = true; });
+  try { proc.kill("SIGTERM"); } catch { /* already gone */ }
+  const timer = setTimeout(() => {
+    if (!exited) try { proc.kill("SIGKILL"); } catch { /* already gone */ }
+  }, APP_SERVER_KILL_GRACE_MS);
+  (timer as { unref?: () => void }).unref?.();
+}
+
+const MAX_APP_SERVER_LINE_BYTES = 1_048_576;
+
+async function readResponse(stream: ReadableStream<Uint8Array>, id: number): Promise<Record<string, unknown>> {
+  const decoder = new TextDecoder();
+  let buffered = "";
+  for await (const chunk of stream) {
+    buffered += decoder.decode(chunk, { stream: true });
+    let newline: number;
+    while ((newline = buffered.indexOf("\n")) >= 0) {
+      const line = buffered.slice(0, newline).trim();
+      buffered = buffered.slice(newline + 1);
+      if (!line) continue;
+      let message: unknown;
+      try { message = JSON.parse(line); } catch { continue; }
+      if (!message || typeof message !== "object") continue;
+      const record = message as Record<string, unknown>;
+      if (record.id !== id) continue;
+      if (record.error !== undefined) throw new CodexAuthStatusError("codex app-server rejected getAuthStatus");
+      if (!record.result || typeof record.result !== "object") {
+        throw new CodexAuthStatusError("codex app-server returned no getAuthStatus result");
+      }
+      return record.result as Record<string, unknown>;
+    }
+    if (buffered.length > MAX_APP_SERVER_LINE_BYTES) throw new CodexAuthStatusError("codex app-server line too long");
+  }
+  throw new CodexAuthStatusError("codex app-server exited before answering getAuthStatus");
+}
+
+function parseAuthStatus(result: Record<string, unknown>): CodexAuthStatus {
+  const authMethod = typeof result.authMethod === "string" ? result.authMethod : null;
+  const authToken = typeof result.authToken === "string" && result.authToken ? result.authToken : null;
+  const requiresOpenaiAuth = typeof result.requiresOpenaiAuth === "boolean" ? result.requiresOpenaiAuth : null;
+  return { authMethod, authToken, requiresOpenaiAuth };
+}
+
+/** `ocx doctor` lines for the active refresh owner. Never includes a credential. */
+export function formatNativeMainRefreshDoctorLines(resolution: NativeMainRefreshResolution): string[] {
+  const configured = resolution.configured === "auto" ? "auto" : `nativeMainRefresh: "${resolution.configured}"`;
+  const binary = resolution.command
+    ? `${displayCodexRuntimePath(resolution.command)} (${resolution.version ?? "unknown"})`
+    : "none";
+  switch (resolution.reason) {
+    case "codex-compatible":
+      return [`  ok  codex: Codex refreshes the main login through app-server (${binary}; ${configured})`];
+    case "configured-opencodex":
+      return [`  --  opencodex: OpenCodex refreshes auth.json with its guarded writer (${configured})`];
+    case "test-guard":
+      return ["  --  opencodex: test guard is armed; Codex delegation is disabled"];
+    case "codex-missing":
+      return [
+        `  !!  opencodex: no Codex binary found, so OpenCodex refreshes auth.json itself (${configured})`,
+        `       Install Codex ${CODEX_AUTH_STATUS_MIN_VERSION} or newer to let Codex own its login.`,
+      ];
+    case "codex-too-old":
+      return [
+        `  !!  opencodex: Codex ${binary} is older than ${CODEX_AUTH_STATUS_MIN_VERSION}, so OpenCodex refreshes auth.json itself (${configured})`,
+        "       Update Codex to let Codex own its login.",
+      ];
+  }
+}

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";
@@ -163,7 +163,7 @@ export function deleteScopedHealth(accountId: string, scope: CodexQuotaScope): v
 }
 
 /** Live quota-refusal avoidance for an account, including the lane the request belongs to. */
-function codexQuotaAvoidUntil(
+export function codexQuotaAvoidUntil(
   accountId: string,
   quotaScope: CodexQuotaScope | undefined,
   now: number,