@yansigit/opencodex 2.31.3 → 2.32.0

package/src/adapters/google.ts

@@ -14,7 +14,7 @@ import type {
   OcxToolResultMessage,
   OcxUsage,
 } from "../types";
-import { isAllowedToolChoice, namespacedToolName, resolveToolChoiceWireName, toolAllowedByChoice } from "../types";
+import { isAllowedToolChoice, namespacedToolName, resolveToolChoiceWireName, toolChoiceToolPredicate } from "../types";
 import { contentPartsToText, parseDataUrl } from "./image";
 import { getVertexAccessToken } from "../lib/gcp-adc";
 import { fetchAntigravityWithRetry, fetchVertexWithRetry } from "./google-http";
@@ -346,11 +346,8 @@ function toolsToGeminiFormat(
   wireModelId: string,
 ): unknown[] | undefined {
   const grounding = parsed._ccaInTurnGrounding;
-  const allowed = isAllowedToolChoice(parsed.options.toolChoice)
-    ? new Set(parsed.options.toolChoice.allowedTools)
-    : undefined;
-  const tools = allowed
-    ? parsed.context.tools?.filter(t => toolAllowedByChoice(t, allowed, parsed.context.tools)) ?? []
+  const tools = isAllowedToolChoice(parsed.options.toolChoice)
+    ? parsed.context.tools?.filter(toolChoiceToolPredicate(parsed.options.toolChoice, parsed.context.tools)) ?? []
     : parsed.context.tools ?? [];
   const functionDeclarations = tools.map(t => ({
     name: namespacedToolName(t.namespace, t.name),
@@ -1077,7 +1074,9 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         const replaySession = provider.googleMode === "cloud-code-assist" ? antigravitySession : vertexReplaySession;
         if ((provider.googleMode === "cloud-code-assist" || provider.googleMode === "vertex")
           && parts && replayModel && replaySession) {
-          pendingStreamThoughtSig = observeAntigravityReplay(
+          // Observation may scan the whole frame, so use it only for replay-cache side effects.
+          // The source-order loop below exclusively owns stream carry and cannot pair backwards.
+          observeAntigravityReplay(
             replayModel,
             replaySession,
             parts as unknown[],

package/src/adapters/kiro.ts

@@ -318,9 +318,6 @@ function validateKiroCapabilities(parsed: OcxParsedRequest): void {
   if (choice !== undefined && choice !== "auto" && choice !== "none") {
     throw new Error("Kiro supports only automatic tool choice or tool_choice:none");
   }
-  if (parsed.options.parallelToolCalls === true) {
-    throw new Error("Kiro does not support parallel tool calls");
-  }
   if (parsed.options.serviceTier !== undefined) {
     throw new Error("Kiro does not support service tiers");
   }

package/src/adapters/openai-responses.ts

@@ -1684,6 +1684,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
 
       const forward = provider.authMode === "forward";
       let convertedRoutedCustomToolNames: Set<string> | undefined;
+      let routedCustomToolRepairNames: Set<string> | undefined;
       let convertedRoutedToolSearchNames: Set<string> | undefined;
       let convertedRoutedNamespaceToolAliases: Map<string, { namespace: string; name: string }> | undefined;
       const unexpandedMiss = !!parsed.previousResponseId && parsed._previousResponseInputExpanded !== true;
@@ -1741,6 +1742,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         );
         outBody = rewritten.body;
         convertedRoutedCustomToolNames = rewritten.names;
+        routedCustomToolRepairNames = rewritten.repairNames;
       }
       if (!isCanonicalOpenAiForwardProvider(provider)) {
         // Run after custom-tool lowering so the search compatibility layer can choose a
@@ -1811,6 +1813,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         body,
         releaseBodyObservation,
         ...(convertedRoutedCustomToolNames ? { convertedRoutedCustomToolNames } : {}),
+        ...(routedCustomToolRepairNames ? { routedCustomToolRepairNames } : {}),
         ...(convertedRoutedToolSearchNames ? { convertedRoutedToolSearchNames } : {}),
         ...(convertedRoutedNamespaceToolAliases ? { convertedRoutedNamespaceToolAliases } : {}),
         ...(tierLog ? { tierLog } : {}),

package/src/adapters/tool-catalog-nudge.ts

@@ -120,7 +120,7 @@ export function buildNonOpenAIToolCatalogNudgeFromNames(
     "Call only listed names with their listed argument keys; do not invent, translate, or rename tools.",
     "Names mentioned only in instructions, tool descriptions, argument descriptions, or nested helper APIs are not additional top-level tools.",
     verifiedCodeModeExecName
-      ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.<name>(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.<name>`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names."
+      ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.<name>(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.<name>`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names. Nested `tools.apply_patch(input)` is host-executed: the string must begin exactly with `*** Begin Patch` and end with `*** End Patch` (no trailing `***` on those lines). OpenCodex does not rewrite JavaScript inside exec, so a decorated `*** Begin Patch ***` envelope is rejected by Codex before the file is touched."
       : "If a listed tool exposes nested helpers such as a tools.* API, call the listed parent tool and use those helpers only inside that tool's input.",
     unavailableNeighborNames.length > 0
       ? "Do not use neighboring-agent tool names " + quoteNames(unavailableNeighborNames) + " unless this turn's catalog lists those exact names."

package/src/adapters/xai-web-search.ts

@@ -60,10 +60,15 @@ function normalizeToolGroup(tools: unknown[]): ToolGroupRewrite {
       : undefined;
     const enableImageSearch = searchContentTypes?.includes("image") === true;
     const next: Record<string, unknown> = { ...tool, type: CODEX_WEB_SEARCH_TOOL };
+    // Only the two fields xAI actually refuses are removed. Probed 2026-08-22, one field per
+    // request, against BOTH xAI destinations (api.x.ai and cli-chat-proxy.grok.com): they behave
+    // identically — `external_web_access` 400s on every value including `true`, and
+    // `search_context_size` 400s, while `user_location`, `search_content_types`, `filters` and
+    // `enable_image_search` are all accepted. Deleting the accepted ones was a silent capability
+    // loss, and it contradicted the sibling layer, whose own probe note already records
+    // user_location/filters as accepted (tests/responses-routed-web-search-fields.test.ts).
     delete next.external_web_access;
     delete next.search_context_size;
-    delete next.search_content_types;
-    delete next.user_location;
     if (enableImageSearch && !Object.hasOwn(next, "enable_image_search")) {
       next.enable_image_search = true;
     }

package/src/bridge.ts

@@ -8,6 +8,7 @@ import type {
 } from "./types";
 import { coerceIntegerToolArguments } from "./lib/tool-argument-integers";
 import { adapterFailureFromMessage, classifyError, CYBER_POLICY_ERROR_CODE, isCyberPolicyCode, type OcxErrorPayload } from "./lib/errors";
+import { repairFreeformToolInput } from "./responses/apply-patch-envelope";
 import { encodeCompactionSummary } from "./responses/compaction";
 import { isTruncatedStopReason, truncationReasonFor } from "./responses/truncated-stop-reason";
 import { encodeReasoningEnvelope, type ReasoningEnvelope } from "./responses/reasoning-envelope";
@@ -230,12 +231,12 @@ export function bridgeToResponsesSSE(
   const replayCacheScope = options?.replayCacheScope;
   const setBeatInterval = options?.timers?.setInterval ?? ((handler: () => void, ms: number) => setInterval(handler, ms));
   const clearBeatInterval = options?.timers?.clearInterval ?? ((id: unknown) => clearInterval(id as ReturnType<typeof setInterval>));
-  // Freeform/custom tools (apply_patch) carry their body in `input`; the model is given a
-  // function with `{input:string}`, so unwrap it here when relaying back as a custom_tool_call.
-  const freeformInput = (args: string): string => {
-    try { const o = JSON.parse(args); if (o && typeof o.input === "string") return o.input; } catch { /* raw */ }
-    return args;
-  };
+  // Freeform/custom tools (apply_patch, code-mode exec) carry their body in `input`; the
+  // model is given a function with `{input:string}`, so unwrap it here when relaying back
+  // as a custom_tool_call. Decorated apply_patch envelopes are repaired at this boundary.
+  const freeformInput = (args: string, toolName: string, namespace?: string): string => (
+    repairFreeformToolInput(args, toolName, namespace)
+  );
   // Best-effort unwrap of a PARTIAL freeform arg buffer for live input streaming
   // (`response.custom_tool_call_input.delta` — codex-rs uses it for UI preview only;
   // the completed custom_tool_call item stays authoritative). Compact `{"input":"...`
@@ -626,6 +627,7 @@ export function bridgeToResponsesSSE(
         const argsStr = coerceIntegerToolArguments(
           currentToolCall.args || "{}",
           options?.toolParameterSchemas?.get(currentToolCall.name),
+          currentToolCall.namespace === undefined ? currentToolCall.name : undefined,
         );
         // Finalize streamed function-call arguments so Codex commits the call (incl. MCP / computer_use).
         if (!currentToolCall.freeform && !currentToolCall.toolSearch) {
@@ -636,7 +638,8 @@ export function bridgeToResponsesSSE(
         if (currentToolCall.freeform) {
           emit("response.custom_tool_call_input.done", {
             item_id: currentToolCall.itemId, output_index: currentToolCall.outputIndex,
-            input: freeformInput(currentToolCall.args),
+            ...(currentToolCall.namespace ? { namespace: currentToolCall.namespace } : {}),
+            input: freeformInput(currentToolCall.args, currentToolCall.name, currentToolCall.namespace),
           });
         }
         // Freeform tools serialize as custom_tool_call without extra_content; remember the
@@ -652,7 +655,8 @@ export function bridgeToResponsesSSE(
           ? {
               type: "custom_tool_call", id: currentToolCall.itemId,
               call_id: currentToolCall.callId, name: currentToolCall.name,
-              input: freeformInput(currentToolCall.args), status: "completed",
+              ...(currentToolCall.namespace ? { namespace: currentToolCall.namespace } : {}),
+              input: freeformInput(currentToolCall.args, currentToolCall.name, currentToolCall.namespace), status: "completed",
             }
           : {
               type: "function_call", id: currentToolCall.itemId,
@@ -691,7 +695,8 @@ export function bridgeToResponsesSSE(
           ? {
               type: "custom_tool_call", id: currentToolCall.itemId,
               call_id: currentToolCall.callId, name: currentToolCall.name,
-              input: freeformInput(currentToolCall.args), status: "incomplete",
+              ...(currentToolCall.namespace ? { namespace: currentToolCall.namespace } : {}),
+              input: freeformInput(currentToolCall.args, currentToolCall.name, currentToolCall.namespace), status: "incomplete",
             }
           : {
               type: "function_call", id: currentToolCall.itemId,
@@ -1064,7 +1069,7 @@ export function bridgeToResponsesSSE(
               const item = toolSearch
                 ? { type: "tool_search_call", id: itemId, call_id: event.id, execution: "client", arguments: {}, status: "in_progress" }
                 : freeform
-                ? { type: "custom_tool_call", id: itemId, call_id: event.id, name: realName, input: "", status: "in_progress" }
+                ? { type: "custom_tool_call", id: itemId, call_id: event.id, name: realName, ...(ns ? { namespace: ns } : {}), input: "", status: "in_progress" }
                 : { type: "function_call", id: itemId, call_id: event.id, name: realName, arguments: "", status: "in_progress", ...(ns ? { namespace: ns } : {}) };
               emit("response.output_item.added", { output_index: outputIndex, item });
               currentToolCall = { itemId, outputIndex, callId: event.id, name: realName, args: "", argsBytes: 0, namespace: ns, freeform, toolSearch, providerMetadata: event.providerMetadata };
@@ -1567,10 +1572,9 @@ function buildResponseJSONWithBudget(
   // Web-search citations awaiting the next assistant message (attached as url_citation annotations).
   let pendingWebSources: { url: string; title?: string }[] = [];
 
-  const freeformInput = (args: string): string => {
-    try { const o = JSON.parse(args); if (o && typeof o.input === "string") return o.input; } catch { /* raw */ }
-    return args;
-  };
+  const freeformInput = (args: string, toolName: string, namespace?: string): string => (
+    repairFreeformToolInput(args, toolName, namespace)
+  );
   const parseArgsObj = (args: string): Record<string, unknown> => {
     try { const o = JSON.parse(args); return o && typeof o === "object" ? o : {}; } catch { return {}; }
   };
@@ -1656,6 +1660,7 @@ function buildResponseJSONWithBudget(
     const coercedArgs = coerceIntegerToolArguments(
       currentToolCallArgs,
       options?.toolParameterSchemas?.get(currentToolCallName),
+      ns === undefined ? realName : undefined,
     );
     // Freeform tools serialize as custom_tool_call without extra_content; remember the
     // signature server-side regardless so the replayed call can be re-signed (#1735).
@@ -1670,7 +1675,8 @@ function buildResponseJSONWithBudget(
       pushOutput({
         type: "custom_tool_call", id: `ctc_${uuid()}`,
         call_id: currentToolCallId, name: realName,
-        input: freeformInput(currentToolCallArgs), status,
+        ...(ns ? { namespace: ns } : {}),
+        input: freeformInput(currentToolCallArgs, realName, ns), status,
       });
     } else {
       pushOutput({

package/src/cli/dispatch.ts

@@ -203,7 +203,11 @@ const commandRunners: Record<string, CommandRunner> = {
     return 0;
   },
   sync: async deps => {
-    const restartCodex = deps.args.slice(1).includes("--restart-codex");
+    const syncArgs = deps.args.slice(1);
+    const restartCodex = syncArgs.includes("--restart-codex");
+    // Separate flag on purpose: --restart-codex promises app-server-only scope,
+    // and quitting the desktop app ends live conversations.
+    const restartDesktopApp = syncArgs.includes("--restart-desktop-app");
     const live = await deps.findLiveProxy();
     const synced = await syncModelsToCodex(
       live?.port,
@@ -229,6 +233,7 @@ const commandRunners: Record<string, CommandRunner> = {
     // exactly when a long-lived app-server is holding the stale list.
     if (synced.catalogWritten || synced.cacheSynced) {
       afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
+      if (restartDesktopApp) await handleDesktopAppRestart(console);
     }
     // `ocx sync` is a direct CLI path; it does not call the management
     // `/api/sync` route. Refresh the already-connected MCode block here too,
@@ -259,7 +264,9 @@ const commandRunners: Record<string, CommandRunner> = {
     return await cmdV2(deps.args.slice(1), {}, async () => (await deps.findLiveProxy())?.port);
   },
   "sync-cache": async deps => {
-    const restartCodex = deps.args.slice(1).includes("--restart-codex");
+    const cacheArgs = deps.args.slice(1);
+    const restartCodex = cacheArgs.includes("--restart-codex");
+    const restartDesktopApp = cacheArgs.includes("--restart-desktop-app");
     const { withCatalogWriteSerialization } = await import("../codex/catalog-write-serialization");
     const { invalidateCodexModelsCacheWithPermit } = await import("../codex/catalog/sync");
     const { getCodexHome } = await import("../codex/paths");
@@ -270,6 +277,7 @@ const commandRunners: Record<string, CommandRunner> = {
     // Only warn/restart when models_cache was actually rewritten from a readable catalog.
     if (invalidated.kind === "completed" && invalidated.value) {
       afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
+      if (restartDesktopApp) await handleDesktopAppRestart(console);
     } else if (desiredDisabled) {
       console.log("Codex integration is OFF; cache sync skipped (no catalog or cache write).");
     }
@@ -583,3 +591,43 @@ export async function dispatchCommand(head: CliHead, deps: CliDispatchDeps): Pro
   }
   return await runner(deps);
 }
+
+/**
+ * Report the outcome of an opt-in desktop-app restart. Kept next to the two
+ * callers so `sync` and `sync-cache` cannot drift in what they tell the user.
+ */
+async function handleDesktopAppRestart(log: Pick<Console, "log" | "error">): Promise<void> {
+  const { restartCodexDesktopApp } = await import("../codex/desktop-app-restart");
+  const result = restartCodexDesktopApp();
+  switch (result.reason) {
+    case "windows_only":
+      log.error("--restart-desktop-app is supported on Windows only; nothing was stopped.");
+      return;
+    case "package_discovery_failed":
+      log.error(
+        "Could not identify the installed Codex desktop package. Quit and relaunch the desktop app "
+        + "manually to refresh the model picker.",
+      );
+      return;
+    case "self_ancestry":
+      log.error(
+        "Refusing to restart the desktop app because this command is running inside it. "
+        + "Run 'ocx sync --restart-desktop-app' from an external terminal instead.",
+      );
+      return;
+    case "no_targets":
+      log.log("Codex desktop app is not running; nothing to restart.");
+      return;
+    case "targets_survived":
+      log.error(
+        `Codex desktop app PID(s) ${result.surviving.join(", ")} did not exit, so it was not relaunched. `
+        + "Quit the desktop app manually to refresh the model picker.",
+      );
+      return;
+    default:
+      if (result.relaunch === "started") {
+        log.log("Codex desktop app restarted; its model picker will re-read the catalog.");
+      }
+  }
+}
+

package/src/cli/doctor.ts

@@ -10,7 +10,8 @@
 import { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { getConfigDir, getConfigPath, readConfigDiagnostics, readPid, resolveEnvValue } from "../config";
+import { getConfigDir, getConfigPath, readConfigDiagnostics, resolveEnvValue } from "../config";
+import { readPid } from "../config/process-state";
 import { findLiveProxy, type LiveProxy } from "../server/proxy-liveness";
 import { BUN_RUNTIME_SOURCES } from "../lib/bun-runtime";
 import type { BunRuntimeSource } from "../lib/bun-runtime";
@@ -1072,10 +1073,10 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   console.log(`  ${probe.ok ? "ok " : "-- "} ${WHAM_USAGE_URL}`);
   console.log(`       ${detail}, ${probe.durationMs}ms, ${probe.authenticated ? "authenticated" : "unauthenticated"}`);
 
-  // Design B upgrade visibility: threads still tagged opencodex are invisible to the native
-  // Codex app until the one-time migration lands. Read-only probe (readonly sqlite, 100ms
-  // busy timeout) — reports state, never mutates.
-  console.log("\nCodex history migration");
+  // Design B upgrade visibility: only the backup manifest authorizes restoring provider
+  // metadata. Bare routed rows have unknown provenance and remain unchanged. This read-only
+  // probe reports manifest work and database readability; it never mutates.
+  console.log("\nCodex history metadata restore");
   // The history failure messages point here; make the visit worthwhile by
   // probing the coordinator namespace the locks live in. The probe exercises
   // identity, runtime-root, and permission checks without taking any lock or
@@ -1096,11 +1097,17 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   for (const line of formatCoordinatorDoctorLines(inspectCodexCoordinator())) console.log(line);
   const pending = countPendingOpencodexHistory();
   if (pending.failed) {
-    console.log("  --     state DB locked or unreadable (Codex app open?) — migration state unknown");
+    if (pending.failureReason === "busy") {
+      console.log("  --     history database, backup manifest, or rollout file is busy — exact metadata restore is pending");
+    } else if (pending.failureReason === "permission") {
+      console.log("  --     state DB or backup manifest access was denied — restore state unknown");
+    } else {
+      console.log("  --     backup manifest or restore target failed integrity checks — manual review required");
+    }
   } else if (pending.pendingRows === 0 && pending.backupEntries === 0) {
-    console.log("  ok     no legacy opencodex-tagged threads pending");
+    console.log("  ok     no manifest-backed provider metadata pending; untracked routed history is unchanged");
   } else {
-    console.log(`  --     ${pending.pendingRows} thread(s) still tagged opencodex, ${pending.backupEntries} backup manifest entr${pending.backupEntries === 1 ? "y" : "ies"}`);
+    console.log(`  --     ${pending.backupEntries} backup manifest entr${pending.backupEntries === 1 ? "y" : "ies"} pending exact metadata restore`);
   }
 
   console.log("\nProject Codex configs");
@@ -1148,7 +1155,7 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   const { collectCodexAppServerCatalogState } = await import("../codex/app-server-processes");
   const catalogState = collectCodexAppServerCatalogState();
   if (catalogState.state === "stale") {
-    console.log(`  [WARN] Codex app-server (PID(s): ${catalogState.processes.map(p => p.pid).join(", ")}) started before the on-disk catalog changed; its in-memory model list disagrees with ocx. Action: restart Codex (or run \`ocx sync --restart-codex\`)`);
+    console.log(`  [WARN] Codex app-server (PID(s): ${catalogState.processes.map(p => p.pid).join(", ")}) started before the on-disk catalog changed; its in-memory model list disagrees with ocx. Action: restart Codex (or run \`ocx sync --restart-codex\`; on Windows the desktop app may need \`ocx sync --restart-desktop-app\`)`);
   } else if (catalogState.state === "unknown") {
     console.log("  [WARN] Could not verify whether the running Codex app-server's model catalog is current (start time or catalog unreadable). Action: if the model list looks stale, restart Codex");
   } else if (catalogState.state === "fresh") {
@@ -1185,8 +1192,14 @@ export async function runDoctor(args: string[] = []): Promise<void> {
       }
     }
   }
-  if (pending.failed || pending.pendingRows > 0 || pending.backupEntries > 0) {
-    hints.push("Legacy chat threads are still tagged opencodex (or the DB was locked). The running proxy retries the migration automatically; to force it now, close the Codex app and run 'ocx sync'.");
+  if (pending.failed && pending.failureReason === "busy") {
+    hints.push("Backed-up history metadata is pending or its state is unreadable. The running proxy retries exact restoration automatically; to force it now, close the Codex app and run 'ocx sync'. Untracked routed history is not relabeled.");
+  } else if (pending.failed && pending.failureReason === "permission") {
+    hints.push("Backed-up history metadata could not be inspected because access was denied. Fix access to the reported Codex history paths, then run 'ocx sync'; repeated retries do not repair permissions.");
+  } else if (pending.failed) {
+    hints.push("The history manifest or its target is invalid or changed. Preserve both, inspect the manifest/database/rollout identity, and do not repeatedly run 'ocx sync' until the mismatch is understood. Untracked routed history is not relabeled.");
+  } else if (pending.backupEntries > 0) {
+    hints.push("Backed-up history metadata is pending. The running proxy retries exact restoration automatically; to force it now, close the Codex app and run 'ocx sync'. Untracked routed history is not relabeled.");
   }
   if (dual.dualInstall && !dual.effectiveIsWindowsMount) {
     hints.push(`Codex is installed on BOTH WSL and Windows. Each side keeps its own ~/.codex (logins, config, catalog are separate); ocx here manages the Linux one. To share a single home, set CODEX_HOME=${dual.windowsCodexHomes[0] ?? `${dual.automountRoot}/c/Users/<you>/.codex`} in WSL (drvfs file locking is less reliable).`);

package/src/cli/help.ts

@@ -24,8 +24,8 @@ Usage:
   ocx stop                    Stop the proxy AND restore native Codex (plain codex works again)
   ocx restore                 Restore native Codex without stopping (alias: eject)
   ocx restore back            Re-point codex at the running proxy (undo restore)
-  ocx recover-history --legacy-openai
-                               Explicitly recover pre-backup syncResumeHistory rows
+  ocx recover-history --legacy-openai --yes
+                               Force all user-message opencodex rows to OpenAI (legacy recovery)
   ocx uninstall               Remove service/shim/config and restore native Codex (alias: remove)
   ocx service [sub]           Run as a background service (default: install/update/start)
   ocx codex-shim <sub>        Auto-start proxy when \`codex\` launches (install|status|uninstall|remove)
@@ -57,7 +57,8 @@ Usage:
   ocx observe <sub>           Logs, usage, storage, memory, and debug data
   ocx route <sub>             Routing features (combo, policy)
   ocx logs [filters]          Alias of ocx observe logs
-  ocx usage [--range <7d|30d|all>]  Alias of ocx observe usage
+  ocx usage [--range <today|1d|7d|30d|all>] [--provider <name>] [--model <id>]
+                              Token and estimated-cost report (alias of ocx observe usage)
   ocx storage [--json]        Alias of ocx observe storage
   ocx memory [--json]         Alias of ocx observe memory
   ocx api-key <sub>           Alias of ocx access key

package/src/cli/index.ts

@@ -12,6 +12,9 @@ import {
   codexAutoStartEnabled,
   getConfigDir,
   loadConfig,
+  saveConfig,
+} from "../config";
+import {
   readPid,
   readPidFileValue,
   readRuntimePort,
@@ -19,10 +22,9 @@ import {
   removePidIfValueIs,
   removeRuntimePort,
   removeRuntimePortIfPidIs,
-  saveConfig,
   writePid,
   writeRuntimePort,
-} from "../config";
+} from "../config/process-state";
 import { collectStatus } from "./status";
 
 import {
@@ -906,8 +908,13 @@ async function handleStatus() {
 
 async function handleRecoverHistory() {
   if (args[1] !== "--legacy-openai") {
-    console.error("Usage: ocx recover-history --legacy-openai");
-    console.error("Only use this if an older syncResumeHistory build already remapped OpenAI Codex App history to opencodex before backup support existed.");
+    console.error("Usage: ocx recover-history --legacy-openai --yes");
+    console.error("This force-relabels every user-message opencodex row to OpenAI, including legitimate dedicated-provider history. Back up first and use it only for pre-backup legacy recovery.");
+    process.exit(1);
+  }
+  console.error("WARNING: this force-relabels every user-message opencodex row to OpenAI, normalizes exec to cli, and includes legitimate dedicated-provider history.");
+  if (args.length !== 3 || args[2] !== "--yes") {
+    console.error("Re-run with explicit confirmation: ocx recover-history --legacy-openai --yes");
     process.exit(1);
   }
   // Manifest-independent legacy ejection, serialized like every other history

package/src/cli/models.ts

@@ -5,7 +5,12 @@ import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline/promises";
 import { syncModelsToCodex } from "../codex/sync";
 import { hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
-import { canonicalizeReasoningEfforts, isDeclaredReasoningEffort, modelRecordValue } from "../reasoning-effort";
+import {
+  canonicalizeReasoningEfforts,
+  configuredReasoningEfforts,
+  isDeclaredReasoningEffort,
+  modelRecordValue,
+} from "../reasoning-effort";
 import { encodedModelIdCollides, routedSlug, slugEquals } from "../providers/slug-codec";
 import { knownModelIdsForProvider } from "../router";
 import { findLiveProxy } from "../server/proxy-liveness";
@@ -91,7 +96,6 @@ function collectModels(config: OcxConfig, providerFilter?: string): ModelEntry[]
     const seen = new Set<string>();
     const contextWindows = prov.modelContextWindows ?? {};
     const inputModalities = prov.modelInputModalities ?? {};
-    const reasoningEfforts = prov.modelReasoningEfforts ?? {};
     const globalContext = prov.contextWindow ?? null;
 
     const addModel = (model: string, isDefault: boolean) => {
@@ -107,7 +111,13 @@ function collectModels(config: OcxConfig, providerFilter?: string): ModelEntry[]
       // an exact `gpt-oss:120b` entry that lists "image", and the proxy rejects the image.
       const noVision = modelInList(prov.noVisionModels, model);
       const modalities = noVision ? ["text"] : (modelRecordValue(inputModalities, model) ?? null);
-      const efforts = modelRecordValue(reasoningEfforts, model) ?? prov.reasoningEfforts ?? null;
+      // Same reason, for the ladder: `configuredReasoningEfforts` is what the catalog
+      // (`provider-fetch`) and the effort cap (`effort-policy`) resolve through, and it
+      // does three things this expression did not — it returns [] for a noReasoningModels
+      // match, drops levels Codex does not declare, and re-adds tiers the wire map proves
+      // the model emits. Restating two of its five lines here reported a ladder the proxy
+      // strips, and unsanitized junk as a supported level.
+      const efforts = configuredReasoningEfforts(prov, model) ?? null;
 
       entries.push({
         provider: provName,

package/src/cli/observe.ts

@@ -10,6 +10,8 @@ import {
   takeOption,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import { formatUsageReport } from "./usage-report";
+import { USAGE_RANGES, USAGE_SURFACES } from "../usage/summary";
 
 const USAGE = `Usage:
   ocx observe logs [--provider <name>] [--model <id>] [--status <code>]
@@ -17,7 +19,8 @@ const USAGE = `Usage:
   ocx logs explain <request-id> [--json]
   ocx logs rebuild-index
   ocx logs index-status
-  ocx observe usage [--range <7d|30d|all>] [--surface <all|codex|claude|grok>] [--json]
+  ocx observe usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>]
+      [--provider <name>] [--model <id>] [--json]
   ocx observe storage [codex-logs [status|protect|unprotect|repair|compact] [--mode <compat|quiet>]] [--json]
   ocx observe memory [--json]
   ocx observe debug [--json]
@@ -131,11 +134,23 @@ async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const wantsJson = takeFlag(args, "--json");
   const range = takeOption(args, "--range") ?? "30d";
   const surface = takeOption(args, "--surface") ?? "all";
-  if (!["7d", "30d", "all"].includes(range)) throw new CliUsageError("--range must be 7d, 30d, or all", USAGE);
-  if (!["all", "codex", "claude", "grok"].includes(surface)) throw new CliUsageError("--surface must be all, codex, claude, or grok", USAGE);
+  const provider = takeOption(args, "--provider");
+  const model = takeOption(args, "--model");
+  // `1d` is accepted here as well as server-side so the CLI does not reject an
+  // alias the API would have understood.
+  const ranges = [...USAGE_RANGES, "1d"];
+  if (!ranges.includes(range)) throw new CliUsageError(`--range must be one of ${USAGE_RANGES.join(", ")} (1d aliases today)`, USAGE);
+  if (!USAGE_SURFACES.includes(surface as (typeof USAGE_SURFACES)[number])) {
+    throw new CliUsageError(`--surface must be one of ${USAGE_SURFACES.join(", ")}`, USAGE);
+  }
   rejectArgs(args, USAGE);
-  const result = await runtimeRequest(`/api/usage${query({ range, surface })}`, {}, deps);
-  printData(result, wantsJson, summaryLines(result));
+  const result = await runtimeRequest(`/api/usage${query({ range, surface, provider, model })}`, {}, deps);
+  // Built only when it will be printed: JavaScript evaluates arguments before
+  // the call, so passing formatUsageReport(...) inline would run the human
+  // renderer during --json and let its assumptions affect a path that is meant
+  // to bypass it entirely.
+  if (wantsJson) printData(result, true);
+  else printData(result, false, formatUsageReport(result as Parameters<typeof formatUsageReport>[0]));
 }
 
 async function simple(path: string, argv: string[], deps: RuntimeApiDeps): Promise<void> {

package/src/cli/provider.ts

@@ -8,7 +8,8 @@
  *   show <name>   Show provider config details (secrets masked)
  *   set-default <name>  Change the default provider
  */
-import { apiKeyTransportConfigError, hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
+import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
+import { apiKeyTransportConfigError } from "../config/provider-validation";
 import { hasHelpFlag } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
 import { providerConfigSeed } from "../providers/derive";

package/src/cli/registry.ts

@@ -36,8 +36,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "recover-history",
-    usage: "ocx recover-history --legacy-openai",
-    summary: "Explicitly recover pre-backup syncResumeHistory rows.",
+    usage: "ocx recover-history --legacy-openai --yes",
+    summary: "Force all user-message opencodex rows to OpenAI for legacy recovery.",
   },
   {
     name: "uninstall",
@@ -88,20 +88,22 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   { name: "ensure", usage: "ocx ensure", summary: "Ensure the proxy is running and Codex config/cache are current." },
   {
     name: "sync",
-    usage: "ocx sync [--restart-codex]",
+    usage: "ocx sync [--restart-codex] [--restart-desktop-app]",
     summary: "Fetch provider models and inject them into Codex config.",
     details: [
       "After writing the catalog, warns if long-lived Codex app-server processes are still running.",
       "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+      "--restart-desktop-app (Windows only, opt-in) fully restarts the Codex desktop app so its model picker re-reads the catalog. Never implied by --restart-codex: it ends live conversations.",
     ],
   },
   {
     name: "sync-cache",
-    usage: "ocx sync-cache [--restart-codex]",
+    usage: "ocx sync-cache [--restart-codex] [--restart-desktop-app]",
     summary: "Refresh Codex's model cache from the active catalog.",
     details: [
       "Warns when Codex app-server processes still hold an in-memory model list.",
       "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+      "--restart-desktop-app (Windows only, opt-in) fully restarts the Codex desktop app so its model picker re-reads the catalog. Never implied by --restart-codex: it ends live conversations.",
     ],
   },
   { name: "status", usage: "ocx status", summary: "Check proxy server status." },
@@ -209,7 +211,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   { name: "logs", usage: "ocx logs [filters] [--follow] [--json|--jsonl]", summary: "Alias of ocx observe logs." },
   {
     name: "usage",
-    usage: "ocx usage [--range <7d|30d|all>] [--surface <all|codex|claude|grok>] [--json]",
+    usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--json]",
     summary: "Alias of ocx observe usage.",
   },
   { name: "storage", usage: "ocx storage [--json]", summary: "Alias of ocx observe storage." },

package/src/cli/status.ts

@@ -1,5 +1,6 @@
 import { durableBunRuntime } from "../lib/bun-runtime";
-import { codexAutoStartEnabled, getConfigPath, getPidPath, readConfigDiagnostics, readPid, readRuntimePort, type RuntimePortState } from "../config";
+import { codexAutoStartEnabled, getConfigPath, readConfigDiagnostics } from "../config";
+import { getPidPath, readPid, readRuntimePort, type RuntimePortState } from "../config/process-state";
 import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../codex/plugins-doctor";
 import { findLiveProxy, isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";

package/src/cli/system-restart-client.ts

@@ -1,4 +1,4 @@
-import { readRuntimePort } from "../config";
+import { readRuntimePort } from "../config/process-state";
 import {
   LOCAL_ATTESTATION_CHALLENGE_HEADER,
   LOCAL_ATTESTATION_PROOF_HEADER,