diff --git a/docs-site/src/content/docs/guides/codex-integration.md b/docs-site/src/content/docs/guides/codex-integration.md
index ae8aab96629..fd78c442a2d 100644
--- a/docs-site/src/content/docs/guides/codex-integration.md
+++ b/docs-site/src/content/docs/guides/codex-integration.md
@@ -1621,3 +1621,37 @@ The shared SSE decoder accepts LF, CRLF and standalone CR line endings, even whe
 Choosing an account-qualified model does not enable credit spending. Stored accounts obey **Use credits after limit** during authentication, when credentials are prepared, and before Responses HTTP or WebSocket dispatch after pacing or retry waits. A held request reports the credit policy, not an authentication failure; wait for the reset, choose another account, or explicitly enable that account’s credit spending.
 
 Stored-account vision and web-search helpers also recheck this policy before sending, including retries. If consent changes or a limit is reached after helper selection, the helper reports the policy refusal without sending that attempt. The standalone search relay returns a reset-bound 429. Caller-owned Direct credentials retain their existing behavior.
+
+## Opt in a custom provider to managed local routing
+
+A custom provider such as `chatgpt-http` may use `supports_websockets = false`
+to keep HTTP transport. OpenCodex leaves custom providers untouched by default.
+To delegate only that provider's URL to OpenCodex, run:
+
+```sh
+ocx codex-provider allow chatgpt-http
+ocx start
+```
+
+The first command explains the scope and asks for confirmation, defaulting to No.
+For an explicitly approved scripted operation, use `allow chatgpt-http --yes`.
+Consent applies to this provider ID in the selected `CODEX_HOME`; it does not
+approve other providers or other homes. Start and sync update only its `base_url`
+to the local proxy. Its identity, WebSocket setting, other TOML fields and history
+remain unchanged. Keep the proxy running while using this route.
+
+This mode supports explicit Responses provider tables with `requires_openai_auth = true`
+and no custom credentials or headers. Non-loopback targets, authless Desktop mode
+and client compaction require the existing dedicated integration instead.
+
+`ocx stop` and `ocx restore` restore recorded URLs while keeping consent for a later
+start. Run `ocx codex-provider status` to list approvals, or
+`ocx codex-provider revoke chatgpt-http` to restore its managed URL and remove consent.
+A URL changed outside OpenCodex is preserved and requires revoke followed by a new
+approval; OpenCodex does not silently adopt the replacement as a new baseline.
+The original URL assignment is retained in private recovery metadata under
+`OPENCODEX_HOME`, separately from the native config journal.
+
+Startup safety recognizes an approved provider's recorded managed URL as OpenCodex routing.
+This does not install restart protection: a manually started proxy still needs a viable
+background service to recover automatically after a restart.
diff --git a/docs-site/src/content/docs/reference/cli/lifecycle.md b/docs-site/src/content/docs/reference/cli/lifecycle.md
index 1a8f7a509d1..bcf244d4269 100644
--- a/docs-site/src/content/docs/reference/cli/lifecycle.md
+++ b/docs-site/src/content/docs/reference/cli/lifecycle.md
@@ -1139,3 +1139,13 @@ Use `ocx connect <url> --pairing-code-stdin`, `ocx connect status`, `ocx sync`,
 On Linux, `ocx service install` checks `loginctl show-user <current-user> -p Linger` before printing boot advice. Enabled linger is reported as already enabled. Disabled linger gets the `loginctl enable-linger $USER` hint; missing or unreadable diagnostics state the uncertainty and do not fail installation.
 
 On macOS, `ocx service status` distinguishes a loaded Desktop login item from a valid enabled registration awaiting the next login. `ocx status` credits the latter in restart safety when the same Desktop app currently supervises the proxy. An incorrect plist label or command, a disabled entry, an unverified load probe, or changed process identity still cannot earn protection.
