@bitkyc08/opencodex 2.56.0 → 2.58.0

package/src/claude/desktop-profile.ts

@@ -22,8 +22,34 @@ export interface RenderedDesktopModel extends DesktopProfileModel {
   supports1m: boolean;
 }
 
-const DATE_ALIAS = /^claude-opus-4-8-(2026\d{4})$/;
-const DAY_COUNT_2026 = 365;
+// Managed-namespace date aliases run 2026-2035. The original 2026-only
+// (365 slots) design failed with "all 365 encoded date slots are occupied"
+// once a catalog exceeded 365 routes (stale assignments are retained by
+// design, so the set only grows). Years before 2026 stay rejected: dated
+// ids like `claude-opus-4-8-20250201` are real model snapshot ids, not
+// managed aliases, and the inbound decoder relies on that distinction.
+// Every emitted suffix stays 8 digits so modelMap date-stripping keeps
+// working.
+const DATE_ALIAS = /^claude-opus-4-8-(202[6-9]\d{4}|203[0-5]\d{4})$/;
+const LEGACY_YEAR = 2026;
+const LEGACY_DAY_COUNT = 365;
+const ALIAS_FIRST_YEAR = 2026;
+const ALIAS_LAST_YEAR = 2035;
+
+function isLeapYear(year: number): boolean {
+  return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+}
+
+function daysInAliasYear(year: number): number {
+  return isLeapYear(year) ? 366 : 365;
+}
+
+export const TOTAL_ALIAS_SLOTS = (() => {
+  let total = 0;
+  for (let year = ALIAS_FIRST_YEAR; year <= ALIAS_LAST_YEAR; year += 1) total += daysInAliasYear(year);
+  return total;
+})();
+export const ALIAS_YEAR_RANGE = { first: ALIAS_FIRST_YEAR, last: ALIAS_LAST_YEAR } as const;
 
 export class DesktopProfileError extends Error {
   constructor(message: string, readonly path = "profile") {
@@ -119,7 +145,7 @@ export function parseDesktopProfile(value: unknown): DesktopProfile {
     if (isRealAnthropicRoute(route)) {
       if (raw.alias !== routeModelId(route)) throw new DesktopProfileError("real Anthropic routes must keep their exact model id", `profile.assignments.${route}.alias`);
     } else if (!validDateAlias(raw.alias)) {
-      throw new DesktopProfileError("must be a valid claude-opus-4-8-2026MMDD alias", `profile.assignments.${route}.alias`);
+      throw new DesktopProfileError("must be a valid claude-opus-4-8-YYYYMMDD alias", `profile.assignments.${route}.alias`);
     }
     if (aliases.has(raw.alias)) throw new DesktopProfileError(`duplicate alias "${raw.alias}"`, `profile.assignments.${route}.alias`);
     aliases.add(raw.alias);
@@ -144,26 +170,57 @@ export function parseDesktopProfile(value: unknown): DesktopProfile {
   return { version: 1, assignments, defaults, ...appliedMarkers(value) };
 }
 
-function dayOfYearAlias(dayIndex: number): string {
-  const date = new Date(Date.UTC(2026, 0, dayIndex + 1));
+function formatSlotDate(year: number, dayOfYear: number): string {
+  const date = new Date(Date.UTC(year, 0, dayOfYear));
   const y = date.getUTCFullYear();
   const m = String(date.getUTCMonth() + 1).padStart(2, "0");
   const d = String(date.getUTCDate()).padStart(2, "0");
   return `claude-opus-4-8-${y}${m}${d}`;
 }
 
+// Legacy 2026 ring, byte-identical to the original allocator: the same route
+// must keep resolving to the same 2026 alias it always had, and a probe over
+// a nearly-full 2026 set must land on the same free date as before.
+function legacyDayAlias(dayIndex: number): string {
+  return formatSlotDate(LEGACY_YEAR, dayIndex + 1);
+}
+
+// Overflow ring for catalogs past 365 routes (2027-2035). Probed only after
+// every legacy slot is taken, so existing profiles never shift into it.
+const OVERFLOW_FIRST_YEAR = LEGACY_YEAR + 1;
+const OVERFLOW_SLOT_COUNT = TOTAL_ALIAS_SLOTS - LEGACY_DAY_COUNT;
+
+function overflowSlotAlias(slotIndex: number): string {
+  let remaining = ((slotIndex % OVERFLOW_SLOT_COUNT) + OVERFLOW_SLOT_COUNT) % OVERFLOW_SLOT_COUNT;
+  for (let year = OVERFLOW_FIRST_YEAR; year <= ALIAS_LAST_YEAR; year += 1) {
+    const days = daysInAliasYear(year);
+    if (remaining < days) return formatSlotDate(year, remaining + 1);
+    remaining -= days;
+  }
+  throw new DesktopProfileError("slot index out of range", "profile.assignments");
+}
+
 function routeStartDay(route: string): number {
-  return createHash("sha256").update(route).digest().readUInt32BE(0) % DAY_COUNT_2026;
+  return createHash("sha256").update(route).digest().readUInt32BE(0) % LEGACY_DAY_COUNT;
+}
+
+function routeOverflowStart(route: string): number {
+  return createHash("sha256").update(route).digest().readUInt32BE(4) % OVERFLOW_SLOT_COUNT;
 }
 
 function allocateAlias(route: string, used: Set<string>): string {
   if (isRealAnthropicRoute(route)) return routeModelId(route);
   const start = routeStartDay(route);
-  for (let offset = 0; offset < DAY_COUNT_2026; offset += 1) {
-    const alias = dayOfYearAlias((start + offset) % DAY_COUNT_2026);
+  for (let offset = 0; offset < LEGACY_DAY_COUNT; offset += 1) {
+    const alias = legacyDayAlias((start + offset) % LEGACY_DAY_COUNT);
+    if (!used.has(alias)) return alias;
+  }
+  const overflowStart = routeOverflowStart(route);
+  for (let offset = 0; offset < OVERFLOW_SLOT_COUNT; offset += 1) {
+    const alias = overflowSlotAlias((overflowStart + offset) % OVERFLOW_SLOT_COUNT);
     if (!used.has(alias)) return alias;
   }
-  throw new DesktopProfileError("all 365 encoded date slots are occupied", `profile.assignments.${route}.alias`);
+  throw new DesktopProfileError(`all ${TOTAL_ALIAS_SLOTS} encoded date slots are occupied`, `profile.assignments.${route}.alias`);
 }
 
 export function reconcileDesktopProfile(

package/src/claude/outbound.ts

@@ -189,7 +189,7 @@ function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resultConte
   return { id, input, resultContent, completed };
 }
 
-function messageSnapshot(model: string): Rec {
+function messageSnapshot(model: string, confirmedUsage?: Rec): Rec {
   return {
     id: `msg_${uuid()}`,
     type: "message",
@@ -198,7 +198,7 @@ function messageSnapshot(model: string): Rec {
     model,
     stop_reason: null,
     stop_sequence: null,
-    usage: { input_tokens: 0, output_tokens: 0 },
+    usage: confirmedUsage ?? { input_tokens: 0, output_tokens: 0 },
   };
 }
 
@@ -212,6 +212,8 @@ interface OpenBlock {
   argsBuf?: string;
   argsBufBytes?: number;
   webSearchArgsEmitted?: boolean;
+  /** True once ordinary function-call arguments were emitted to Anthropic SSE. */
+  toolArgsEmitted?: boolean;
   callId?: string;
   /** Last fixed-size reasoning identity (item + summary/content index) seen by this block. */
   reasoningPartKey?: string;
@@ -244,6 +246,7 @@ export function responsesSseToAnthropicSse(
   let open: OpenBlock | null = null;
   let sawToolUse = false;
   let webSearchRequests = 0;
+  let earlyAnthropicUsage: Rec | undefined;
   let pingTimer: ReturnType<typeof setInterval> | undefined;
   let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
   const utf8SliceBytes = (value: string, start: number, end: number): number => {
@@ -280,7 +283,7 @@ export function responsesSseToAnthropicSse(
       const ensureStarted = () => {
         if (started) return;
         started = true;
-        emit("message_start", { type: "message_start", message: messageSnapshot(model) });
+        emit("message_start", { type: "message_start", message: messageSnapshot(model, earlyAnthropicUsage) });
         emit("ping", { type: "ping" });
       };
       // Keepalive pings protect remote deployments behind LB/NAT idle timeouts even
@@ -403,8 +406,17 @@ export function responsesSseToAnthropicSse(
       const handleFrame = (eventName: string, data: Rec) => {
         switch (eventName) {
           case "response.created":
-            // Transport prelude only. Start Anthropic framing on semantic output or completion.
+          case "response.in_progress": {
+            // Lifecycle preludes do not start Anthropic framing, but some upstreams attach
+            // confirmed input usage before semantic output. Retain only its bounded Anthropic
+            // projection so message_start can report measurements that already arrived.
+            const response = isRec(data.response) ? data.response : {};
+            const usage = isRec(response.usage) ? response.usage : undefined;
+            if (!started && usage && typeof usage.input_tokens === "number") {
+              earlyAnthropicUsage = anthropicUsage(usage);
+            }
             break;
+          }
           case "response.heartbeat":
             if ((controller.desiredSize ?? 0) > 0) emit("ping", { type: "ping" });
             break;
@@ -488,6 +500,7 @@ export function responsesSseToAnthropicSse(
               argsBuf: "",
               argsBufBytes: 0,
               webSearchArgsEmitted: false,
+              toolArgsEmitted: false,
             };
             break;
           }
@@ -518,6 +531,14 @@ export function responsesSseToAnthropicSse(
               type: "content_block_delta", index: open.index,
               delta: { type: "input_json_delta", partial_json: data.delta },
             });
+            open.toolArgsEmitted = true;
+            break;
+          }
+          case "response.function_call_arguments.done": {
+            if (!open || open.kind !== "tool_use" || open.bufferWebSearchArgs || open.toolArgsEmitted) break;
+            if (typeof data.arguments !== "string" || data.arguments.length === 0) break;
+            emit("content_block_delta", { type: "content_block_delta", index: open.index, delta: { type: "input_json_delta", partial_json: data.arguments } });
+            open.toolArgsEmitted = true;
             break;
           }
           case "response.output_item.done": {
@@ -565,6 +586,13 @@ export function responsesSseToAnthropicSse(
                   delta: { type: "input_json_delta", partial_json: JSON.stringify(sanitizeWebSearchInput(parsed)) },
                 });
                 open.webSearchArgsEmitted = true;
+              } else if (!open.bufferWebSearchArgs && !open.toolArgsEmitted
+                && typeof item.arguments === "string" && item.arguments.length > 0) {
+                emit("content_block_delta", {
+                  type: "content_block_delta", index: open.index,
+                  delta: { type: "input_json_delta", partial_json: item.arguments },
+                });
+                open.toolArgsEmitted = true;
               }
               closeOpenBlock();
             }

package/src/cli/account-main.ts

@@ -245,7 +245,7 @@ export async function cmdNativeMainAccount(args: string[], deps: AccountDeps): P
     }
     if (noWait) {
       printStatus({ flowId: startFlowId, ...pending });
-      console.log("follow up: ocx account main reauth status --flow " + startFlowId);
+      if (!wantsJson) console.log("follow up: ocx account main reauth status --flow " + startFlowId);
       return 0;
     }
     // Blocking wait bounded by the service flow expiry (15-minute grant + margin).

package/src/cli/capabilities.ts

@@ -710,10 +710,10 @@ export const CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["system", "codex-restart"],
-    summary: "Restart the Codex app-server.",
+    summary: "Restart the Codex desktop app and app-servers.",
     routes: [{ method: "POST", path: "/api/system/codex-restart" }],
     flags: [
-      { name: "--yes", value: "boolean", summary: "Required: restarts the operator's running Codex app-server." },
+      { name: "--yes", value: "boolean", summary: "Required: fully quits and relaunches the operator's Codex desktop app and restarts its app-servers." },
       { name: "--json", value: "boolean", summary: "Emit the restart result as JSON." },
     ],
     mutates: true,

package/src/cli/combo.ts

@@ -15,7 +15,8 @@ const USAGE = `Usage:
   ocx combo show <id> [--json]
   ocx combo set <id> --targets <provider/model[:weight],...>
       [--strategy <failover|round-robin|random|least-used|reset-window>] [--sticky <1-100>]
-      [--effort <low|medium|high|xhigh|max|ultra|->] [--alias <name|->]
+      [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force>]
+      (force overrides valid client effort and can increase cost/latency) [--alias <name|->]
       [--native-alias] [--display-name <label|->]
       [--rename-from <id>] [--json]
   ocx combo remove <id> --yes [--json]`;
@@ -80,6 +81,10 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     if (strategy !== "round-robin") throw new CliUsageError("--sticky applies only to round-robin", USAGE);
   }
   const effort = takeOption(args, "--effort");
+  const effortMode = takeOption(args, "--effort-mode");
+  if (effortMode !== undefined && effortMode !== "fallback" && effortMode !== "force") {
+    throw new CliUsageError("--effort-mode must be fallback or force", USAGE);
+  }
   const alias = takeOption(args, "--alias");
   const nativeAlias = takeFlag(args, "--native-alias");
   const displayName = takeOption(args, "--display-name");
@@ -91,12 +96,16 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     targets: parseTargets(targetsRaw),
   };
   if (effort !== undefined) combo.defaultEffort = effort === "-" ? null : effort;
+  if (effortMode !== undefined) combo.defaultEffortMode = effortMode;
   if (alias !== undefined) combo.alias = alias === "-" ? "" : alias;
   if (nativeAlias) combo.nativeAlias = true;
   if (displayName !== undefined) combo.displayName = displayName === "-" ? "" : displayName;
   const current = await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", {}, deps);
   const existing = (current.combos ?? []).find(row => row.id === (renameFrom ?? id));
   if (existing?.imageInput === "disabled") combo.imageInput = "disabled";
+  if (effortMode === undefined && existing?.defaultEffortMode === "force") {
+    combo.defaultEffortMode = effort === "-" ? "fallback" : "force";
+  }
   const result = await runtimeRequest("/api/combos", {
     method: "PUT",
     body: JSON.stringify({ id, combo, ...(renameFrom ? { renameFrom } : {}) }),

package/src/cli/config-command.ts

@@ -4,7 +4,7 @@ import { getConfigPath, mutatePersistedConfig, readConfigDiagnostics, sanitizeMo
 import { VISION_REASONING_EFFORTS, isVisionReasoningEffort } from "../reasoning-effort";
 import type { OcxConfig } from "../types";
 import { normalizeVisionReasoningForModel } from "../vision/reasoning";
-import type { ClientConnectionStatus } from "./connect";
+import type { ServiceApiTokenState } from "../lib/service-secrets";
 import { CliUsageError, printData, rejectArgs, runCliAction, takeFlag } from "./runtime-api";
 
 const USAGE = `Usage:
@@ -38,9 +38,8 @@ const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
  * `client` block, which is the same defect in miniature: the presence of configuration is not
  * evidence that the connection works, and a machine whose data-plane token was revoked, rotated
  * away or deleted would have been labelled `connected: true` while it could not reach the hub at
- * all. `collectClientConnectionStatus` is the one reader that knows — it compares the token file's
- * fingerprint against the connection record — so the caller passes its answer in and this stays
- * pure and testable.
+ * all. The read-only projection compares the bounded token file's fingerprint against the
+ * connection record, and passes that answer in so this formatter stays pure and testable.
  *
  * Synthetic and NOT persisted, for two reasons. `clientConnectionSchema` is `.strict()`, so a
  * `client.note` field would not validate; and persisted prose drifts from the behaviour it
@@ -49,7 +48,7 @@ const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
  */
 export function remoteHubConfigNote(
   config: OcxConfig,
-  readConnection: () => Pick<ClientConnectionStatus, "state" | "reason" | "token">,
+  readConnection: () => RemoteHubConnectionObservation,
 ): { connected: boolean; origin: string; note: string } | null {
   if (config.runtimeRole !== "client" || !config.client) return null;
   // A thunk, so a standalone or hub install pays nothing: the guard above returns first and the
@@ -67,6 +66,36 @@ export function remoteHubConfigNote(
   return { connected, origin: config.client.serverUrl, note };
 }
 
+export type RemoteHubConnectionObservation = {
+  state: "disconnected" | "connected" | "invalid" | "mismatched";
+  reason?: string;
+  token: "owned" | "missing" | "changed" | "unsafe";
+};
+
+export function remoteHubConnectionFromTokenState(
+  config: Pick<OcxConfig, "client">,
+  tokenState: ServiceApiTokenState,
+): RemoteHubConnectionObservation {
+  const token = tokenState.kind === "absent"
+    ? "missing"
+    : tokenState.kind === "unsafe"
+      ? "unsafe"
+      : tokenState.fingerprint === config.client?.tokenFingerprint ? "owned" : "changed";
+  return { state: "connected", token };
+}
+
+async function readRemoteHubConfigNote(config: OcxConfig): Promise<ReturnType<typeof remoteHubConfigNote>> {
+  if (config.runtimeRole !== "client" || !config.client) return null;
+  // This display command needs only connection ownership, not lifecycle recovery, catalog
+  // readiness, or any write-capable connect machinery. Keep the read on the bounded token
+  // observer so a cold `config show` never imports the full connect command graph.
+  const { readServiceApiTokenState } = await import("../lib/service-secrets");
+  return remoteHubConfigNote(
+    config,
+    () => remoteHubConnectionFromTokenState(config, readServiceApiTokenState()),
+  );
+}
+
 function redact(value: unknown, key = ""): unknown {
   if (SECRET_KEYS.test(key) && typeof value === "string") return value ? "********" : value;
   // `client.priorCatalog` is the base64 catalog snapshot connect took before overwriting the
@@ -168,19 +197,7 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       rejectArgs(args, USAGE);
       const diagnostics = readConfigDiagnostics();
       const redacted = redact(diagnostics.config);
-      // Imported here rather than at module scope: `./connect` pulls the whole client lifecycle
-      // in, and `ocx config get/set` has no use for it.
-      const { collectClientConnectionStatus } = await import("./connect");
-      // The readiness probe is declined explicitly. `collectClientConnectionStatus` observes the
-      // local Codex ladder for a connected client, and observing it spawns `codex debug models`
-      // under a 45s budget. `ocx config show` reads only `state`, `reason` and `token` from the
-      // result, so paying for a subprocess here would buy nothing and would quietly turn a
-      // read-only config dump into a runtime probe. Returning no ladder resolves readiness to
-      // `unverified`, which is the honest answer for a caller that never asked.
-      const note = remoteHubConfigNote(
-        diagnostics.config,
-        () => collectClientConnectionStatus(undefined, undefined, { supportedEfforts: () => null }),
-      );
+      const note = await readRemoteHubConfigNote(diagnostics.config);
       // First key, not last: it has to be read before the empty `providers` map that misled a
       // reader into concluding nothing was configured anywhere.
       const config = note && redacted && typeof redacted === "object" && !Array.isArray(redacted)

package/src/cli/dispatch.ts

@@ -24,7 +24,7 @@ import {
 } from "../codex/desired-state";
 import { syncModelsToCodex } from "../codex/sync";
 import { collectOrcaCodexHomeDiagnostic } from "../codex/home";
-import { restoreNativeCodexAsync } from "../codex/inject";
+import { restoreNativeCodexAsync, type CodexNativeRestoreResult } from "../codex/inject";
 import { stripGrokConfig } from "../grok/inject";
 import { handleRestartScopeAfterWrite, readRestartScope, type RestartScope } from "./restart-scope";
 import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
@@ -106,6 +106,7 @@ const commandRunners: Record<string, CommandRunner> = {
   restore: async deps => {
     const restoreArgs = deps.args.slice(1);
     const restoreJson = takeFlag(restoreArgs, "--json");
+    const removeProviderTable = takeFlag(restoreArgs, "--remove-codex-provider-table");
     if (restoreArgs[0] === "back") {
       // Reverse switch: re-point plain `codex` at the RUNNING proxy without touching its
       // lifecycle — the counterpart of `ocx restore`. Start/stop triggers are unchanged;
@@ -146,6 +147,9 @@ const commandRunners: Record<string, CommandRunner> = {
       const target = collectOrcaCodexHomeDiagnostic();
       return emitBack(true, `Plain \`codex\` now routes through opencodex in ${target.effectiveCodexHome} (undo with: ocx restore).`, 0);
     }
+    if (removeProviderTable && !restoreJson) {
+      console.log("⚠️  Removing [model_providers.opencodex] means conversations already tagged opencodex will stop opening.");
+    }
     const desired = setIntegrationEnabled("codex", false);
     if (!desired.ok) {
       if (restoreJson) {
@@ -191,9 +195,9 @@ const commandRunners: Record<string, CommandRunner> = {
         return grokCode;
       }
     }
-    let r: { success: boolean; message: string };
+    let r: CodexNativeRestoreResult | Pick<CodexNativeRestoreResult, "success" | "message">;
     try {
-      r = await restoreNativeCodexAsync({ revalidateDesiredState: true });
+      r = await restoreNativeCodexAsync({ revalidateDesiredState: true, removeProviderTable });
     } catch (err) {
       r = { success: false, message: err instanceof Error ? err.message : String(err) };
     }
@@ -232,7 +236,16 @@ const commandRunners: Record<string, CommandRunner> = {
       code = 1;
     }
     if (r.success) {
-      console.log("Codex integration is OFF and plain `codex` now runs natively. Switch back with: ocx restore back");
+      const retained = "retainedCodexProviderTable" in r ? r.retainedCodexProviderTable : undefined;
+      if (retained) {
+        console.log("Codex integration is OFF and plain `codex` now runs natively.");
+        console.log("The following lines remain in $CODEX_HOME/config.toml because conversations already tagged opencodex resolve their provider only through this table:");
+        console.log(retained.lines.join("\n"));
+        console.log(`Follow-up: ${retained.followUp}`);
+        console.log("Switch back with: ocx restore back");
+      } else {
+        console.log("Codex integration is OFF and plain `codex` now runs natively. Switch back with: ocx restore back");
+      }
       console.log(`Note: ${OCX_NATIVE_REPLAY_RECOVERY_NOTE}`);
     } else {
       console.error("Plain `codex` was not fully restored. Inspect $CODEX_HOME/config.toml before using native Codex.");

package/src/cli/index.ts

@@ -13,9 +13,22 @@ try {
     /* best-effort */
   }
 }
-import { currentExternalCodexModelProvider, restoreNativeCodex, restoreNativeCodexAsync, shouldInjectApiAuthHeader } from "../codex/inject";
+import {
+  currentExternalCodexModelProvider,
+  restoreNativeCodex,
+  restoreNativeCodexAsync,
+  shouldInjectApiAuthHeader,
+} from "../codex/inject";
+// Straight from the owning modules rather than the facade: these are teardown-reporting
+// helpers, not part of the injection surface, and `inject.ts` sits under a size cap that
+// exists to stop it collecting exactly this kind of passthrough.
+import { readOcxProviderTableBlock } from "../codex/inject/remove";
+import {
+  describeRetainedCodexProviderTable,
+  type RetainedCodexProviderTable,
+} from "../codex/inject/restore";
 import { stripGrokConfig } from "../grok/inject";
-import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "../update/stop-contract.mjs";
+import { STOP_HISTORY_DEFERRED_EXIT_CODE, STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "../update/stop-contract.mjs";
 import {
   describeHistoryJobFailure,
   resolveCodexHistoryJobTarget,
@@ -46,6 +59,7 @@ import {
   isPendingTeardownAbandoned,
   listPendingTeardowns,
   pendingTeardownPathFor,
+  pendingTeardownsAreExactly,
   quarantinePendingTeardown,
 } from "../config/pending-teardown";
 import { collectStatus, hubStatusLines, remoteHubBannerLine, remoteHubStatusLines, unusedProxyWarningLines } from "./status";
@@ -118,6 +132,12 @@ function reportShellHookFailure(result: { state: "installed" | "absent" | "faile
   console.warn("   Check ~/.zshrc for the '# opencodex claude-env hook' block.");
 }
 
+function reportRetainedCodexProviderTable(retained: RetainedCodexProviderTable): void {
+  console.log(`   ${describeRetainedCodexProviderTable(retained)}`);
+  console.log("   Retained config lines:");
+  for (const line of retained.lines) console.log(`      ${line}`);
+}
+
 async function refreshOwnedRaycastCatalog(
   config: ReturnType<typeof loadConfig>,
   port: number,
@@ -785,20 +805,44 @@ async function handleRestartStartWhenStopped(): Promise<boolean | "skipped"> {
  *
  * The distinction exists because `ocx update` must proceed for the first and abort for the
  * second, and it can only see an exit code (#3008).
+ *
+ * `historyDeferred` is the third kind (#4718). The Codex history preflight refuses BEFORE
+ * the config half runs, so nothing was restored at all: config, catalog, history and
+ * provenance are untouched and the client is still routed at the proxy that just stopped.
+ * Like `historyOnly` the proxy is genuinely down, so an update may replace package files.
+ * Unlike `historyOnly` the obligation was not performed, so the receipt must survive.
  */
-async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boolean; other: boolean }> {
+async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boolean; historyDeferred: boolean; other: boolean }> {
   let historyOnly = false;
+  let historyDeferred = false;
   let other = false;
   try {
     const result = await restoreNativeCodexAsync();
-    if (result.success) console.log(`↩️  ${result.message}`);
+    if (result.success) {
+      console.log(`↩️  ${result.message}`);
+      if (result.retainedCodexProviderTable) {
+        reportRetainedCodexProviderTable(result.retainedCodexProviderTable);
+      }
+    }
     else {
       // Codex history is the one restore whose failure leaves the runtime consistent: the
       // manifest is retained and the routed metadata is untouched. Config and catalog are
       // not — a client reads those, so their failure is a real teardown failure.
       const artifacts = result.artifacts;
       const configOrCatalogFailed = artifacts.config.state === "failed" || artifacts.catalog.state === "failed";
-      if (!configOrCatalogFailed && artifacts.history.state === "failed") historyOnly = true;
+      // A preflight refusal reports every artifact as `skipped` because none of them were
+      // attempted. Reading the states alone cannot tell that apart from an ownership
+      // refusal, so the structured reason carries it and the states are still required to
+      // agree — a refusal that somehow reports a failed artifact is not this case.
+      // A degraded restore has no refusal reason and reports config as partial, so it cannot
+      // enter this branch: its config obligation was discharged and the stop receipt must be
+      // released rather than preserved.
+      const preflightRefused = result.historyPreflightRefusal !== undefined
+        && artifacts.config.state === "skipped"
+        && artifacts.catalog.state === "skipped"
+        && artifacts.history.state === "skipped";
+      if (preflightRefused) historyDeferred = true;
+      else if (!configOrCatalogFailed && artifacts.history.state === "failed") historyOnly = true;
       else other = true;
       console.error(`⚠️  ${result.message}`);
     }
@@ -816,7 +860,7 @@ async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boole
     other = true;
     console.error(`⚠️  Grok config restore failed: ${error instanceof Error ? error.message : String(error)}`);
   }
-  return { historyOnly, other };
+  return { historyOnly, historyDeferred, other };
 }
 
 async function handleStop() {
@@ -860,6 +904,11 @@ async function handleStop() {
   };
   let stopFailed = false;
   let historyOnlyFailure = false;
+  /**
+   * Obligations this run deliberately kept because the Codex history preflight refused
+   * before restoring anything (#4718). Non-null selects the deferred exit code.
+   */
+  let historyDeferredNonces: string[] | null = null;
   // Only Task Scheduler respawns after a successful stop (#764), so only it earns the
   // restart-window wait; launchd, systemd and WinSW are down when they say so.
   let schedulerCanRespawn = false;
@@ -1138,6 +1187,7 @@ async function handleStop() {
     }
     const restore = await restoreSharedClientStateAfterStop();
     if (restore.other) stopFailed = true;
+    else if (restore.historyDeferred) historyDeferredNonces = teardownNonce ? [teardownNonce, ...recoveredNonces] : recoveredNonces;
     else if (restore.historyOnly) historyOnlyFailure = true;
     // The obligation is discharged whether or not history metadata finalized: config and
     // catalog are what a client reads, and `restore.other` already fails the stop.
@@ -1145,7 +1195,16 @@ async function handleStop() {
     // Each nonce names its own file, so a clear can only ever remove the obligation it
     // names — never one a concurrent stop wrote. Both this run's claim and every inherited
     // receipt it proved discharged are released together.
-    if (!restore.other) {
+    //
+    // A history-preflight refusal is the exception: it restored nothing, so there is
+    // nothing to discharge. Clearing here would drop a real obligation on the floor and
+    // leave the client config pointing at a proxy that is gone, with nothing on disk
+    // saying so — which is the whole failure the receipt exists to prevent (#4718).
+    if (restore.historyDeferred) {
+      console.error("   The shared teardown was refused before it changed anything, so it is still owed.");
+      console.error("   Its receipt is preserved; run 'ocx stop' again once Codex is closed to retry the restore.");
+    }
+    if (!restore.other && !restore.historyDeferred) {
       const discharged = teardownNonce ? [teardownNonce, ...recoveredNonces] : recoveredNonces;
       for (const nonce of discharged) {
         // A receipt that survives its discharge re-triggers recovery forever, so a failed
@@ -1185,6 +1244,17 @@ async function handleStop() {
   // still wins: it is the stronger signal.
   if (stopFailed) process.exitCode = 1;
   else if (historyOnlyFailure) process.exitCode = STOP_HISTORY_INCOMPLETE_EXIT_CODE;
+  // The deferred code says "the only obligations left are the ones I just decided to
+  // keep". It is read across a process boundary by an updater that will replace package
+  // files on the strength of it, so this run has to be able to prove the claim: if any
+  // other obligation is sitting in the home — quarantined, or a concurrent stop's — the
+  // claim is false and the ordinary failure code is the honest answer. That is also the
+  // behaviour before #4718, so the fallback loses nothing that used to work.
+  else if (historyDeferredNonces) {
+    process.exitCode = pendingTeardownsAreExactly(historyDeferredNonces)
+      ? STOP_HISTORY_DEFERRED_EXIT_CODE
+      : 1;
+  }
   return !stopFailed;
 }
 
@@ -1314,6 +1384,9 @@ async function handleUninstall() {
     await runStep("native Codex restored", async () => {
       const r = await restoreNativeCodexAsync();
       if (!r.success) throw new Error(r.message);
+      if (r.retainedCodexProviderTable) {
+        reportRetainedCodexProviderTable(r.retainedCodexProviderTable);
+      }
     });
 
     await runStep("Grok Build config restored", () => {
@@ -1460,6 +1533,18 @@ async function handleStatus() {
   console.log(`   Codex autostart: ${status.json.codexAutostart ? "enabled" : "disabled"}${local}`);
   console.log(`   Restart safety: ${startupHealthSummary(status.json.startup)}${local}`);
   console.log(`   ${formatStartupRoutingDetail(status.json.startup)}${local}`);
+  if (status.json.startup.routingKind === "native") {
+    let retainedProviderTable = false;
+    try {
+      retainedProviderTable = readOcxProviderTableBlock() !== null;
+    } catch {
+      // The routing snapshot owns unreadable-config reporting. A later read race must not
+      // turn this diagnostic command into a teardown failure.
+    }
+    if (retainedProviderTable) {
+      console.log(`   ⚠️  Codex provider table retained${local}: [model_providers.opencodex] remains while root routing is native. Remove with 'ocx restore --remove-codex-provider-table'; tagged conversations will stop opening.`);
+    }
+  }
   console.log(`   Service: ${status.json.service.summary}${local}`);
   console.log(`   ${status.json.codexShim.summary}${local}`);
   console.log(`   Codex runtime: ${status.json.codexRuntime.path}${local}`);

package/src/cli/registry.ts

@@ -407,7 +407,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Ensures the proxy is running, then execs `claude` with ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN,",
       "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 and model slots from config.claudeCode.",
       "When Claude routing is explicitly disabled, it launches natively after removing proven OpenCodex-owned proxy state.",
-      "Routed models appear in the native /model picker with stable claude-opus-4-8-2026MMDD slot aliases (Claude Code >= 2.1.129).",
+      "Routed models appear in the native /model picker with stable claude-opus-4-8-YYYYMMDD slot aliases,",
+      "where the year runs 2026-2035 and 2026 slots are allocated first (Claude Code >= 2.1.129).",
       "Older versions: pick models via ANTHROPIC_MODEL or /model <id> directly (any string passes through).",
       "User-exported ANTHROPIC_* variables take precedence for routed launches; native fallback removes only proven OpenCodex-owned proxy values.",
       "",