@koreanhole/opencodex 2.98.0 → 2.99.0

package/AGENTS_INSTALL.md

@@ -29,6 +29,10 @@ ocx start
 ocx codex sync
 ```
 
+`ocx start` journals the native Codex config and injects the managed routing.
+`ocx stop` restores it. Use `ocx restore`/`ocx eject` to restore while keeping
+the proxy alive, and `ocx restore back` to re-enable routing.
+
 `ocx codex sync` refreshes the Codex app catalog with locally discovered Gemini
 models and reasoning levels. Restart the Codex app/app-server after refresh. The
 catalog file is written only when `model_catalog_json` names an opencodex catalog
@@ -57,6 +61,9 @@ or through the documented default path; unrelated Codex settings are not changed
 ```bash
 ocx status
 ocx stop
+ocx restore [--json] [--remove-codex-provider-table]
+ocx restore back [--json]
+ocx eject
 ```
 
 The default listener is loopback-only. A non-loopback bind is refused unless a
@@ -73,6 +80,7 @@ bun test tests/e2e/cline-only.test.ts
 bun run test:e2e:gemini
 bun run test:e2e:gemini-tool
 bun run test:e2e:gemini-reasoning
+bun run test:e2e:codex-restore
 ```
 
 Report whether each evidence path used a deterministic ACP fixture or a real

package/README.md

@@ -55,7 +55,15 @@ Cline-only configs load unchanged and keep Cline as the default.
 
 ## Codex
 
-Use a Responses provider pointed at the proxy:
+`ocx start` now records a mode-0600 pre-image under `$OPENCODEX_HOME/codex/`,
+injects the loopback Responses provider, and points Codex at the live model
+catalog. The managed block is marked and is the only block opencodex will touch.
+
+```bash
+ocx start
+```
+
+The resulting Codex config is equivalent to:
 
 ```toml
 model = "gemini-cli/gemini-3.5-flash-lite"
@@ -69,6 +77,19 @@ requires_openai_auth = false
 model_catalog_url = "http://127.0.0.1:10100/v1/model-catalog"
 ```
 
+Switch back to native Codex without stopping the proxy:
+
+```bash
+ocx restore          # alias: ocx eject
+ocx restore back     # re-point Codex at the running proxy
+```
+
+`ocx stop`, Ctrl-C/SIGTERM, and SIGHUP also restore native Codex. The restore
+covers Codex config and the opencodex catalog only; resume-history metadata is
+not changed. A pre-existing unmarked `[model_providers.opencodex]` block is
+treated as user-owned and refused. Remove a stale manual block first with
+`ocx restore --remove-codex-provider-table` if needed.
+
 The model list is live. Cline ACP models are exposed as `cline-cli/<encoded-id>`;
 Gemini ACP models are exposed as `gemini-cli/<encoded-id>`. Each provider keeps a
 `default` selector. A provider prefix routes only to that vendor; unprefixed
@@ -120,6 +141,9 @@ Use a `cline-cli/...` model to route the same Messages surface to Cline.
   telemetry, updates, and automatic approval disabled. The real vendor provider
   store is immutable; a mode-0600 copy inside the staged home lets the vendor CLI
   refresh auth state and is removed after the turn.
+- Codex restore uses a mode-0600 journal under `$OPENCODEX_HOME/codex/`. The
+  journal contains the pre-image needed to reverse only opencodex-managed config
+  and catalog changes; it is never logged and is removed after a successful restore.
 - Gemini native tools are removed by a per-turn deny policy; permission requests
   are cancelled, and no ACP filesystem/terminal client capabilities are advertised.
   User MCP servers, extensions, skills, and hooks are disabled for the session; only
@@ -149,6 +173,9 @@ bun run src/cli/index.ts provider list [--json]
 bun run src/cli/index.ts start [--port 10100] [--host 127.0.0.1]
 bun run src/cli/index.ts status [--json]
 bun run src/cli/index.ts stop [--json]
+bun run src/cli/index.ts restore [--json] [--remove-codex-provider-table]
+bun run src/cli/index.ts restore back [--json]
+bun run src/cli/index.ts eject
 ```
 
 Gemini has no proxy login command. Authenticate it through the official CLI
@@ -168,6 +195,7 @@ bun run test:e2e:gemini-previous-response
 bun run test:e2e:gemini-websocket
 bun run test:e2e:gemini-websocket-tool
 bun run test:e2e:gemini-reasoning
+bun run test:e2e:codex-restore
 bun run privacy:scan
 bun run structure:check
 ```