+
+## Custom Codex provider consent
+
+`ocx codex-provider status` lists the provider IDs approved for the selected Codex home.
+`ocx codex-provider allow <id>` asks before allowing URL-only management on start/sync;
+`--yes` is explicit noninteractive consent for that named provider.
+`ocx codex-provider revoke <id>` restores an unchanged managed URL and revokes permission.
+These commands are local and do not require a running proxy. See
+[custom provider routing](/guides/codex-integration/#opt-in-a-custom-provider-to-managed-local-routing)
+for eligibility, restore behavior and transport preservation.
diff --git a/scripts/generate-ocx-skill-surface.ts b/scripts/generate-ocx-skill-surface.ts
index 87558c27adc..474c741807b 100644
--- a/scripts/generate-ocx-skill-surface.ts
+++ b/scripts/generate-ocx-skill-surface.ts
@@ -16,7 +16,7 @@ const PREAMBLE = `<!-- ${OWNER}. Do not edit by hand. -->\n<!-- Regenerate: bun
 
 // Navigation groups, not command dispatch. New roots require an explicit assignment.
 const DOMAINS = [
-  { name: "lifecycle", roots: ["chatgpt", "status", "resolve", "capabilities", "sync", "start", "stop", "restart", "service", "gui"] },
+  { name: "lifecycle", roots: ["codex-provider", "chatgpt", "status", "resolve", "capabilities", "sync", "start", "stop", "restart", "service", "gui"] },
   { name: "providers-models", roots: ["provider", "models", "alias"] },
   { name: "accounts", roots: ["account", "auth", "login", "logout"] },
   { name: "agents-routing", roots: ["agent", "combo", "route", "v2", "effort", "memory", "message", "advisor"] },
diff --git a/scripts/test-layout/layout.json b/scripts/test-layout/layout.json
index ffd84bbd044..a3f14d1585c 100644
--- a/scripts/test-layout/layout.json
+++ b/scripts/test-layout/layout.json
@@ -2,7 +2,7 @@
   "version": 1,
   "root": "tests",
   "explicitShards": ["layout-clients.json"],
-  "explicit": { "service-log.test.ts": "service", "messages-native-empty-inline.test.ts": "claude-integration",
+  "explicit": { "codex-provider-routing.test.ts": "codex-integration", "service-log.test.ts": "service", "messages-native-empty-inline.test.ts": "claude-integration",
     "owner-registry-isolation.test.ts": "config",
     "codex-history-pending-wal.test.ts": "codex-integration", "responses-anthropic-billing-send-budget.test.ts": "responses", "anthropic-billing-ownership.test.ts": "adapters/anthropic", "server-anthropic-billing.test.ts": "server", "server-anthropic-billing-boundaries.test.ts": "server", "router-anthropic-billing-failover.test.ts": "routing", "anthropic-billing-refusal.test.ts": "adapters/anthropic", "messages-request-id-headers.test.ts": "claude-integration", "bounded-file-read.test.ts": "lib", "responses-undeclared-tool-guard-inbound.test.ts": "responses", "explicit-empty-tool-catalog.test.ts": "responses", "explicit-empty-tool-catalog-history.test.ts": "responses",
     "messages-request-id-endpoint.test.ts": "claude-integration",
diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md
index ef01e117654..6f3f7722e0a 100644
--- a/skills/ocx/references/01_management_surface.md
+++ b/skills/ocx/references/01_management_surface.md
@@ -25,7 +25,7 @@ These answer in the CLI head and never reach the proxy, so they work with nothin
 
 | Chapter | Declared capabilities |
 |---|---|
-| [lifecycle](01_surface_lifecycle.md) | 12 |
+| [lifecycle](01_surface_lifecycle.md) | 13 |
 | [providers-models](01_surface_providers-models.md) | 47 |
 | [accounts](01_surface_accounts.md) | 41 |
 | [agents-routing](01_surface_agents-routing.md) | 51 |
@@ -47,6 +47,10 @@ Check the chapter's flags, the requested authority and the operating skill's con
 
 Original invocation order. These headings preserve links to the previous single-file reference.
 
+### `ocx codex-provider`
+
+[State-changing task](01_surface_lifecycle.md#ocx-codex-provider)
+
 ### `ocx chatgpt`
 
 [State-changing task](01_surface_lifecycle.md#ocx-chatgpt)
diff --git a/skills/ocx/references/01_surface_lifecycle.md b/skills/ocx/references/01_surface_lifecycle.md
index e8aa0b21a9d..ac998abd244 100644
--- a/skills/ocx/references/01_surface_lifecycle.md
+++ b/skills/ocx/references/01_surface_lifecycle.md
@@ -8,7 +8,25 @@
 Use these declarations to choose a task, then check its flags and authority before execution.
 Non-mutating probes may still contact providers, consume quota or refresh caches.
 
-Declared capabilities: 12.
+Declared capabilities: 13.
+
+### `ocx codex-provider`
+
+Usage: `ocx codex-provider <status|allow <id> [--yes]|revoke <id>>`
+
+Inspect, allow or revoke custom Codex provider routing consent.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--yes` | boolean | Explicitly approve the named provider without an interactive prompt. |
+
+JSON mode: `none`.
+
+- Only local loopback routing for Responses providers using OpenAI authentication is supported. No custom credentials/headers, authless mode or client compaction. Unapproved providers are never changed.
 
 ### `ocx chatgpt`
 
diff --git a/src/cli/capabilities-base.ts b/src/cli/capabilities-base.ts
index 4a374354b43..7ebe95ee113 100644
--- a/src/cli/capabilities-base.ts
+++ b/src/cli/capabilities-base.ts
@@ -19,6 +19,15 @@ export const HEAD_CAPABILITIES: readonly HeadCapability[] = [
  * A capability must not name a route the command does not actually fetch.
  */
 export const CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["codex-provider"],
+    bannerLines: ["ocx codex-provider <sub>    Confirm custom Codex provider routing: status|allow|revoke"],
+    summary: "Inspect, allow or revoke custom Codex provider routing consent.",
+    routes: [], flags: [{ name: "--yes", value: "boolean", summary: "Explicitly approve the named provider without an interactive prompt." }],
+    mutates: true, json: "none",
+    usage: "ocx codex-provider <status|allow <id> [--yes]|revoke <id>>",
+    details: ["Only local loopback routing for Responses providers using OpenAI authentication is supported. No custom credentials/headers, authless mode or client compaction. Unapproved providers are never changed."],
+  },
   {
     command: ["chatgpt"],
     summary: "Experimental ChatGPT app-server shim: launch, restore or status (macOS only).",
diff --git a/src/cli/codex-provider.ts b/src/cli/codex-provider.ts
new file mode 100644
index 00000000000..0f34845d23b
--- /dev/null
+++ b/src/cli/codex-provider.ts
@@ -0,0 +1,44 @@
+import { allowCodexProviderRouting, approvedCodexProviders, previewCodexProviderConsent, restoreApprovedCodexProviders } from "../codex/provider-routing";
+import { interactiveConfirm } from "./interactive-confirm";
+import { terminalSafeError, terminalSafeText } from "./runtime-api";
+
+export const CODEX_PROVIDER_USAGE = "Usage: ocx codex-provider <status|allow <id> [--yes]|revoke <id>>";
+
+export async function handleCodexProviderCommand(args: string[]): Promise<number> {
+  const [verb, id, flag] = args;
+  if (verb === "status" && args.length === 1) {
+    console.log(JSON.stringify({ approvedProviders: approvedCodexProviders() }));
+    return 0;
+  }
+  if ((verb !== "allow" && verb !== "revoke") || !id || args.length > 3
+    || (flag !== undefined && (verb !== "allow" || flag !== "--yes"))) {
+    console.error(CODEX_PROVIDER_USAGE);
+    return 1;
+  }
+  try {
+    if (verb === "revoke") {
+      restoreApprovedCodexProviders(id);
+      console.log(`Routing consent revoked for ${terminalSafeText(id)}; any unchanged managed URL was restored.`);
+      return 0;
+    }
+    const expected = previewCodexProviderConsent(id);
+    console.log(`OpenCodex will manage only base_url for Codex provider ${terminalSafeText(id)} in the selected CODEX_HOME.`);
+    console.log("Start/sync will route it to the local proxy; stop/restore will restore its original URL. Provider identity, transport settings and history stay unchanged.");
+    if (flag !== "--yes") {
+      if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error("Explicit consent required: use an interactive terminal or pass --yes with the exact provider ID.");
+        return 1;
+      }
+      if (!await interactiveConfirm({ question: "Allow this provider's routing to be managed?", defaultYes: false })) {
+        console.log("Cancelled; no consent or routing changes were saved.");
+        return 0;
+      }
+    }
+    allowCodexProviderRouting(id, expected);
+    console.log("Consent saved. Run ocx start or ocx sync to apply routing; use ocx codex-provider revoke <id> to undo consent.");
+    return 0;
+  } catch (error) {
+    console.error(terminalSafeError(error));
+    return 1;
+  }
+}
diff --git a/src/cli/dispatch.ts b/src/cli/dispatch.ts
index 59d9350e4be..c11d313a3b3 100644
--- a/src/cli/dispatch.ts
+++ b/src/cli/dispatch.ts
@@ -945,6 +945,10 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleLabCommand } = await import("./lab");
     return await handleLabCommand(deps.args.slice(1));
   },
+  "codex-provider": async deps => {
+    const { handleCodexProviderCommand } = await import("./codex-provider");
+    return await handleCodexProviderCommand(deps.args.slice(1));
+  },
   chatgpt: async deps => {
     const { handleChatgptCommand } = await import("./chatgpt-command");
     return await handleChatgptCommand(deps.args.slice(1));
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 9f20b1c8853..ec9250ba0da 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -100,6 +100,7 @@ Usage:
   ocx advisor <status|on|off|set|consent>  Advisor sidecar settings and context-sharing consent
   ocx companion <show|set|reset>  Menu-bar and widget companion usage settings
   ocx lab <sub>               Inspect Lab evidence and control local automation
+  ocx codex-provider <sub>    Confirm custom Codex provider routing: status|allow|revoke
   ocx chatgpt <sub>          Experimental app-server shim: launch|restore|status (macOS)
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 708698bf9a0..ebff2d17c25 100755
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -660,7 +660,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     }
     removePid(process.pid);
     removeRuntimePort(process.pid);
-    if (teardown.restoreNativeCodex && !currentExternalCodexModelProvider()) {
+    if (teardown.restoreNativeCodex) {
       try {
         if (!codexHomeIsAbsent(getCodexHome())) {
           const restored = restoreNativeCodex();
diff --git a/src/cli/registry.ts b/src/cli/registry.ts
index 597951a92af..541cec7f46c 100644
--- a/src/cli/registry.ts
+++ b/src/cli/registry.ts
@@ -8,6 +8,12 @@ export interface CliCommandEntry {
 }
 
 export const CLI_COMMANDS: CliCommandEntry[] = [
+  {
+    name: "codex-provider",
+    usage: "ocx codex-provider <status|allow <id> [--yes]|revoke <id>>",
+    summary: "Explicitly allow or revoke local routing management for a custom Codex provider.",
+    details: ["Consent is bound to the selected CODEX_HOME and provider ID. Only base_url is managed; transport settings and history are preserved."],
+  },
   {
     name: "message",
     usage: "ocx message <sessions|send> [options]",
diff --git a/src/codex/inject.ts b/src/codex/inject.ts
index a2c6102e878..982331a23ff 100644
--- a/src/codex/inject.ts
+++ b/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";
@@ -240,6 +241,9 @@ async function injectCodexConfigImpl(
   const rawContent = missingConfig ? "" : readFileSync(CODEX_CONFIG_PATH, "utf-8");
   const activeProvider = externalCodexModelProvider(rawContent);
   if (activeProvider) {
+    if (injectApprovedCodexProvider(activeProvider, routingTarget, options.beforeClientWrite ? () => runClientWriteGuard(options.beforeClientWrite) : undefined, options.validateOnly)) {
+      return { success: true, ...(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 +262,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'.`,
diff --git a/src/codex/inject/restore.ts b/src/codex/inject/restore.ts
index 73986a9c0e5..79e45d53328 100644
--- a/src/codex/inject/restore.ts
+++ b/src/codex/inject/restore.ts
@@ -1,3 +1,4 @@
+import { restoreApprovedCodexProviders } from "../provider-routing";
 import { beginCodexWriteSection, cleanExternalProviderJournal, publishCodexArtifact } from "./config-write-section";
 import { assertCodexHomeOwner, codexHomeIsAbsent, codexHomeOwnerBlocksCompensation, CodexHomeOwnerRefusal, type CodexHomeOwnerRefusalReason } from "../codex-home-owner";
 import { loadConfig } from "../../config";
@@ -115,6 +116,7 @@ export interface CodexRestoreConfigResult {
     | "owned-fields-stripped"
     | "routing-restored-provider-retained"
     | "external-provider-preserved"
+    | "approved-provider-restored"
     | "failed";
   message: string;
   retained?: RetainedCodexProviderTable;
@@ -236,6 +238,26 @@ export function failedHistoryRestoreFromOutcome(
   return failedHistoryRestore(undefined, describeHistoryJobFailure(outcome, "restore"));
 }
 
+export function finishApprovedProviderRestore(result: CodexNativeRestoreResult, revalidateDesiredState = false): CodexNativeRestoreResult {
+  if (!result.success || revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) return result;
+  try {
+    if (!restoreApprovedCodexProviders()) return result;
+  } catch (error) {
+    if (error instanceof CodexHomeOwnerRefusal) throw error;
+    const message = `Approved Codex provider URL restoration failed: ${error instanceof Error ? error.message : String(error)}`;
+    return { ...result, success: false, message: `${result.message} ${message}`, artifacts: {
+      ...result.artifacts, config: { ...result.artifacts.config, state: "failed", action: "failed", message },
+    } };
+  }
+  const message = "Approved Codex provider URLs restored; identity, other settings and history preserved.";
+  return { ...result, message: result.externalProvider ? message : `${result.message} ${message}`, artifacts: {
+    ...result.artifacts,
+    config: { ...result.artifacts.config, state: result.artifacts.config.state === "partial" ? "partial" : "ok", changed: true,
+      action: result.artifacts.config.changed ? result.artifacts.config.action : "approved-provider-restored",
+      message: result.artifacts.config.state === "partial" ? `${result.artifacts.config.message} ${message}` : message },
+  } };
+}
+
 function externalProviderRestoreResult(activeProvider: string): CodexNativeRestoreResult {
   const message = `External Codex provider ${tomlString(activeProvider)} preserved; no native restore was needed.`;
   return {
@@ -553,7 +575,7 @@ export async function restoreNativeCodexAsync(
   if (sibling) return sibling;
   try {
     assertCodexHomeOwner(getCodexHome());
-    return await restoreNativeCodexAsyncImpl(options);
+    return finishApprovedProviderRestore(await restoreNativeCodexAsyncImpl(options), options.revalidateDesiredState);
   } catch (error) {
     if (error instanceof CodexHomeOwnerRefusal) return homeOwnerRestoreRefusal(error);
     if (!(error instanceof CodexRestoreRefusal)) throw error;
@@ -782,7 +804,7 @@ export function restoreNativeCodex(
   if (sibling) return sibling;
   try {
     assertCodexHomeOwner(getCodexHome());
-    return restoreNativeCodexImpl(options);
+    return finishApprovedProviderRestore(restoreNativeCodexImpl(options), options.revalidateDesiredState);
   } catch (error) {
     if (error instanceof CodexHomeOwnerRefusal) return homeOwnerRestoreRefusal(error);
     throw error;
diff --git a/src/codex/inject/routing-classify.ts b/src/codex/inject/routing-classify.ts
index 8818ded27b7..102e12a20e9 100644
--- a/src/codex/inject/routing-classify.ts
+++ b/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";
   }
diff --git a/src/codex/provider-routing.ts b/src/codex/provider-routing.ts
new file mode 100644
index 00000000000..e266823f52d
--- /dev/null
+++ b/src/codex/provider-routing.ts
@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+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 { cleanExternalProviderJournal } from "./inject/config-write-section";
+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()]);
+    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): boolean {
+  if (!Object.hasOwn(readRecord().providers, id)) return false;
+  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 (!validateOnly) cleanExternalProviderJournal(beforeWrite);
+  return inWriteSection((held, content, record) => {
+    const apply = () => {
+      if (!Object.hasOwn(record.providers, id)) return false;
+      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 || field.url === target.baseUrl) return true;
+      beforeWrite?.();
+      if (readFileSync(CODEX_CONFIG_PATH, "utf8") !== content) throw new Error("Codex config changed before publication; retry sync.");
+      // 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 true;
+    };
+    return beforeWrite ? withConfigMutationLockSync(apply) : 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;
+  });
+}
diff --git a/src/codex/sync.ts b/src/codex/sync.ts
index 4be25a40aac..d06eb0a99f8 100644
--- a/src/codex/sync.ts
+++ b/src/codex/sync.ts
@@ -1,3 +1,4 @@
+import { approvedCodexProviders } from "./provider-routing";
 import { currentExternalCodexModelProvider, injectCodexConfig } from "./inject";
 import { FOREIGN_CODEX_HOME_OWNER_MESSAGE, UNKNOWN_CODEX_HOME_OWNER_MESSAGE, unbackedRoutedRemovalMessage } from "./catalog/routed-removal";
 import { printProjectCodexConfigWarnings, groupProjectCodexConfigWarningsByPath, type ProjectCodexConfigWarning } from "./project-config-warnings";
@@ -188,7 +189,7 @@ export async function syncModelsToCodex(
     };
   }
 
-  if (externalProvider) {
+  if (externalProvider && !approvedCodexProviders().includes(externalProvider)) {
     if (catalogEvenWhenNotInjected) {
       // External providers own config.toml, and the injector removes the OpenCodex
       // journal for external providers (inject.ts). This explicit catalog-only sync
diff --git a/structure/INDEX.md b/structure/INDEX.md
index 3ff8fd65633..5587f9c5839 100644
--- a/structure/INDEX.md
+++ b/structure/INDEX.md
@@ -25,6 +25,7 @@ Persisted config, the Codex home it writes into, and the model catalog it publis
 | Doc | Scope |
 | --- | --- |
 | [`config.md`](config.md) | Persisted config schema, both injection forms, provider validation, and restore. |
+| [`codex-provider-routing.md`](codex-provider-routing.md) | Explicit provider-ID routing consent, URL-only publication and recovery. |
 | [`codex-home.md`](codex-home.md) | CODEX_HOME resolution, the files opencodex manages there, and Codex-home diagnostics. |
 | [`codex-prompts.md`](codex-prompts.md) | Prompt-layer repair, base import previews and bounded text-probe sources. |
 | [`catalog.md`](catalog.md) | Shared Codex catalog assembly, account namespaces, pool rotation, and effort ladders. |
@@ -152,6 +153,7 @@ A source area can be described by more than one doc, because these docs are orga
 | `src/claude/` | [`runtime.md`](runtime.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md)<br>[`clients/claude-desktop-config-reads.md`](clients/claude-desktop-config-reads.md) |
 | `src/cli.ts` | [`runtime.md`](runtime.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
 | `src/cli/` | [`runtime.md`](runtime.md)<br>[`config.md`](config.md)<br>[`local-messaging.md`](local-messaging.md)<br>[`cli-management.md`](cli-management.md)<br>[`clients/integrations.md`](clients/integrations.md)<br>[`clients/codex-desktop.md`](clients/codex-desktop.md)<br>[`clients/chatgpt-desktop.md`](clients/chatgpt-desktop.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `src/cli/codex-provider.ts` | [`codex-provider-routing.md`](codex-provider-routing.md) |
 | `src/cli/models-runtime.ts` | [`pricing.md`](pricing.md) |
 | `src/client/` | [`runtime.md`](runtime.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md) |
 | `src/clients/` | [`clients/integrations.md`](clients/integrations.md)<br>[`clients/qoder.md`](clients/qoder.md) |
@@ -161,6 +163,7 @@ A source area can be described by more than one doc, because these docs are orga
 | `src/codex/catalog/parsing.ts` | [`catalog-vendor-context.md`](catalog-vendor-context.md) |
 | `src/codex/catalog/routed-gather.ts` | [`catalog-vendor-context.md`](catalog-vendor-context.md) |
 | `src/codex/catalog/vendor-context.ts` | [`catalog-vendor-context.md`](catalog-vendor-context.md) |
+| `src/codex/provider-routing.ts` | [`codex-provider-routing.md`](codex-provider-routing.md) |
 | `src/codex/runtime.ts` | [`catalog-effort-clamp.md`](catalog-effort-clamp.md) |
 | `src/combos/` | [`runtime.md`](runtime.md)<br>[`providers-and-adapters.md`](providers-and-adapters.md)<br>[`providers/jev-decision.md`](providers/jev-decision.md) |
 | `src/companion/` | [`overview.md`](overview.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md)<br>[`companion.md`](companion.md) |
diff --git a/structure/cli-management.md b/structure/cli-management.md
index 6b59efcd821..249746bdb8e 100644
--- a/structure/cli-management.md
+++ b/structure/cli-management.md
@@ -127,3 +127,12 @@ Internal version observations in `src/service/managing-cli.ts` (`probeVersionOnc
 `src/cli/account-auth.ts` creates a Grok coupon operation UUID before every explicitly confirmed consume request unless the caller supplies one. Uncertain delivery and unknown-outcome API responses, including `operation_state_changed`, print guidance to preserve that same `--operation-id`; the CLI performs no automatic redemption retry. Ledger and reconciliation semantics are owned by [Grok reset coupons](providers/xai-grok.md#grok-reset-coupons-billing-api-parity).
 
 Remote Link enrollment is shared with the dashboard through `src/server/management/link-enrollment.ts` and `src/cli/link-enrollment.ts`. `ocx link probe <alias>` returns a temporary SSH fingerprint/key type/version offer. `ocx link add <alias> --expect-fingerprint SHA256:…` confirms exact trust and applies under loopback admin authority, with TTY explicit confirmation when the flag is omitted. Non-TTY omission fails before discovery. One Home URL and a 360-second deadline cover all requests and bodies; redirects are refused, credentials are never printed, and post-connect residual failures retain fixed recovery. `tests/cli/cli-link-enrollment.test.ts` verifies these boundaries. Child `link status` fallback uses the shared projector with persisted client connection and `clientLinkTunnelStatus`, plus validated client-owned sidecar/marker initiation identity; ambiguous evidence never invents direction. An unobserved Home-owned tunnel is conservatively idle. Link-mode `status` reads supported Hub projections via the local Child without sending a credential; a standalone Home role-based 404 explains absent Hub state rather than recommending an upgrade.
+
+## Custom Codex provider approval
+
+`src/cli/codex-provider.ts` exposes local status, per-ID allow and revoke operations.
+Allow previews the exact URL assignment before a default-No terminal confirmation and
+rechecks it under the config lock before saving. Noninteractive allow requires `--yes`;
+no prompt is issued during background start/sync. The
+[configuration contract](codex-provider-routing.md) owns scope,
+eligibility, drift refusal and recovery. No endpoint or credential is printed by this command.
diff --git a/structure/codex-home.md b/structure/codex-home.md
index d637ff05b6b..0166b86c7a3 100644
--- a/structure/codex-home.md
+++ b/structure/codex-home.md
@@ -45,7 +45,7 @@ set path that is unreadable or not a directory is an error, not a fallback: sile
 different home than the operator named would write provider state where nobody is looking for it. A proven missing home (including explicit `CODEX_HOME`) resolves lexically; native restore, remove and journal reconcile succeed without creating a directory or acquiring the config write lock. Dangling links do not prove absence, and existing homes retain ownership checks. Lock-path resolution never creates parents; unresolved parents yield a typed, handled refusal. Scalar and multi-agent feature edits refuse missing homes; prompt commits and native feature commands retain their directory creation before locking. The management native feature toggle resolves and retains the spawn invocation before preparing a home; unavailable executables return the toggle failure without creating it. Failed native toggles and prompt commits keep a home they created (`src/codex/prepared-home.ts`): a pathname-based removal cannot prove it still names that directory, and an empty home is what Codex itself creates. A fresh install can have that directory but no `config.toml` yet; applying the integration then creates an empty `config.toml` there (never overwriting an existing file) and continues, while a missing home directory is refused with instructions to start Codex once or set `CODEX_HOME` (issue 5422).
 On macOS, `src/codex/runtime.ts` tries the system then user ChatGPT.app bundle after environment, persisted selection, shim, PATH, established installs and a runnable bare fallback, preferring `Contents/Resources/codex-cli/bin/codex` over `Contents/Resources/codex`. Bundle membership compares the normalized and canonical (symlink-resolved) forms of the path and bundle with a segment boundary, including backing executables; candidate ordering keys on the generated app commands, so an established install path that links into the app keeps its precedence. Discovery and probe prechecks require exactly one top-level `CFBundleIdentifier` equal to `com.openai.codex` in a regular XML `Contents/Info.plist`, read in-process with a 64 KiB limit; the whole document must be valid plist XML, so binary, malformed (anywhere, not only in the identity pair), oversized or unavailable metadata fails closed. App candidates never supersede a runnable persisted selection, including legacy/discovered records and the fast path, but full discovery can report them in `newerAvailable`; invalid selections retain `replacedConfigured` recovery. When a verified app candidate exists, deferred discovery skips the bare fallback as a candidate and retains it only as the no-candidate sentinel.
 `src/codex/home.ts` imports path expansion directly from `src/config/paths.ts`, so a fresh WSL process can resolve its Codex home without re-entering the config facade before the resolver initializes.
-The managed files are:
+Provider-ID approvals are home-bound; see the [custom routing contract](codex-provider-routing.md). The managed files are:
 
 ```text
 $CODEX_HOME/config.toml
diff --git a/structure/codex-provider-routing.md b/structure/codex-provider-routing.md
new file mode 100644
index 00000000000..f40420655bc
--- /dev/null
+++ b/structure/codex-provider-routing.md
@@ -0,0 +1,20 @@
+# Custom Codex provider routing consent
+
+`src/codex/provider-routing.ts` stores explicit, home-bound provider-ID approvals in
+private OpenCodex-home recovery records. Default external-provider preservation remains
+unchanged. The approved path manages only the provider table's URL assignment, preserving
+provider identity, HTTP/WebSocket settings and history. It uses the shared config write
+lock and destination guards; recovery evidence precedes URL publication and retains the
+previous and candidate local URL across an interrupted write. Changed foreign URLs refuse
+injection and survive restore. Native restore completes its existing preflight before
+restoring approved URLs. Foreground signal/exit cleanup delegates to the same native restore, which restores approved URLs and preserves unapproved external configurations. Partial native outcomes remain partial, and recovery failures are reported in the config artifact. Consent survives stop/restore; explicit revocation removes it.
+Only Responses/OpenAI-auth provider tables without separate credentials or headers are
+eligible, and only ordinary loopback routing is admitted. Authless, client-compaction and
+admission-token targets are refused rather than silently changing authentication policy.
+
+`src/cli/codex-provider.ts` owns the default-No allow prompt, explicit `--yes` acknowledgment, status and revoke commands.
+
+Startup routing observation credits a custom provider as OpenCodex-local only when its
+actual loopback URL matches a URL recorded as published for that approved provider.
+Consent alone, an unapproved provider, or an independently changed local URL does not
+establish ownership. Existing service/shim availability still determines restart safety.
diff --git a/structure/config.md b/structure/config.md
index 2ddd9cc3719..54538121f2a 100644
--- a/structure/config.md
+++ b/structure/config.md
@@ -19,7 +19,7 @@ Connected-client catalog diagnostics use the [terminal rendering contract](runti
 
 Hub management ingress also selects the [local dashboard address](runtime.md#hub-management-dashboard-address) using its configured port.
 
-Native main reauthentication follows the [CLI JSON output contract](runtime.md#native-main-reauth-json-output).
+Native main reauthentication follows the [CLI JSON output contract](runtime.md#native-main-reauth-json-output). Provider-ID consent and URL-only recovery follow the [custom routing contract](codex-provider-routing.md).
 
 The Codex restart command follows the [CLI restart scope contract](runtime.md#cli-codex-restart-scope).
 
diff --git a/structure/manifest.json b/structure/manifest.json
index c115fcca7cf..09497e42f94 100644
--- a/structure/manifest.json
+++ b/structure/manifest.json
@@ -119,6 +119,13 @@
         "src/types.ts"
       ]
     },
+    {
+      "path": "codex-provider-routing.md",
+      "tier": 2,
+      "title": "Custom Codex Provider Routing",
+      "scope": "Explicit provider-ID routing consent, URL-only publication and recovery.",
+      "documents": ["src/codex/provider-routing.ts", "src/cli/codex-provider.ts"]
+    },
     {
       "path": "codex-home.md",
       "tier": 2,
diff --git a/structure/runtime.md b/structure/runtime.md
index 13c0097ced6..9acc468dddd 100644
--- a/structure/runtime.md
+++ b/structure/runtime.md
@@ -183,7 +183,7 @@ their own files. `src/grok/inject.ts` holds the shared canonical config-write lo
 
 ## Lifecycle
 
-Startup catalog sync and native restore apply the [retired-native policy](catalog.md#shared-catalog). Guarded tests isolate the owner registry used by cross-home discovery beneath their selected home, including children without a registry override; production retains the shared locator. See [test state isolation](ops/test-sandbox-cleanup.md).
+Startup catalog sync and native restore apply the [retired-native policy](catalog.md#shared-catalog). Foreground exit cleanup in `src/cli/index.ts` delegates restoration through the existing sibling/recycle teardown gates; approved external URLs follow [custom-provider consent](codex-provider-routing.md), while unapproved provider configuration and history remain unchanged. Guarded tests isolate the owner registry used by cross-home discovery beneath their selected home, including children without a registry override; production retains the shared locator. See [test state isolation](ops/test-sandbox-cleanup.md).
 `src/server/background-lifecycle.ts` registers low-quota protection for each live server, flushes pending saves before releasing its owner, binds its own event ledger to management requests, and unregisters it on failed startup or stop; with no pending save, owner release remains synchronous. The protection writer loads config persistence only when a threshold schedules a save; see [configuration](config.md#codex-pool-low-quota-protection). Codex quota processing has shared and Reserve scopes; retired model evidence is suppressed as
 described in [OpenAI quota ownership](providers/openai-tiers.md#public-provider-contract).
 
diff --git a/tests/ci-workflows/skill-ocx-generated.test.ts b/tests/ci-workflows/skill-ocx-generated.test.ts
index e95a32eca31..2101702fedb 100644
--- a/tests/ci-workflows/skill-ocx-generated.test.ts
+++ b/tests/ci-workflows/skill-ocx-generated.test.ts
@@ -11,7 +11,7 @@ const INDEX = "01_management_surface.md";
 const OWNER = "GENERATED by scripts/generate-ocx-skill-surface.ts";
 // Audited navigation contract, independent of the generator's internal assignment helper.
 const GROUPS: Record<string, string[]> = {
-  lifecycle: ["chatgpt", "status", "resolve", "capabilities", "sync", "start", "stop", "restart", "service", "gui"],
+  lifecycle: ["codex-provider", "chatgpt", "status", "resolve", "capabilities", "sync", "start", "stop", "restart", "service", "gui"],
   "providers-models": ["provider", "models", "alias"], accounts: ["account", "auth", "login", "logout"],
   "agents-routing": ["agent", "combo", "route", "v2", "effort", "memory", "message", "advisor"], integrations: ["claude", "integration", "commandcode", "grok", "codex-shim"],
   "observe-system": ["companion", "usage", "logs", "storage", "inspect", "system", "observe", "debug", "export", "import", "cost", "update", "config", "tray"],
diff --git a/tests/cli/cli-dispatch.test.ts b/tests/cli/cli-dispatch.test.ts
index 246238a8cd1..746b7cb021d 100644
--- a/tests/cli/cli-dispatch.test.ts
+++ b/tests/cli/cli-dispatch.test.ts
@@ -610,7 +610,7 @@ describe("a sibling start leaves shared client routing to the live owner", () =>
     const cleanup = slice("const syncCleanup = () => {", "let shuttingDown = false;");
     expect(cleanup).toContain("decideStartExitTeardown({ sibling: siblingStart, recycling: isRecyclingForExit(), ocxService: process.env.OCX_SERVICE })");
     expect(cleanup).toContain("if (teardown.revertSystemEnv) {");
-    expect(cleanup).toContain("if (teardown.restoreNativeCodex && !currentExternalCodexModelProvider()) {");
+    expect(cleanup).toContain("if (teardown.restoreNativeCodex) {");
     expect(cleanup).toContain("if (teardown.stripGrokConfig && serviceEnvironmentOwnedHere()) {");
     expect(cleanup).not.toContain("preserveRouting");
   });
diff --git a/tests/codex-integration/codex-provider-routing.test.ts b/tests/codex-integration/codex-provider-routing.test.ts
new file mode 100644
index 00000000000..df3d43bfb4c
--- /dev/null
+++ b/tests/codex-integration/codex-provider-routing.test.ts
@@ -0,0 +1,243 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { repoRoot } from "../helpers/repo-root";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { SPAWN_BUDGET_MS } from "../helpers/test-budget";
+
+let root: string, codexHome: string, ocxHome: string;
+const original = 'model_provider = "chatgpt-http"\n\n[model_providers."chatgpt-http"]\nname = "ChatGPT HTTP"\nbase_url = \'https://chatgpt.com/backend-api/codex\' # keep\nwire_api = "responses"\nrequires_openai_auth = true\nsupports_websockets = false\n';
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "ocx-provider-routing-"));
+  codexHome = join(root, "codex"); ocxHome = join(root, "ocx");
+  mkdirSync(codexHome); mkdirSync(ocxHome);
+  writeFileSync(join(codexHome, "config.toml"), original);
+  writeFileSync(join(codexHome, "history.jsonl"), "history sentinel\n");
+});
+afterEach(() => removeTreeWithRetry(root));
+
+function run(script: string, home = codexHome) {
+  const child = spawnSync(process.execPath, ["--eval", `
+    import { existsSync, readFileSync, writeFileSync } from "node:fs";
+    import { join } from "node:path";
+    import { allowCodexProviderRouting, previewCodexProviderConsent, approvedCodexProviders, restoreApprovedCodexProviders } from "./src/codex/provider-routing";
+    import { injectCodexConfig, restoreNativeCodex, restoreNativeCodexAsync } from "./src/codex/inject";
+    import { handleCodexProviderCommand } from "./src/cli/codex-provider";
+    const path = join(process.env.CODEX_HOME, "config.toml");
+    const id = "chatgpt-http";
+    const allow = () => allowCodexProviderRouting(id, previewCodexProviderConsent(id));
+    ${script}
+  `], { cwd: repoRoot(), env: { ...process.env, CODEX_HOME: home, OPENCODEX_HOME: ocxHome }, encoding: "utf8", timeout: SPAWN_BUDGET_MS - 5000 });
+  expect(child.status, child.stderr).toBe(0);
+  return child.stdout;
+}
+
+test("unapproved providers and noninteractive implicit consent leave config untouched", () => {
+  const output = run(`
+    const result = await injectCodexConfig(10100, {});
+    if (result.configApplied !== false) throw new Error("unapproved provider changed");
+    if (await handleCodexProviderCommand(["allow", id]) !== 1) throw new Error("missing consent accepted");
+    if (approvedCodexProviders().length) throw new Error("consent was saved");
+    console.log("unchanged");
+  `);
+  expect(output).toContain("unchanged");
+  expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toBe(original);
+});
+
+test.each(["sync", "async"])("approved provider follows port changes and restores exactly (%s)", kind => {
+  run(`
+    if (await handleCodexProviderCommand(["allow", id, "--yes"]) !== 0) throw new Error("consent failed");
+    const journal = join(process.env.CODEX_HOME, "opencodex-journal.json");
+    writeFileSync(journal, JSON.stringify({ version: 1, originalConfig: Buffer.from('model_provider = "openai"\\n').toString("base64"), originalProfile: null, opencodexHome: process.env.OPENCODEX_HOME }));
+    for (const port of [10100, 10101]) {
+      const result = await injectCodexConfig(port, {});
+      if (!result.success || result.configApplied === false) throw new Error("approved routing skipped");
+      const config = Bun.TOML.parse(readFileSync(path, "utf8"));
+      if (config.model_provider !== id || config.model_providers[id].supports_websockets !== false
+        || config.model_providers[id].base_url !== "http://127.0.0.1:" + port + "/v1") throw new Error("settings changed");
+    }
+    if (existsSync(journal)) throw new Error("stale native journal survived approved routing");
+    const result = ${kind === "async" ? "await restoreNativeCodexAsync()" : "restoreNativeCodex()"};
+    if (!result.success || !result.artifacts.config.changed) throw new Error("restore did not report its write");
+    if (!approvedCodexProviders().includes(id)) throw new Error("stop lost persistent consent");
+  `);
+  expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toBe(original);
+  expect(readFileSync(join(codexHome, "history.jsonl"), "utf8")).toBe("history sentinel\n");
+});
+
+test("URL drift is refused and revocation preserves a user-owned replacement", () => {
+  run(`
+    allow(); await injectCodexConfig(10100, {});
+    writeFileSync(path, readFileSync(path, "utf8").replace("http://127.0.0.1:10100/v1", "https://other.example/v1"));
+    let refused = false;
+    try { await injectCodexConfig(10101, {}); } catch { refused = true; }
+    if (!refused) throw new Error("URL drift accepted");
+    restoreApprovedCodexProviders(id);
+    if (approvedCodexProviders().length) throw new Error("revocation failed");
+  `);
+  expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toContain("https://other.example/v1");
+});
+
+test("prompt snapshot drift, credential-bearing providers and non-loopback targets are refused", () => {
+  run(`
+    const expected = previewCodexProviderConsent(id);
+    writeFileSync(path, readFileSync(path, "utf8").replace("https://chatgpt.com/backend-api/codex", "https://changed.example/v1"));
+    let refused = false;
+    try { allowCodexProviderRouting(id, expected); } catch { refused = true; }
+    if (!refused || approvedCodexProviders().length) throw new Error("stale confirmation accepted");
+    const clean = readFileSync(path, "utf8");
+    writeFileSync(path, clean + 'env_key = "PROVIDER_KEY"\\n');
+    refused = false;
+    try { allow(); } catch { refused = true; }
+    if (!refused) throw new Error("separate credential accepted");
+    writeFileSync(path, clean); allow();
+    refused = false;
+    try { await injectCodexConfig(10100, { hostname: "0.0.0.0" }); } catch { refused = true; }
+    if (!refused || readFileSync(path, "utf8") !== clean) throw new Error("non-loopback target changed config");
+  `);
+});
+
+test("validation is read-only, revocation restores managed URL and removes future permission", () => {
+  run(`
+    allow();
+    const before = readFileSync(path, "utf8");
+    await injectCodexConfig(10100, {}, { validateOnly: true });
+    if (readFileSync(path, "utf8") !== before) throw new Error("validation wrote config");
+    await injectCodexConfig(10100, {});
+    if (await handleCodexProviderCommand(["revoke", id]) !== 0) throw new Error("revoke failed");
+    const result = await injectCodexConfig(10100, {});
+    if (result.configApplied !== false) throw new Error("revoked provider changed");
+  `);
+  expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toBe(original);
+});
+
+
+test("explicit sync applies an approved provider instead of taking the external catalog-only path", () => {
+  run(`
+    allow();
+    const { syncModelsToCodex } = await import("./src/codex/sync");
+    const result = await syncModelsToCodex(10103, { providers: {} }, null, {
+      admitCodexWrite: () => ({ kind: "admitted" }),
+      injectCodexConfig,
+      currentExternalCodexModelProvider: () => id,
+      refreshCodexModelCatalog: async () => ({ added: 0, path: join(process.env.CODEX_HOME, "opencodex-catalog.json"), catalogExists: false, catalogWritten: false, cacheSynced: false, comboOmissions: [] }),
+    }, { catalogEvenWhenNotInjected: true });
+    if (!result.ok || result.status === "catalog-only") throw new Error("approved sync skipped injection");
+    if (Bun.TOML.parse(readFileSync(path, "utf8")).model_providers[id].base_url !== "http://127.0.0.1:10103/v1") throw new Error("sync did not publish URL");
+  `);
+});
+
+
+test("approving a provider in one Codex home does not approve the same ID in another", () => {
+  run("allow();");
+  const other = join(root, "other-codex");
+  mkdirSync(other); writeFileSync(join(other, "config.toml"), original);
+  run(`
+    if (approvedCodexProviders().length) throw new Error("consent leaked across homes");
+    const result = await injectCodexConfig(10100, {});
+    if (result.configApplied !== false) throw new Error("another home was routed");
+  `, other);
+  expect(readFileSync(join(other, "config.toml"), "utf8")).toBe(original);
+});
+
+
+test("a new process restores URL-only recovery after abrupt process exit", () => {
+  run("allow(); await injectCodexConfig(18272, {}); process.exit(0);");
+  expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toContain("http://127.0.0.1:18272/v1");
+  run(`
+    const result = await restoreNativeCodexAsync();
+    if (!result.success || !result.artifacts.config.changed) throw new Error("crash recovery failed");
+    if (!approvedCodexProviders().includes(id)) throw new Error("recovery lost consent");
+  `);
+  expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toBe(original);
+  expect(readFileSync(join(codexHome, "history.jsonl"), "utf8")).toBe("history sentinel\n");
+});
+
+test("reserved provider IDs cannot claim consent", () => {
+  run(`
+    const clean = readFileSync(path, "utf8");
+    for (const reserved of ["__proto__", "constructor", "prototype", "openai", "opencodex", "ollama", "lmstudio"]) {
+      writeFileSync(path, clean.replaceAll("chatgpt-http", reserved));
+      let refused = false;
+      try { allowCodexProviderRouting(reserved, previewCodexProviderConsent(reserved)); } catch (error) { refused = error.message.includes("Select a custom provider ID"); }
+      if (!refused || approvedCodexProviders().length) throw new Error("reserved ID admitted: " + reserved);
+      writeFileSync(path, clean);
+    }
+  `);
+  expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toBe(original);
+});
+
+test("concurrent sync processes leave a complete restorable config", () => {
+  run(`
+    allow();
+    const jobs = [18273, 18274, 18275].map(port => Bun.spawn([process.execPath, "--eval",
+      'import { injectCodexConfig } from "./src/codex/inject"; const result = await injectCodexConfig(' + port + ', {}); if (!result.success && !result.retryable) process.exit(2);'
+    ], { cwd: process.cwd(), env: process.env, stdout: "pipe", stderr: "pipe" }));
+    const exits = await Promise.all(jobs.map(job => job.exited));
+    if (exits.some(code => code !== 0)) throw new Error("concurrent sync failed: " + exits);
+    const config = Bun.TOML.parse(readFileSync(path, "utf8"));
+    if (![18273, 18274, 18275].some(port => config.model_providers[id].base_url === "http://127.0.0.1:" + port + "/v1")) throw new Error("no sync published");
+  `);
+  run("restoreApprovedCodexProviders();");
+  expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toBe(original);
+});
+
+
+test("approved restore preserves partial native outcome and reports recovery failures structurally", () => {
+  run(`
+    const { finishApprovedProviderRestore, skippedRestoreEnvelope } = await import("./src/codex/inject/restore");
+    allow(); await injectCodexConfig(18278, {});
+    const native = skippedRestoreEnvelope(true, "Native restore kept a provider table.");
+    native.artifacts.config = { state: "partial", changed: true, action: "routing-restored-provider-retained", message: "History-backed provider table retained." };
+    const restored = finishApprovedProviderRestore(native);
+    if (!restored.success || restored.artifacts.config.state !== "partial" || !restored.artifacts.config.message.includes("History-backed provider table retained")) throw new Error("partial outcome erased");
+    const { readdirSync } = await import("node:fs");
+    const record = readdirSync(process.env.OPENCODEX_HOME).find(name => name.startsWith("codex-provider-routing-") && name.endsWith(".json"));
+    writeFileSync(join(process.env.OPENCODEX_HOME, record), "broken record");
+    const failed = finishApprovedProviderRestore(native);
+    if (failed.success || failed.artifacts.config.state !== "failed" || !failed.artifacts.config.changed || !failed.message.includes("Approved Codex provider URL restoration failed")) throw new Error("recovery failure lost its artifact outcome");
+  `);
+});
+
+
+test("a crash between recovery publication and URL publication preserves both recovery candidates", () => {
+  run(`
+    allow(); await injectCodexConfig(18279, {});
+    const { setBeforeProviderRoutingPublishForTests } = await import("./src/codex/provider-routing");
+    setBeforeProviderRoutingPublishForTests(() => process.exit(0));
+    await injectCodexConfig(18280, {});
+    throw new Error("publication seam was not reached");
+  `);
+  expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toContain("http://127.0.0.1:18279/v1");
+  run(`
+    const { readdirSync } = await import("node:fs");
+    const record = readdirSync(process.env.OPENCODEX_HOME).find(name => name.startsWith("codex-provider-routing-") && name.endsWith(".json"));
+    const saved = JSON.parse(readFileSync(join(process.env.OPENCODEX_HOME, record), "utf8")).providers[id];
+    if (!saved.managedUrls.includes("http://127.0.0.1:18279/v1") || !saved.managedUrls.includes("http://127.0.0.1:18280/v1")) throw new Error("crash recovery candidates lost");
+    let busy = false;
+    try { restoreNativeCodex(); } catch (error) { busy = error.retryable === true; }
+    if (!busy) throw new Error("fresh crashed lock was not respected");
+    const { STALE_AFTER_MS } = await import("./src/codex/prompt-lock");
+    await Bun.sleep(STALE_AFTER_MS + 100);
+    const result = restoreNativeCodex();
+    if (!result.success) throw new Error(result.message);
+  `);
+  expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toBe(original);
+}, SPAWN_BUDGET_MS);
+
+
+test("startup health recognizes only the exact managed URL of an approved provider", () => {
+  run(`
+    const { getCodexRoutingKind } = await import("./src/codex/inject/routing-classify");
+    const before = readFileSync(path, "utf8");
+    writeFileSync(path, before.replace("https://chatgpt.com/backend-api/codex", "http://127.0.0.1:10100/v1"));
+    if (getCodexRoutingKind() !== "custom-local") throw new Error("unapproved URL was claimed");
+    writeFileSync(path, before); allow(); await injectCodexConfig(10100, {});
+    if (getCodexRoutingKind() !== "opencodex-local") throw new Error("managed route was not recognized");
+    writeFileSync(path, readFileSync(path, "utf8").replace("http://127.0.0.1:10100/v1", "http://127.0.0.1:19999/v1"));
+    if (getCodexRoutingKind() !== "custom-local") throw new Error("unrecorded URL was claimed");
+  `);
+});
diff --git a/tests/fixtures/test-layout-expected.json b/tests/fixtures/test-layout-expected.json
index 5e817d539f2..9b2994e8a26 100644
--- a/tests/fixtures/test-layout-expected.json
+++ b/tests/fixtures/test-layout-expected.json
@@ -1,4 +1,5 @@
 {
+  "codex-provider-routing.test.ts": "codex-integration",
   "messages-native-empty-inline.test.ts": "claude-integration",
   "explicit-empty-tool-catalog.test.ts": "responses",
   "explicit-empty-tool-catalog-history.test.ts": "responses",
diff --git a/tests/service/shutdown-launcher.test.ts b/tests/service/shutdown-launcher.test.ts
index b6045bf18a0..8b97d731168 100644
--- a/tests/service/shutdown-launcher.test.ts
+++ b/tests/service/shutdown-launcher.test.ts
@@ -95,9 +95,9 @@ async function waitUntil(fn: () => Promise<boolean>, deadlineMs: number): Promis
 }
 
 describe.skipIf(!runnable)("ocx launcher graceful shutdown", () => {
-  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) for (const approved of [false, true]) {
     test(
-      `${signal} to the launcher tears down the Bun proxy and restores Codex config (no orphan)`,
+      `${signal} to the launcher restores ${approved ? "approved" : "native"} Codex config (no orphan)`,
       async () => {
         const home = mkdtempSync(join(tmpdir(), "ocx-shutdown-"));
         tmpHomes.push(home);
@@ -107,7 +107,10 @@ describe.skipIf(!runnable)("ocx launcher graceful shutdown", () => {
         // Seed a native Codex config so the proxy actually injects on start (injectCodexConfig
         // no-ops when no config.toml exists) — this lets us prove the config is RESTORED.
         const codexConfig = join(home, "config.toml");
-        writeFileSync(codexConfig, 'model = "gpt-5.1"\n');
+        const original = approved
+          ? 'model_provider = "chatgpt-http"\n[model_providers.chatgpt-http]\nbase_url = "https://chatgpt.com/backend-api/codex"\nwire_api = "responses"\nrequires_openai_auth = true\nsupports_websockets = false\n'
+          : 'model = "gpt-5.1"\n';
+        writeFileSync(codexConfig, original);
         // Pin the configured port to this test's own port. `ocx start` probes the CONFIGURED
         // port for a live owner even with no state files, and a fresh home defaults to 10100.
         // On a developer machine running ocx there, the child found that proxy, took the sibling
@@ -123,9 +126,7 @@ describe.skipIf(!runnable)("ocx launcher graceful shutdown", () => {
         // startup regression. Locally the same spawn is healthy in ~800ms, so a
         // 25x margin is already generous and the missing evidence was the actual
         // problem.
-        const child = spawn("node", [BIN_OCX, "start", "--port", String(port)], {
-          stdio: ["ignore", "pipe", "pipe"],
-          env: {
+        const childEnv = {
             ...process.env,
             HOME: identity.homeDir,
             USERPROFILE: identity.userProfile,
@@ -136,7 +137,15 @@ describe.skipIf(!runnable)("ocx launcher graceful shutdown", () => {
             GROK_HOME: join(home, "grok"),
             OCX_OWNER_REGISTRY_DIR: join(identity.homeDir, ".opencodex", "ocx-homes"),
             ...identity.serviceManagerEnv,
-          },
+          };
+        if (approved) {
+          const consent = spawnSync(process.execPath, ["--eval", 'import { allowCodexProviderRouting, previewCodexProviderConsent } from "./src/codex/provider-routing"; allowCodexProviderRouting("chatgpt-http", previewCodexProviderConsent("chatgpt-http"));'], {
+            cwd: repoPath(), env: childEnv, encoding: "utf8", timeout: STARTUP_BUDGET_MS,
+          });
+          expect(consent.status, consent.stderr).toBe(0);
+        }
+        const child = spawn("node", [BIN_OCX, "start", "--port", String(port)], {
+          stdio: ["ignore", "pipe", "pipe"], env: childEnv,
         });
         spawned.push(child);
 
@@ -156,7 +165,7 @@ describe.skipIf(!runnable)("ocx launcher graceful shutdown", () => {
         const up = await waitUntil(async () => {
           if (!(await healthy(port))) return false;
           healthSeen = true;
-          return readFileSync(codexConfig, "utf8").includes(OCX_ROUTING_MARKER_LINE);
+          return readFileSync(codexConfig, "utf8").includes(approved ? `http://127.0.0.1:${port}/v1` : OCX_ROUTING_MARKER_LINE);
         }, STARTUP_BUDGET_MS);
         if (!up) {
           // Name what actually went wrong instead of asserting a bare boolean.
@@ -168,9 +177,14 @@ describe.skipIf(!runnable)("ocx launcher graceful shutdown", () => {
         }
         expect(existsSync(join(home, "ocx.pid"))).toBe(true);
         const injected = readFileSync(codexConfig, "utf8");
-        expect(injected).toContain(OCX_ROUTING_MARKER_LINE);
-        expect(injected).toContain(`openai_base_url = "http://127.0.0.1:${port}/v1"`);
-        expect(injected).not.toContain("model_providers.opencodex");
+        if (approved) {
+          expect(injected).toContain(`base_url = "http://127.0.0.1:${port}/v1"`);
+          expect(injected).toContain('model_provider = "chatgpt-http"');
+        } else {
+          expect(injected).toContain(OCX_ROUTING_MARKER_LINE);
+          expect(injected).toContain(`openai_base_url = "http://127.0.0.1:${port}/v1"`);
+          expect(injected).not.toContain("model_providers.opencodex");
+        }
 
         // 2. Signal ONLY the launcher PID (the exact orphan trigger).
         child.kill(signal);
@@ -187,6 +201,7 @@ describe.skipIf(!runnable)("ocx launcher graceful shutdown", () => {
         expect(existsSync(join(home, "ocx.pid"))).toBe(false);
         expect(existsSync(join(home, "runtime-port.json"))).toBe(false);
         expect(readFileSync(codexConfig, "utf8")).not.toContain("opencodex");
+        if (approved) expect(readFileSync(codexConfig, "utf8")).toBe(original);
       },
       STARTUP_BUDGET_MS + 40_000,
     );