@@ -223,6 +251,9 @@ Optional overrides are `CLINE_BIN_PATH`, `GEMINI_BIN_PATH`, and `CODEX_BIN_PATH`
   quota; the catalog stays accurate but that model cannot complete a live turn.
 - **Codex model picker is stale**: run `ocx codex sync`, then restart the Codex
   app/app-server.
+- **Codex provider conflict**: an existing unmarked
+  `[model_providers.opencodex]` was preserved. Reconcile it manually or use
+  `ocx restore --remove-codex-provider-table`, then start again.
 - **Port in use**: choose another port with `ocx start --port <port>`.
 - **Stale runtime state**: run `ocx stop`; it removes stale state only when the
   recorded process and health endpoint cannot be verified.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koreanhole/opencodex",
-  "version": "2.98.0",
+  "version": "2.99.0",
   "description": "Cline and Gemini CLI provider proxy for OpenAI Codex and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",
@@ -37,6 +37,7 @@
     "test:e2e:gemini-websocket": "bun test ./tests/e2e/gemini-codex.live.ts -t \"runs a live Codex WebSocket turn\"",
     "test:e2e:gemini-websocket-tool": "bun test ./tests/e2e/gemini-codex.live.ts -t \"runs a live Codex WebSocket tool loop\"",
     "test:e2e:gemini-reasoning": "bun test ./tests/e2e/gemini-reasoning.live.ts",
+    "test:e2e:codex-restore": "bun test ./tests/e2e/codex-restore.live.ts",
     "typecheck": "bun check --no-script --noEmit",
     "privacy:scan": "bun scripts/privacy-scan.ts",
     "structure:check": "bun scripts/structure-check.ts",

package/src/cli/index.ts

@@ -20,6 +20,7 @@ import { startServer } from "../server";
 import { loginClineAcp } from "../adapters/cli-agent/cline/acp";
 import { runCodingAgentMcpServer } from "../adapters/cli-agent/mcp-server";
 import { syncCodexCatalog } from "../lib/codex-catalog";
+import { injectCodexConfig, recordCodexCatalogState, restoreCodexConfig } from "../lib/codex-inject";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -61,7 +62,10 @@ function help(): string {
     "  provider list [--json]                 Show supported providers",
     "  start [--port <port>] [--host <host>] Start the proxy",
     "  status [--json]                        Check the running proxy",
-    "  stop [--json]                          Stop the running proxy",
+    "  stop [--json]                          Stop the proxy and restore native Codex",
+    "  restore [--json]                       Restore native Codex without stopping",
+    "  restore back [--json]                  Re-point Codex at the running proxy",
+    "  eject                                  Alias of restore",
     "  codex sync [--json]                    Refresh the Codex model catalog",
     "  version                                Print the package version",
     "  help                                   Show this help",
@@ -179,21 +183,27 @@ async function startCommand(args: string[]): Promise<number> {
     config.port = parsed;
   }
   if (host !== undefined) config.host = host;
+  const running = startServer(config, { env });
+  try {
+    await injectCodexConfig({ env, endpoint: { host: running.host, port: running.port }, config });
+  } catch (error) {
+    await running.stop(true).catch(() => undefined);
+    throw error;
+  }
   try {
     const catalog = await syncCodexCatalog({ env });
     if (catalog.ok && catalog.written) {
+      await recordCodexCatalogState(env).catch(error => {
+        console.warn(`[opencodex] Codex catalog state was not journaled: ${error instanceof Error ? error.message : String(error)}`);
+      });
       console.log(`Codex catalog refreshed: ${catalog.path}`);
       console.log("Restart the Codex app/app-server to reload the model picker.");
-      if (!catalog.configured) {
-        console.log(`Activate it with: model_catalog_json = "${catalog.path}"`);
-      }
     } else if (!catalog.ok) {
       console.warn(`[opencodex] Codex catalog was not refreshed: ${catalog.message}`);
     }
   } catch (error) {
     console.warn(`[opencodex] Codex catalog refresh failed: ${error instanceof Error ? error.message : String(error)}`);
   }
-  const running = startServer(config, { env });
   await writeRuntimeState({ pid: process.pid, port: running.port, host: running.host, startedAt: new Date().toISOString() }, env);
   console.log(`opencodex listening on http://${running.host}:${running.port}/v1 (default provider: ${config.defaultProvider})`);
   console.log(`Health: http://${running.host}:${running.port}/healthz`);
@@ -202,10 +212,22 @@ async function startCommand(args: string[]): Promise<number> {
     console.log(`\nStopping proxy (${signal})...`);
     await running.stop(true);
     await removeRuntimeStateIfPid(process.pid, env);
-    process.exit(0);
+    let exitCode = 0;
+    try {
+      const restored = await restoreCodexConfig({ env });
+      if (!restored.success) {
+        exitCode = 1;
+        console.error(`ocx: Codex restore did not complete: ${restored.catalog.message}`);
+      }
+    } catch (error) {
+      exitCode = 1;
+      console.error(`ocx: Codex restore failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    process.exit(exitCode);
   };
   process.once("SIGINT", () => void shutdown("SIGINT"));
   process.once("SIGTERM", () => void shutdown("SIGTERM"));
+  process.once("SIGHUP", () => void shutdown("SIGHUP"));
   await new Promise<never>(() => undefined);
   return 0;
 }
@@ -232,9 +254,42 @@ async function codexCommand(args: string[]): Promise<number> {
     }
     console.log("Codex reload required: restart the Codex app or app-server model picker.");
   }
+  if (result.ok) await recordCodexCatalogState(process.env).catch(() => undefined);
   return 0;
 }
 
+async function restoreCommand(args: string[]): Promise<number> {
+  const env = process.env;
+  const back = args[0] === "back";
+  if (back) args.shift();
+  const json = takeFlag(args, "--json");
+  const removeProviderTable = takeFlag(args, "--remove-codex-provider-table");
+  if (args.length > 0) throw new ConfigError(`Unknown restore option: ${args[0]}`);
+  let result;
+  if (back) {
+    const state = await readRuntimeState(env);
+    if (!state) throw new ConfigError("Proxy is not running; start it before `ocx restore back`.");
+    const config = await loadConfig(env);
+    if (!isAlive(state.pid) || !await health(state.host, state.port, config, env)) {
+      throw new ConfigError("The recorded proxy is not healthy; refusing to restore Codex routing.");
+    }
+    result = await injectCodexConfig({
+      env,
+      endpoint: { host: state.host, port: state.port },
+      config,
+    });
+    result = { ...result, action: "restore-back" as const };
+  } else {
+    result = await restoreCodexConfig({ env, removeProviderTable });
+  }
+  if (json) console.log(JSON.stringify(result));
+  else {
+    console.log(result.config.message);
+    console.log(result.catalog.message);
+  }
+  return result.success ? 0 : 1;
+}
+
 async function statusCommand(args: string[]): Promise<number> {
   const json = takeFlag(args, "--json");
   if (args.length > 0) throw new ConfigError(`Unknown status option: ${args[0]}`);
@@ -257,16 +312,24 @@ async function stopCommand(args: string[]): Promise<number> {
   if (args.length > 0) throw new ConfigError(`Unknown stop option: ${args[0]}`);
   const state = await readRuntimeState();
   if (!state) {
-    if (json) console.log(JSON.stringify({ stopped: false, reason: "not-running" }));
-    else console.log("Proxy is not running.");
+    const restored = await restoreCodexConfig({ env: process.env });
+    if (json) console.log(JSON.stringify({ stopped: false, reason: "not-running", restore: restored }));
+    else {
+      console.log("Proxy is not running.");
+      console.log(restored.config.message);
+    }
     return 1;
   }
   const config = await loadConfig();
   if (!isAlive(state.pid)) {
     await removeRuntimeStateIfPid(state.pid);
-    if (json) console.log(JSON.stringify({ stopped: true, stale: true }));
-    else console.log("Removed stale proxy state.");
-    return 0;
+    const restored = await restoreCodexConfig({ env: process.env });
+    if (json) console.log(JSON.stringify({ stopped: true, stale: true, restore: restored }));
+    else {
+      console.log("Removed stale proxy state.");
+      console.log(restored.config.message);
+    }
+    return restored.success ? 0 : 1;
   }
   if (!await health(state.host, state.port, config, process.env)) {
     throw new ConfigError(`Refusing to stop pid ${state.pid}: it is not the opencodex proxy recorded by this home.`);
@@ -276,9 +339,13 @@ async function stopCommand(args: string[]): Promise<number> {
   while (isAlive(state.pid) && Date.now() < deadline) await Bun.sleep(50);
   if (isAlive(state.pid)) process.kill(state.pid, "SIGKILL");
   await removeRuntimeStateIfPid(state.pid);
-  if (json) console.log(JSON.stringify({ stopped: true, pid: state.pid }));
-  else console.log(`Stopped proxy (pid ${state.pid}).`);
-  return 0;
+  const restored = await restoreCodexConfig({ env: process.env });
+  if (json) console.log(JSON.stringify({ stopped: true, pid: state.pid, restore: restored }));
+  else {
+    console.log(`Stopped proxy (pid ${state.pid}).`);
+    console.log(restored.config.message);
+  }
+  return restored.success ? 0 : 1;
 }
 
 async function main(argv: string[]): Promise<number> {
@@ -301,7 +368,8 @@ async function main(argv: string[]): Promise<number> {
   if (command === "start") return await startCommand(argv);
   if (command === "status") return await statusCommand(argv);
   if (command === "stop") return await stopCommand(argv);
-  throw new ConfigError(`Unknown command: ${command}. Expected login, provider, codex, start, status, stop, version, or help.`);
+  if (command === "restore" || command === "eject") return await restoreCommand(argv);
+  throw new ConfigError(`Unknown command: ${command}. Expected login, provider, codex, start, status, stop, restore, eject, version, or help.`);
 }
 
 try {

package/src/lib/codex-catalog.ts

@@ -257,6 +257,67 @@ function readRootTomlString(text: string, key: string): string | undefined {
   return match?.[1]?.trim() || undefined;
 }
 
+export function codexHome(env: NodeJS.ProcessEnv = process.env): string {
+  return env.CODEX_HOME?.trim() || join(env.HOME?.trim() || homedir(), ".codex");
+}
+
+/** Resolve the catalog only when opencodex is allowed to manage that file. */
+export async function resolveCodexCatalogPath(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<string | undefined> {
+  const home = codexHome(env);
+  let configured: string | undefined;
+  try {
+    configured = readRootTomlString(await readFile(join(home, "config.toml"), "utf8"), "model_catalog_json");
+  } catch {
+    configured = undefined;
+  }
+  if (configured && basename(configured) !== "opencodex-catalog.json") return undefined;
+  return configured ? resolve(home, configured) : join(home, "opencodex-catalog.json");
+}
+
+export function isManagedCodexCatalogSlug(slug: unknown): boolean {
+  return managedSlug(slug);
+}
+
+/** Remove only opencodex-routed rows; preserve native/user rows. */
+export async function removeManagedCodexCatalogRows(path: string): Promise<{
+  changed: boolean;
+  removed: number;
+  message: string;
+}> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { changed: false, removed: 0, message: "No opencodex catalog file was present." };
+    }
+    throw error;
+  }
+  let parsed: Record<string, unknown>;
+  try {
+    const value = asRecord(JSON.parse(raw));
+    if (!value) throw new Error("catalog is not an object");
+    parsed = value;
+  } catch {
+    throw new Error("The opencodex catalog is malformed; it was preserved.");
+  }
+  const models = Array.isArray(parsed.models) ? parsed.models : undefined;
+  if (!models || models.some(model => !asRecord(model))) {
+    throw new Error("The opencodex catalog has an invalid models field; it was preserved.");
+  }
+  const kept = models.filter(model => !managedSlug(asRecord(model)?.slug));
+  const removed = models.length - kept.length;
+  if (removed === 0) return { changed: false, removed: 0, message: "No managed catalog rows were present." };
+  if (kept.length === 0 && basename(path) === "opencodex-catalog.json") {
+    await rm(path, { force: true });
+    return { changed: true, removed, message: `Removed ${removed} managed catalog row(s) and the empty opencodex catalog.` };
+  }
+  await writeCodexCatalog(path, { ...parsed, models: kept } as CodexCatalogDocument);
+  return { changed: true, removed, message: `Removed ${removed} managed catalog row(s) from ${path}.` };
+}
+
 export async function writeCodexCatalog(
   path: string,
   document: CodexCatalogDocument,

package/src/lib/codex-inject.ts

@@ -0,0 +1,467 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getConfigDir, isLoopbackHost, type RuntimeConfig } from "../config";
+import {
+  codexHome,
+  removeManagedCodexCatalogRows,
+  resolveCodexCatalogPath,
+} from "./codex-catalog";
+
+const JOURNAL_VERSION = 1;
+const MANAGED_MARKER = "# Managed by opencodex: provider routing";
+const LOCK_STALE_MS = 30_000;
+
+export class CodexInjectionError extends Error {
+  constructor(message: string, readonly code: string) {
+    super(message);
+    this.name = "CodexInjectionError";
+  }
+}
+
+export interface CodexInjectionEndpoint {
+  host: string;
+  port: number;
+}
+
+export interface CodexInjectionResult {
+  success: boolean;
+  action: "inject" | "restore" | "restore-back";
+  changed: boolean;
+  config: { state: "ok" | "skipped" | "failed"; changed: boolean; message: string };
+  catalog: { state: "ok" | "skipped" | "failed"; changed: boolean; removed: number; message: string };
+}
+
+interface CodexJournal {
+  version: 1;
+  codexHome: string;
+  configPath: string;
+  originalConfigBase64: string | null;
+  injectedConfigHash: string;
+  catalogPath: string | null;
+  originalCatalogBase64: string | null;
+  managedCatalogHash: string | null;
+  createdAt: string;
+}
+
+interface MaybeFile {
+  exists: boolean;
+  bytes: Buffer | null;
+}
+
+function configPath(env: NodeJS.ProcessEnv): string {
+  return join(codexHome(env), "config.toml");
+}
+
+function journalPath(env: NodeJS.ProcessEnv): string {
+  return join(getConfigDir(env), "codex", "inject-journal.json");
+}
+
+function lockPath(env: NodeJS.ProcessEnv): string {
+  return join(getConfigDir(env), "codex", "inject.lock");
+}
+
+function hash(bytes: string | Buffer): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function b64(bytes: Buffer | null): string | null {
+  return bytes ? bytes.toString("base64") : null;
+}
+
+function unb64(value: string | null): Buffer | null {
+  return value ? Buffer.from(value, "base64") : null;
+}
+
+async function readMaybe(path: string): Promise<MaybeFile> {
+  try {
+    return { exists: true, bytes: await readFile(path) };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { exists: false, bytes: null };
+    throw error;
+  }
+}
+
+async function writeAtomic(path: string, bytes: string | Buffer, mode = 0o600): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, bytes, { mode, flag: "wx" });
+    await chmod(temporary, mode);
+    await rename(temporary, path);
+    await chmod(path, mode).catch(() => undefined);
+  } finally {
+    await rm(temporary, { force: true }).catch(() => undefined);
+  }
+}
+
+function alive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+async function withLock<T>(env: NodeJS.ProcessEnv, fn: () => Promise<T>): Promise<T> {
+  const path = lockPath(env);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const acquire = async (): Promise<boolean> => {
+    try {
+      await writeFile(path, JSON.stringify({ pid: process.pid, at: Date.now() }), { mode: 0o600, flag: "wx" });
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      let stale = false;
+      try {
+        const info = await stat(path);
+        let pid = 0;
+        try { pid = (JSON.parse(await readFile(path, "utf8")) as { pid?: number }).pid ?? 0; } catch { /* malformed */ }
+        stale = Date.now() - info.mtimeMs > LOCK_STALE_MS || (pid > 0 && !alive(pid));
+      } catch {
+        stale = true;
+      }
+      if (stale) {
+        await rm(path, { force: true }).catch(() => undefined);
+        return await acquire();
+      }
+      return false;
+    }
+  };
+  if (!await acquire()) throw new CodexInjectionError("Another Codex configuration change is in progress; retry after it finishes.", "codex_config_busy");
+  try {
+    return await fn();
+  } finally {
+    await rm(path, { force: true }).catch(() => undefined);
+  }
+}
+
+function isProviderHeader(line: string): boolean {
+  return /^\s*\[\s*model_providers\.opencodex(?:\s*\.|\s*\])/.test(line);
+}
+
+function isTableHeader(line: string): boolean {
+  return /^\s*\[/.test(line);
+}
+
+function rootEnd(lines: readonly string[]): number {
+  const index = lines.findIndex(isTableHeader);
+  return index < 0 ? lines.length : index;
+}
+
+function rootValue(text: string, key: string): string | undefined {
+  const lines = text.split(/\r?\n/);
+  const end = rootEnd(lines);
+  const re = new RegExp(`^\\s*${key}\\s*=\\s*"([^"]*)"`, "m");
+  for (let index = 0; index < end; index++) {
+    const match = re.exec(lines[index]!);
+    if (match) return match[1] ?? "";
+  }
+  return undefined;
+}
+
+function setRootValue(text: string, key: string, value: string | undefined): string {
+  const lines = text.split(/\r?\n/);
+  let end = rootEnd(lines);
+  let found = false;
+  const re = new RegExp(`^\\s*${key}\\s*=`);
+  for (let index = 0; index < end; index++) {
+    if (!re.test(lines[index]!)) continue;
+    found = true;
+    if (value === undefined) {
+      lines.splice(index, 1);
+      end -= 1;
+    } else {
+      lines[index] = `${key} = ${JSON.stringify(value)}`;
+    }
+    break;
+  }
+  if (!found && value !== undefined) {
+    lines.splice(end, 0, `${key} = ${JSON.stringify(value)}`);
+    end += 1;
+  }
+  return lines.join("\n");
+}
+
+function hasUnmarkedProviderTable(text: string): boolean {
+  const lines = text.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index++) {
+    if (!isProviderHeader(lines[index]!)) continue;
+    let previous = index - 1;
+    while (previous >= 0 && lines[previous]!.trim() === "") previous--;
+    if (lines[previous]?.trim() !== MANAGED_MARKER) return true;
+  }
+  return false;
+}
+
+function stripProviderTables(text: string): string {
+  const lines = text.split(/\r?\n/);
+  const out: string[] = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (isTableHeader(line)) {
+      if (isProviderHeader(line)) {
+        skipping = true;
+        while (out.length > 0 && out[out.length - 1]!.trim() === MANAGED_MARKER) out.pop();
+        continue;
+      }
+      skipping = false;
+    }
+    if (skipping) continue;
+    if (line.trim() === MANAGED_MARKER) continue;
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+function providerBlock(endpoint: CodexInjectionEndpoint): string {
+  const base = `http://${endpoint.host}:${endpoint.port}/v1`;
+  return [
+    MANAGED_MARKER,
+    "[model_providers.opencodex]",
+    'name = "opencodex (Cline or Gemini CLI)"',
+    `base_url = ${JSON.stringify(base)}`,
+    'wire_api = "responses"',
+    "requires_openai_auth = false",
+    `model_catalog_url = ${JSON.stringify(`${base}/model-catalog`)}`,
+  ].join("\n");
+}
+
+function routedModel(original: string, config: RuntimeConfig): string {
+  const current = rootValue(original, "model");
+  if (current?.startsWith("cline-cli/") || current?.startsWith("gemini-cli/")) return current;
+  return `${config.defaultProvider}/${config.providers[config.defaultProvider].defaultModel}`;
+}
+
+function injectedConfig(text: string, endpoint: CodexInjectionEndpoint, config: RuntimeConfig): string {
+  if (hasUnmarkedProviderTable(text)) {
+    throw new CodexInjectionError(
+      "Codex config already defines a different [model_providers.opencodex] table; refusing to overwrite it.",
+      "codex_provider_conflict",
+    );
+  }
+  let next = stripProviderTables(text);
+  next = setRootValue(next, "model_provider", "opencodex");
+  next = setRootValue(next, "model", routedModel(text, config));
+  const body = next.trimEnd();
+  return `${body}${body ? "\n\n" : ""}${providerBlock(endpoint)}\n`;
+}
+
+function restoreRoots(current: string, original: string | null): string {
+  let next = stripProviderTables(current);
+  for (const key of ["model_provider", "model"] as const) {
+    next = setRootValue(next, key, original === null ? undefined : rootValue(original, key));
+  }
+  return next;
+}
+
+async function readJournal(env: NodeJS.ProcessEnv): Promise<CodexJournal | null> {
+  let raw: string;
+  try {
+    raw = await readFile(journalPath(env), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+  let parsed: Partial<CodexJournal>;
+  try {
+    parsed = JSON.parse(raw) as Partial<CodexJournal>;
+  } catch {
+    throw new CodexInjectionError("The Codex restore journal is malformed; it was preserved.", "codex_journal_malformed");
+  }
+  if (parsed.version !== JOURNAL_VERSION || typeof parsed.configPath !== "string" || typeof parsed.injectedConfigHash !== "string") {
+    throw new CodexInjectionError("The Codex restore journal is invalid; it was preserved.", "codex_journal_invalid");
+  }
+  return parsed as CodexJournal;
+}
+
+async function writeJournal(env: NodeJS.ProcessEnv, journal: CodexJournal): Promise<void> {
+  await writeAtomic(journalPath(env), `${JSON.stringify(journal, null, 2)}\n`);
+}
+
+function endpointError(endpoint: CodexInjectionEndpoint): void {
+  if (!Number.isInteger(endpoint.port) || endpoint.port < 1 || endpoint.port > 65_535) {
+    throw new CodexInjectionError("The Codex proxy endpoint port is invalid.", "codex_endpoint_invalid");
+  }
+  if (!isLoopbackHost(endpoint.host)) {
+    throw new CodexInjectionError("Codex injection requires a loopback proxy endpoint.", "codex_endpoint_non_loopback");
+  }
+}
+
+function validateToml(text: string): void {
+  if (!text.trim()) return;
+  try {
+    Bun.TOML.parse(text);
+  } catch {
+    throw new CodexInjectionError("Codex config is not valid TOML; it was preserved.", "codex_config_malformed");
+  }
+}
+
+/** Inject routing and persist the pre-image before touching Codex config. */
+export async function injectCodexConfig(options: {
+  env: NodeJS.ProcessEnv;
+  endpoint: CodexInjectionEndpoint;
+  config: RuntimeConfig;
+}): Promise<CodexInjectionResult> {
+  endpointError(options.endpoint);
+  return await withLock(options.env, async () => {
+    const path = configPath(options.env);
+    const current = await readMaybe(path);
+    if (current.exists) validateToml(current.bytes!.toString("utf8"));
+    const existing = await readJournal(options.env);
+    const originalConfig = existing ? unb64(existing.originalConfigBase64) : current.bytes;
+    const originalCatalog = existing ? unb64(existing.originalCatalogBase64) : null;
+    const catalogPath = existing?.catalogPath ?? await resolveCodexCatalogPath(options.env) ?? null;
+    const catalog = catalogPath ? await readMaybe(catalogPath) : { exists: false, bytes: null };
+    const before = current.bytes?.toString("utf8") ?? "";
+    if (existing && !hasManagedProvider(before)) {
+      throw new CodexInjectionError(
+        "A Codex restore journal exists but Codex routing is already native; run `ocx restore` before starting again.",
+        "codex_journal_state_conflict",
+      );
+    }
+    const next = injectedConfig(before, options.endpoint, options.config);
+    const journal: CodexJournal = {
+      version: JOURNAL_VERSION,
+      codexHome: codexHome(options.env),
+      configPath: path,
+      originalConfigBase64: b64(originalConfig),
+      injectedConfigHash: hash(next),
+      catalogPath: existing?.catalogPath ?? catalogPath,
+      originalCatalogBase64: existing ? existing.originalCatalogBase64 : b64(catalog.bytes),
+      managedCatalogHash: existing?.managedCatalogHash ?? null,
+      createdAt: existing?.createdAt ?? new Date().toISOString(),
+    };
+    await writeJournal(options.env, journal);
+    try {
+      await writeAtomic(path, next);
+    } catch (error) {
+      if (!existing) await rm(journalPath(options.env), { force: true }).catch(() => undefined);
+      throw error;
+    }
+    return {
+      success: true,
+      action: "inject",
+      changed: true,
+      config: { state: "ok", changed: true, message: "Codex routing is pointed at the local proxy." },
+      catalog: { state: "ok", changed: false, removed: 0, message: originalCatalog ? "Original catalog is journaled." : "Catalog state is journaled." },
+    };
+  });
+}
+
+function hasManagedProvider(text: string): boolean {
+  return text.includes(MANAGED_MARKER);
+}
+
+async function restoreCatalog(journal: CodexJournal): Promise<CodexInjectionResult["catalog"]> {
+  const path = journal.catalogPath;
+  if (!path) return { state: "skipped", changed: false, removed: 0, message: "No managed catalog path was journaled." };
+  const current = await readMaybe(path);
+  if (!current.exists) return { state: "skipped", changed: false, removed: 0, message: "No managed catalog file was present." };
+  const currentHash = hash(current.bytes!);
+  const original = unb64(journal.originalCatalogBase64);
+  if (journal.managedCatalogHash && currentHash === journal.managedCatalogHash) {
+    if (original === null) {
+      await rm(path, { force: true });
+      return { state: "ok", changed: true, removed: 0, message: "Removed the opencodex-owned catalog file." };
+    }
+    await writeAtomic(path, original);
+    return { state: "ok", changed: true, removed: 0, message: "Restored the original Codex catalog." };
+  }
+  try {
+    const removed = await removeManagedCodexCatalogRows(path);
+    return { state: "ok", changed: removed.changed, removed: removed.removed, message: removed.message };
+  } catch (error) {
+    return { state: "failed", changed: false, removed: 0, message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** Restore native Codex config/catalog; no-op when nothing was managed. */
+export async function restoreCodexConfig(options: {
+  env: NodeJS.ProcessEnv;
+  removeProviderTable?: boolean;
+}): Promise<CodexInjectionResult> {
+  return await withLock(options.env, async () => {
+    const journal = await readJournal(options.env);
+    const path = configPath(options.env);
+    const current = await readMaybe(path);
+    if (current.exists) validateToml(current.bytes!.toString("utf8"));
+    if (!journal) {
+      let catalog: CodexInjectionResult["catalog"] = {
+        state: "skipped", changed: false, removed: 0, message: "No journal was present.",
+      };
+      const catalogPath = await resolveCodexCatalogPath(options.env);
+      if (catalogPath) {
+        try {
+          const removed = await removeManagedCodexCatalogRows(catalogPath);
+          catalog = { state: "ok", changed: removed.changed, removed: removed.removed, message: removed.message };
+        } catch (error) {
+          catalog = { state: "failed", changed: false, removed: 0, message: error instanceof Error ? error.message : String(error) };
+        }
+      }
+      if (!current.exists) {
+        return {
+          success: catalog.state !== "failed", action: "restore", changed: catalog.changed,
+          config: { state: "skipped", changed: false, message: "Codex config was not present." },
+          catalog,
+        };
+      }
+      const text = current.bytes!.toString("utf8");
+      if (hasUnmarkedProviderTable(text) && !options.removeProviderTable) {
+        throw new CodexInjectionError("Codex contains an unmarked opencodex provider table; refusing to remove it.", "codex_provider_conflict");
+      }
+      if (!hasManagedProvider(text) && !options.removeProviderTable) {
+        return {
+          success: catalog.state !== "failed", action: "restore", changed: catalog.changed,
+          config: { state: "skipped", changed: false, message: "Codex is already using its native configuration." },
+          catalog,
+        };
+      }
+      const restored = restoreRoots(text, null);
+      await writeAtomic(path, restored);
+      return {
+        success: catalog.state !== "failed", action: "restore", changed: true || catalog.changed,
+        config: { state: "ok", changed: true, message: "Removed managed Codex routing; no pre-image journal was available." },
+        catalog,
+      };
+    }
+    const original = unb64(journal.originalConfigBase64);
+    const text = current.bytes?.toString("utf8") ?? "";
+    let changed = false;
+    let message = "Codex config was already native.";
+    if (current.exists && hash(current.bytes!) === journal.injectedConfigHash) {
+      if (original === null) await rm(path, { force: true });
+      else await writeAtomic(path, original);
+      changed = true;
+      message = original === null ? "Removed the managed Codex config." : "Restored the original Codex config.";
+    } else if (hasManagedProvider(text)) {
+      if (hasUnmarkedProviderTable(text) && !options.removeProviderTable) {
+        throw new CodexInjectionError("Codex contains an unmarked opencodex provider table; refusing to remove it.", "codex_provider_conflict");
+      }
+      await writeAtomic(path, restoreRoots(text, original?.toString("utf8") ?? null));
+      changed = true;
+      message = "Removed managed Codex routing while preserving unrelated edits.";
+    }
+    const catalog = await restoreCatalog(journal);
+    if (catalog.state === "failed") {
+      return {
+        success: false, action: "restore", changed,
+        config: { state: "ok", changed, message },
+        catalog,
+      };
+    }
+    await rm(journalPath(options.env), { force: true });
+    return {
+      success: true, action: "restore", changed: changed || catalog.changed,
+      config: { state: changed ? "ok" : "skipped", changed, message },
+      catalog,
+    };
+  });
+}
+
+/** Record the post-sync catalog hash so a later exact restore can remove it. */
+export async function recordCodexCatalogState(env: NodeJS.ProcessEnv): Promise<void> {
+  await withLock(env, async () => {
+    const journal = await readJournal(env);
+    if (!journal?.catalogPath) return;
+    const current = await readMaybe(journal.catalogPath);
+    journal.managedCatalogHash = current.exists ? hash(current.bytes!) : null;
+    await writeJournal(env, journal);
+  });
+}