@bitkyc08/opencodex 2.20.0 → 2.22.0

package/src/adapters/openai-chat.ts

@@ -14,6 +14,7 @@ import { buildNonOpenAIToolCatalogNudgeForTools, shouldInjectNonOpenAIToolCatalo
 import { openRouterProviderPayload, resolveOpenRouterRouting } from "../providers/openrouter-routing";
 import { canSerializeServiceTierForChatModel } from "../providers/service-tier";
 import { openaiChatCompletionsUrl } from "./openai-chat-url";
+import { stripResponsesOnlyEncryptedMarker } from "./responses-tool-schema";
 import {
   isTranslatorBudgetExceededError,
   retainTranslatedEventBatch,
@@ -332,6 +333,16 @@ type InvalidToolCallReason =
   | "tool_call_function_name_blank"
   | "tool_call_function_arguments_invalid";
 
+/**
+ * Streamed string fields are absent when null or undefined (#1731): OpenAI-compatible
+ * streamers repeat already-sent `id`/`name`/`arguments` as null on continuation deltas.
+ * The accumulator and this diagnostic share this predicate so they cannot disagree about
+ * which delta was the invalid one.
+ */
+function isInvalidStreamStringField(value: unknown): boolean {
+  return value != null && typeof value !== "string";
+}
+
 /**
  * Explain only the rejected wire shape, never its values. This diagnostic exists so provider
  * compatibility can be tightened from evidence without retaining tool arguments or credentials.
@@ -358,6 +369,10 @@ function diagnoseInvalidToolCalls(
       // Blank names are caught later at flush, not here, so they are not diagnosed on this
       // branch. Describe exactly that boundary rather than tightening compatibility in a
       // diagnostic change.
+      // #1731: "present" means the same thing here as in the accumulator — null and undefined
+      // are both absent, because some OpenAI-compatible streamers repeat already-sent fields
+      // as null on continuation deltas. A separate predicate here would diagnose accepted
+      // padding as the failure and point compatibility work at the wrong delta.
       const streamFunction = (rawToolCall as { function?: unknown }).function;
       if (streamFunction !== undefined && streamFunction !== null) {
         if (!isRecord(streamFunction)) {
@@ -367,14 +382,14 @@ function diagnoseInvalidToolCalls(
             valueType: Array.isArray(streamFunction) ? "array" : typeof streamFunction,
           };
         }
-        if (streamFunction.name !== undefined && typeof streamFunction.name !== "string") {
+        if (isInvalidStreamStringField(streamFunction.name)) {
           return { reason: "tool_call_function_name_invalid", callIndex, valueType: typeof streamFunction.name };
         }
-        if (streamFunction.arguments !== undefined && typeof streamFunction.arguments !== "string") {
+        if (isInvalidStreamStringField(streamFunction.arguments)) {
           return { reason: "tool_call_function_arguments_invalid", callIndex, valueType: typeof streamFunction.arguments };
         }
       }
-      if (rawToolCall.id !== undefined && typeof rawToolCall.id !== "string") {
+      if (isInvalidStreamStringField(rawToolCall.id)) {
         return { reason: "tool_call_id_invalid", callIndex, valueType: typeof rawToolCall.id };
       }
       continue;
@@ -1077,9 +1092,9 @@ function toolsToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig
   if (tools.length === 0) return undefined;
   const xaiTarget = isXaiSchemaTarget(provider);
   const formatted = tools.flatMap(t => {
-    const parameters = xaiTarget
+    const parameters = stripResponsesOnlyEncryptedMarker(xaiTarget
       ? normalizeXaiToolParameters(t.parameters)
-      : ensureRootObjectType(t.parameters);
+      : ensureRootObjectType(t.parameters));
 
     if (parameters === undefined) return [];
     return [{
@@ -1488,13 +1503,15 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
                 }
                 const rawName = rawFunction.name;
                 const rawArguments = rawFunction.arguments;
-                if ((rawName !== undefined && typeof rawName !== "string")
-                  || (rawArguments !== undefined && typeof rawArguments !== "string")) {
+                // Some OpenAI-compatible streamers repeat already-sent fields as null on
+                // continuation deltas. Treat only null/undefined as absent; every other
+                // non-string value still fails closed before entering the accumulator.
+                if (isInvalidStreamStringField(rawName) || isInvalidStreamStringField(rawArguments)) {
                   logInvalidToolCalls("stream", rawToolCalls);
                   return yield* terminateWithError(invalidToolCallsEvent(pendingUsage));
                 }
               }
-              if (tc.id !== undefined && typeof tc.id !== "string") {
+              if (isInvalidStreamStringField(tc.id)) {
                 logInvalidToolCalls("stream", rawToolCalls);
                 return yield* terminateWithError(invalidToolCallsEvent(pendingUsage));
               }

package/src/adapters/responses-tool-schema.ts

@@ -0,0 +1,67 @@
+// Codex multi-agent v2 stamps a Responses-only `encrypted: true` marker on
+// collaboration tool schemas (openai/codex 5f4d06ef; issue #85). It is an
+// annotation for the ChatGPT backend only, so translated provider schemas must
+// drop it without removing properties or definitions literally named `encrypted`.
+const ENCRYPTED_MARKER_NAME_BAG_KEYS = new Set([
+  "properties",
+  "patternProperties",
+  "$defs",
+  "definitions",
+  "dependencies",
+  "dependentSchemas",
+  "dependentRequired",
+]);
+const ENCRYPTED_MARKER_LITERAL_VALUE_KEYS = new Set(["const", "default", "enum", "examples"]);
+
+/**
+ * The schema is caller-supplied, so its nesting depth is attacker-influenced. Native recursion
+ * would turn a deep schema into a stack overflow that takes down the request path, so this walks
+ * an explicit stack instead: depth costs heap, which is bounded and recoverable.
+ */
+export function stripResponsesOnlyEncryptedMarker(node: unknown, inNameBag = false): unknown {
+  type Assign = (value: unknown) => void;
+  interface Frame { node: unknown; inNameBag: boolean; assign: Assign }
+
+  let result: unknown;
+  const stack: Frame[] = [{ node, inNameBag, assign: value => { result = value; } }];
+
+  while (stack.length > 0) {
+    const frame = stack.pop()!;
+    const current = frame.node;
+
+    if (Array.isArray(current)) {
+      const out: unknown[] = new Array(current.length);
+      frame.assign(out);
+      // Array items are schemas in their own right, never a name bag.
+      for (let i = current.length - 1; i >= 0; i--) {
+        stack.push({ node: current[i], inNameBag: false, assign: value => { out[i] = value; } });
+      }
+      continue;
+    }
+    if (!current || typeof current !== "object") {
+      frame.assign(current);
+      continue;
+    }
+
+    // A schema name may be `__proto__`; a null-prototype record keeps it as data.
+    const out: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    frame.assign(out);
+
+    for (const [key, value] of Object.entries(current as Record<string, unknown>)) {
+      if (frame.inNameBag) {
+        // Inside a name bag every key is a caller-chosen name, so `encrypted` here is data.
+        stack.push({ node: value, inNameBag: false, assign: v => { out[key] = v; } });
+      } else if (key !== "encrypted") {
+        if (ENCRYPTED_MARKER_LITERAL_VALUE_KEYS.has(key)) {
+          // Literal payloads are values, not schemas: an `encrypted` key inside them is data.
+          out[key] = value;
+        } else {
+          const childInNameBag = ENCRYPTED_MARKER_NAME_BAG_KEYS.has(key);
+          stack.push({ node: value, inNameBag: childInNameBag, assign: v => { out[key] = v; } });
+        }
+      }
+    }
+  }
+
+  return result;
+}

package/src/bridge.ts

@@ -2,6 +2,7 @@ import type {
   AdapterEvent,
   OcxMessagePhase,
   OcxProviderContinuationState,
+  OcxProviderOpaqueToolCallMetadata,
   OcxReasoningReplayScopeRef,
   OcxUsage,
 } from "./types";
@@ -10,6 +11,7 @@ import { adapterFailureFromMessage, classifyError, CYBER_POLICY_ERROR_CODE, isCy
 import { encodeCompactionSummary } from "./responses/compaction";
 import { encodeReasoningEnvelope, type ReasoningEnvelope } from "./responses/reasoning-envelope";
 import { rememberReasoningForCall } from "./responses/reasoning-replay-cache";
+import { responsesExtraContentFromProviderMetadata } from "./responses/provider-opaque-metadata";
 import { resolveStallTimeoutSec } from "./stall-timeout";
 import { usageDisplayTotalTokens } from "./usage/totals";
 import {
@@ -496,7 +498,7 @@ export function bridgeToResponsesSSE(
       // synthetic compaction item's payload on done.
       let compactionText = "";
       let compactionTextBytes = 0;
-      let currentToolCall: { itemId: string; outputIndex: number; callId: string; name: string; args: string; argsBytes: number; namespace?: string; freeform?: boolean; toolSearch?: boolean; inputEmitted?: string } | null = null;
+      let currentToolCall: { itemId: string; outputIndex: number; callId: string; name: string; args: string; argsBytes: number; namespace?: string; freeform?: boolean; toolSearch?: boolean; inputEmitted?: string; providerMetadata?: OcxProviderOpaqueToolCallMetadata } | null = null;
       // Open native web-search cell (between begin and end). Holds the output index allocated on
       // begin so the matching done reuses it; closed as `failed` if the stream terminates early.
       let currentWebSearch: { itemId: string; eventId: string; outputIndex: number } | null = null;
@@ -621,6 +623,9 @@ export function bridgeToResponsesSSE(
               call_id: currentToolCall.callId, name: currentToolCall.name,
               arguments: argsStr, status: "completed",
               ...(currentToolCall.namespace ? { namespace: currentToolCall.namespace } : {}),
+              // Provider-opaque metadata (issue #1735) rides the item so a client that replays
+              // this history can hand the signature back on the part it belongs to.
+              ...(responsesExtraContentFromProviderMetadata(currentToolCall.providerMetadata) ?? {}),
             };
         emit("response.output_item.done", { output_index: currentToolCall.outputIndex, item });
         retainFinishedItem(item as OutputItem);
@@ -655,6 +660,10 @@ export function bridgeToResponsesSSE(
               call_id: currentToolCall.callId, name: currentToolCall.name,
               arguments: argsStr, status: "incomplete",
               ...(currentToolCall.namespace ? { namespace: currentToolCall.namespace } : {}),
+              // An incomplete call can still be persisted and replayed (max_output_tokens), so it
+              // carries the same metadata as the completed item — otherwise SSE and buffered JSON
+              // would disagree about whether the signature survives.
+              ...(responsesExtraContentFromProviderMetadata(currentToolCall.providerMetadata) ?? {}),
             };
         emit("response.output_item.done", { output_index: currentToolCall.outputIndex, item });
         retainFinishedItem(item as OutputItem);
@@ -1013,7 +1022,7 @@ export function bridgeToResponsesSSE(
                 ? { type: "custom_tool_call", id: itemId, call_id: event.id, name: realName, 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 };
+              currentToolCall = { itemId, outputIndex, callId: event.id, name: realName, args: "", argsBytes: 0, namespace: ns, freeform, toolSearch, providerMetadata: event.providerMetadata };
               budget?.openCall(event.id);
               break;
             }
@@ -1476,6 +1485,7 @@ function buildResponseJSONWithBudget(
   let currentToolCallId = "";
   let currentToolCallName = "";
   let currentToolCallArgs = "";
+  let currentToolCallProviderMetadata: OcxProviderOpaqueToolCallMetadata | undefined;
   let currentToolCallArgsBytes = 0;
   // Web-search citations awaiting the next assistant message (attached as url_citation annotations).
   let pendingWebSources: { url: string; title?: string }[] = [];
@@ -1584,11 +1594,13 @@ function buildResponseJSONWithBudget(
         call_id: currentToolCallId, name: realName,
         arguments: coercedArgs || "{}", status,
         ...(ns ? { namespace: ns } : {}),
+        ...(responsesExtraContentFromProviderMetadata(currentToolCallProviderMetadata) ?? {}),
       });
     }
     budget?.closeCall(currentToolCallId);
     currentToolCallId = "";
     currentToolCallName = "";
+    currentToolCallProviderMetadata = undefined;
     currentToolCallArgs = "";
     currentToolCallArgsBytes = 0;
   };
@@ -1703,6 +1715,7 @@ function buildResponseJSONWithBudget(
         currentToolCallName = e.name;
         currentToolCallArgs = "";
         currentToolCallArgsBytes = 0;
+        currentToolCallProviderMetadata = e.providerMetadata;
         break;
       case "tool_call_delta":
         {

package/src/claude/agents-inject.ts

@@ -20,7 +20,7 @@ import { claudeConfigDir } from "./gateway-cache";
 import { DEFAULT_SUBAGENT_MODELS, hasOwnProvider } from "../config";
 import { effectiveBlockedSkillNames, resolveInboundModel } from "./inbound";
 import { knownModelIdsForProvider } from "../router";
-import { decodeRoutedModelId } from "../providers/slug-codec";
+import { decodeRoutedModelIdOrThrow } from "../providers/slug-codec";
 
 export interface ClaudeAgentDef {
   file: string;
@@ -85,7 +85,7 @@ function entryParts(entry: string, config: OcxConfig): { alias: string; id: stri
     const provider = entry.slice(0, slash);
     const prov = hasOwnProvider(config.providers, provider) ? config.providers[provider] : undefined;
     const id = prov
-      ? decodeRoutedModelId(entry.slice(slash + 1), knownModelIdsForProvider(provider, prov))
+      ? decodeRoutedModelIdOrThrow(entry.slice(slash + 1), knownModelIdsForProvider(provider, prov, config))
       : entry.slice(slash + 1);
     return { alias: claudeCodeAlias(provider, id), id, provider };
   }

package/src/claude/gateway-cache.ts

@@ -13,12 +13,21 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { loadServiceTokenFromFile, serviceApiTokenFilePath } from "../lib/service-secrets";
+import type { OcxConfig } from "../types";
 
 export interface GatewayModelRow {
   id: string;
   display_name?: string;
 }
 
+export interface GatewayModelCacheRefreshOptions {
+  timeoutMs?: number;
+  configDir?: string;
+  admissionConfig?: Pick<OcxConfig, "apiKeys">;
+  env?: NodeJS.ProcessEnv;
+}
+
 /** Claude Code config dir (CLAUDE_CONFIG_DIR override honored, like the CLI). */
 export function claudeConfigDir(): string {
   const custom = process.env.CLAUDE_CONFIG_DIR;
@@ -45,14 +54,42 @@ export function writeGatewayModelCache(baseUrl: string, models: readonly Gateway
   }
 }
 
+/**
+ * Hardened service-token file, the same precedence `ocx opencode` uses. A service
+ * install writes the admission token to disk rather than the interactive environment,
+ * so an interactive `ocx claude` with neither env token nor configured key would
+ * otherwise still get a 401 and keep a stale picker list.
+ */
+function serviceFileToken(env: NodeJS.ProcessEnv): string | null {
+  const lookup = env.OCX_API_TOKEN_FILE?.trim()
+    ? env
+    : { ...env, OCX_API_TOKEN_FILE: serviceApiTokenFilePath() };
+  return loadServiceTokenFromFile(lookup as Record<string, string | undefined>);
+}
+
 /** Fetch the anthropic-flavor /v1/models from the local proxy and write the cache. */
-export async function refreshGatewayModelCacheFromProxy(port: number, timeoutMs = 3_000, configDir?: string): Promise<string | null> {
+export async function refreshGatewayModelCacheFromProxy(
+  port: number,
+  options: GatewayModelCacheRefreshOptions = {},
+): Promise<string | null> {
   try {
+    const headers = new Headers({ "anthropic-version": "2023-06-01" });
+    // A wildcard/non-loopback listener requires data-plane admission even for a
+    // request sent to its local 127.0.0.1 address. Reuse the same dedicated
+    // credential domain as /v1/models admission; never place it in Authorization,
+    // which can belong to an upstream provider on other data-plane surfaces.
+    const envToken = (options.env ?? process.env).OPENCODEX_API_AUTH_TOKEN?.trim();
+    const configuredToken = options.admissionConfig?.apiKeys
+      ?.find(entry => entry.key.trim().length > 0)
+      ?.key.trim();
+    const admissionToken = envToken || serviceFileToken(options.env ?? process.env) || configuredToken;
+    if (admissionToken) headers.set("x-opencodex-api-key", admissionToken);
+
     // ?ids=cli pins the readable claude-ocx id family deterministically (audit 051
     // #5): the cache prewrite must not depend on UA sniffing.
     const res = await fetch(`http://127.0.0.1:${port}/v1/models?limit=1000&ids=cli`, {
-      headers: { "anthropic-version": "2023-06-01" },
-      signal: AbortSignal.timeout(timeoutMs),
+      headers,
+      signal: AbortSignal.timeout(options.timeoutMs ?? 3_000),
     });
     if (!res.ok) return null;
     const body = await res.json() as { data?: unknown };
@@ -63,7 +100,7 @@ export async function refreshGatewayModelCacheFromProxy(port: number, timeoutMs
         id: m.id as string,
         display_name: typeof m.display_name === "string" ? m.display_name : undefined,
       }));
-    return writeGatewayModelCache(`http://127.0.0.1:${port}`, models, configDir);
+    return writeGatewayModelCache(`http://127.0.0.1:${port}`, models, options.configDir);
   } catch {
     return null;
   }

package/src/cli/claude.ts

@@ -317,7 +317,7 @@ export async function cmdClaude(args: string[]): Promise<number> {
   // Pre-write the CLI's gateway-model cache (devlog 030): without a token the CLI
   // never refreshes it, so the picker would keep showing yesterday's aliases.
   try {
-    const cachePath = await refreshGatewayModelCacheFromProxy(port);
+    const cachePath = await refreshGatewayModelCacheFromProxy(port, { admissionConfig: config });
     if (cachePath === null) {
       console.error("⚠ Gateway model cache could not be refreshed; the model picker may be stale.");
     }

package/src/cli/codex-log-guard-doctor.ts

@@ -0,0 +1,103 @@
+import { inspectCodexLogs, type CodexLogGuardInspection } from "../codex/log-guard/inspect";
+import {
+  getCodexLogGuardProtectionStatus,
+  type CodexLogGuardStatus,
+} from "../codex/log-guard/protection";
+
+function kib(bytes: number): string {
+  return `${(bytes / 1024).toFixed(1)} KiB`;
+}
+
+function fileMetadataLines(report: CodexLogGuardInspection): string[] {
+  if (report.externalSqliteHome === null) return [];
+  const location = report.externalSqliteHome ? "external sqlite_home" : "CODEX_HOME sqlite_home";
+  return [
+    `         ${location}; DB ${kib(report.files.databaseBytes)}, WAL ${kib(report.files.walBytes)}, SHM ${kib(report.files.shmBytes)}`,
+  ];
+}
+
+type DoctorReport = CodexLogGuardInspection | CodexLogGuardStatus;
+
+function protectionLines(report: DoctorReport): string[] {
+  if (!("protection" in report)) return [];
+  const protection = report.protection;
+  switch (protection.state) {
+    case "active":
+      return [`  ok     protection active (${protection.desiredMode})`];
+    case "off":
+      return ["  --     protection off"];
+    case "drifted":
+      return [
+        `  WARN   protection drifted (desired ${protection.desiredMode}; observed ${protection.observedMode})`,
+        "         Action: ocx storage codex-logs repair",
+      ];
+    case "unsupported":
+      return ["  --     protection unavailable for this schema"];
+    case "unknown":
+      return ["  WARN   protection state unknown; inspect reserved Log Guard triggers before changing mode"];
+  }
+}
+
+export function formatCodexLogGuardDoctor(report: DoctorReport): string[] {
+  const lines = ["Codex diagnostic logs"];
+  lines.push(...protectionLines(report));
+
+  if (report.schema.state === "unavailable") {
+    lines.push("  --     inspection unavailable");
+    return lines;
+  }
+  if (report.schema.state === "missing") {
+    lines.push("  --     logs_2.sqlite is not present");
+    return lines;
+  }
+  if (report.schema.state === "unreadable") {
+    lines.push("  --     logs_2.sqlite is unreadable; inspection metadata only");
+    lines.push(...fileMetadataLines(report));
+    lines.push("         checkpointed read-only snapshot; activity rate not measured");
+    return lines;
+  }
+  if (report.schema.state === "unsupported") {
+    lines.push("  --     unknown schema; inspection only");
+  } else {
+    lines.push("  ok     schema compatible");
+  }
+
+  lines.push(...fileMetadataLines(report));
+
+  if (report.metrics) {
+    lines.push(
+      `         ${report.metrics.totalRows} rows; TRACE ${(report.metrics.traceShare * 100).toFixed(1)}%; reclaimable ${kib(report.metrics.reclaimableBytes)}`,
+    );
+    const top = report.metrics.topTargets[0];
+    if (top) lines.push(`         top target ${top.target} (${top.rows} rows)`);
+  }
+
+  lines.push("         checkpointed read-only snapshot; activity rate not measured");
+  return lines;
+}
+
+export interface CodexLogGuardDoctorDeps {
+  inspect?: () => DoctorReport;
+  log?: (line: string) => void;
+}
+
+/** Observe-only doctor section. Inspection failures are reported without mutating or failing doctor. */
+export function printCodexLogGuardDoctor(deps: CodexLogGuardDoctorDeps = {}): void {
+  const inspect = deps.inspect ?? getCodexLogGuardProtectionStatus;
+  const log = deps.log ?? console.log;
+  try {
+    for (const line of formatCodexLogGuardDoctor(inspect())) log(line);
+  } catch (error) {
+    // Production can still fall back to PR 1's simpler inspector if the enriched
+    // protection lookup fails. An injected inspector is a test/caller boundary:
+    // never escape that boundary and touch the real Codex home behind its back.
+    if (!deps.inspect) {
+      try {
+        for (const line of formatCodexLogGuardDoctor(inspectCodexLogs())) log(line);
+        return;
+      } catch { /* report the original failure below */ }
+    }
+    log("Codex diagnostic logs");
+    log("  --     inspection unavailable");
+  }
+}

package/src/cli/dispatch.ts

@@ -171,8 +171,14 @@ const commandRunners: Record<string, CommandRunner> = {
     return Number(process.exitCode ?? 0);
   },
   doctor: async deps => {
+    const doctorArgs = deps.args.slice(1);
     const { runDoctor } = await import("./doctor");
-    await runDoctor(deps.args.slice(1));
+    await runDoctor(doctorArgs);
+    if (!doctorArgs.includes("--fix-codex-runtime")) {
+      console.log("");
+      const { printCodexLogGuardDoctor } = await import("./codex-log-guard-doctor");
+      printCodexLogGuardDoctor();
+    }
     return 0;
   },
   debug: async deps => {

package/src/cli/help.ts

@@ -42,7 +42,7 @@ Usage:
   ocx gui                     Open the opencodex dashboard
   ocx update [--tag <tag>]    Update opencodex (keeps preview installs on @preview)
   ocx restart                  Stop and restart the proxy
-  ocx v2 <sub>                multi_agent_v2 surface (status|on|off|mode|threads|mode-hint)
+  ocx v2 <sub>                multi_agent_v2 surface (status|on|off|mode|keep-native-v1|threads|mode-hint)
   ocx health [--json]          Check proxy health (exit 0=healthy, 1=not)
   ocx ready [--json] [--wait [--timeout <s>]]  Check post-sync readiness (exit 0 only when ready)
   ocx provider <sub>          Providers, connectivity, quota, and selected models

package/src/cli/models.ts

@@ -6,7 +6,8 @@ import { createInterface } from "node:readline/promises";
 import { syncModelsToCodex } from "../codex/sync";
 import { hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
 import { canonicalizeReasoningEfforts, isDeclaredReasoningEffort } from "../reasoning-effort";
-import { routedSlug } from "../providers/slug-codec";
+import { encodedModelIdCollides, routedSlug, slugEquals } from "../providers/slug-codec";
+import { knownModelIdsForProvider } from "../router";
 import { findLiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig, OcxCustomModel } from "../types";
 
@@ -180,7 +181,6 @@ async function handleCustomAdd(args: string[]): Promise<void> {
 
   if (!provider || !modelId) fail("provider and modelId are required", ADD_USAGE);
   if (!isValidProviderName(provider)) fail(`invalid provider name "${provider}"`);
-  if (modelId.includes("/")) fail("modelId must not contain /");
 
   const config = loadConfig();
   if (!hasOwnProvider(config.providers, provider)) {
@@ -216,6 +216,10 @@ async function handleCustomAdd(args: string[]): Promise<void> {
   if (existing.some(model => routedSlug(model.provider, model.modelId) === slug)) {
     fail(`custom model "${slug}" already exists`);
   }
+  const known = knownModelIdsForProvider(provider, config.providers[provider], config);
+  if (encodedModelIdCollides(modelId, known)) {
+    fail(`custom model "${slug}" is ambiguous; it encodes to an existing model id`);
+  }
 
   const entry: OcxCustomModel = {
     id: randomUUID(),
@@ -256,10 +260,16 @@ async function handleCustomRemove(args: string[]): Promise<void> {
 
   const config = loadConfig();
   const existing = config.customModels ?? [];
-  const index = target.includes("/")
-    ? existing.findIndex(model => routedSlug(model.provider, model.modelId) === target)
-    : existing.findIndex(model => model.id === target);
-  if (index === -1) fail(`custom model "${target}" not found`);
+  const matchingIndexes = existing.flatMap((model, index) => (
+    target.includes("/")
+      ? slugEquals(target, model.provider, model.modelId)
+      : model.id === target
+  ) ? [index] : []);
+  if (matchingIndexes.length === 0) fail(`custom model "${target}" not found`);
+  if (matchingIndexes.length > 1) {
+    fail(`custom model selector "${target}" is ambiguous; use the custom model id`);
+  }
+  const index = matchingIndexes[0]!;
 
   const model = existing[index];
   if (!confirmed && !(await confirmCustomRemoval(model))) {

package/src/cli/observe.ts

@@ -18,7 +18,7 @@ const USAGE = `Usage:
   ocx logs rebuild-index
   ocx logs index-status
   ocx observe usage [--range <7d|30d|all>] [--surface <all|codex|claude|grok>] [--json]
-  ocx observe storage [--json]
+  ocx observe storage [codex-logs [status|protect|unprotect|repair|compact] [--mode <compat|quiet>]] [--json]
   ocx observe memory [--json]
   ocx observe debug [--json]
   ocx observe claude-inbound [--limit <n>] [--json]
@@ -147,6 +147,42 @@ async function simple(path: string, argv: string[], deps: RuntimeApiDeps): Promi
   printData(result, wantsJson, summaryLines(result));
 }
 
+async function storage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  if (argv[0] !== "codex-logs") {
+    await simple("/api/storage", argv, deps);
+    return;
+  }
+
+  const args = argv.slice(1);
+  const action = args[0] && !args[0].startsWith("-") ? args.shift()! : "status";
+  const wantsJson = takeFlag(args, "--json");
+  const mode = takeOption(args, "--mode");
+  rejectArgs(args, USAGE);
+
+  let result: unknown;
+  if (action === "status") {
+    if (mode !== undefined) throw new CliUsageError("--mode is only valid with codex-logs protect", USAGE);
+    result = await runtimeRequest("/api/storage/codex-logs", {}, deps);
+  } else if (action === "protect") {
+    const requestedMode = mode ?? "compat";
+    if (requestedMode !== "compat" && requestedMode !== "quiet") {
+      throw new CliUsageError("--mode must be compat or quiet", USAGE);
+    }
+    result = await runtimeRequest("/api/storage/codex-logs/protect", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ mode: requestedMode }),
+    }, deps);
+  } else if (action === "unprotect" || action === "repair" || action === "compact") {
+    if (mode !== undefined) throw new CliUsageError("--mode is only valid with codex-logs protect", USAGE);
+    result = await runtimeRequest(`/api/storage/codex-logs/${action}`, { method: "POST" }, deps);
+  } else {
+    throw new CliUsageError(`unknown codex-logs action ${action}`, USAGE);
+  }
+
+  printData(result, wantsJson, summaryLines(result));
+}
+
 export async function handleObserveCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
   return runCliAction(async () => {
     const [sub = "logs", ...rest] = argv;
@@ -158,7 +194,7 @@ export async function handleObserveCommand(argv: string[], deps: RuntimeApiDeps
       else await logs(rest, deps);
     }
     else if (sub === "usage") await usage(rest, deps);
-    else if (sub === "storage") await simple("/api/storage", rest, deps);
+    else if (sub === "storage") await storage(rest, deps);
     else if (sub === "memory") await simple("/api/system/memory", rest, deps);
     else if (sub === "debug") await simple("/api/debug", rest, deps);
     else if (sub === "claude-inbound") await simple("/api/claude/inbound-debug", rest, deps);

package/src/cli/registry.ts

@@ -309,12 +309,13 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "v2",
-    usage: "ocx v2 <status|on|off|mode <v1|default|v2>|threads <n>>",
+    usage: "ocx v2 <status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>>",
     summary: "Toggle the Codex multi_agent_v2 feature (multi-agent surface).",
     details: [
       "status                Show flag, multi-agent mode, and thread limit.",
       "on | off              Enable/disable multi_agent_v2 (catalog resyncs).",
       "mode <v1|default|v2>  Force all models to one surface, or respect upstream pins.",
+      "keep-native-v1 <on|off>  Under mode v2, keep ChatGPT-native models on v1.",
       "threads <n>           Set max_concurrent_threads_per_session (integer >= 1).",
       "Flips preserve the active thread limit while moving between v1/v2 modes.",
     ],

package/src/cli/v2.ts

@@ -110,6 +110,9 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     log.log(v2StatusLine(isEnabled()));
     const cfg = loadConfig();
     log.log(multiAgentModeLine(cfg.multiAgentMode ?? "default"));
+    log.log(cfg.keepNativeChatGptOnV1 === true
+      ? "keep_native_chatgpt_on_v1: ON — ChatGPT-native rows stay v1 when mode is v2"
+      : "keep_native_chatgpt_on_v1: OFF");
     const threads = getLogicalMaxThreads();
     log.log(`max_threads: ${threads ?? "(unset — codex default)"}`);
     const v2Active = isEnabled();
@@ -204,8 +207,38 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     log.log("Applies to NEW sessions; running sessions keep their pinned multi-agent version.");
     return 0;
   }
+  if (verb === "keep-native-v1") {
+    const flag = (args[1] ?? "").trim().toLowerCase();
+    if (flag !== "on" && flag !== "off") {
+      log.error("v2 keep-native-v1: expected on|off");
+      return 1;
+    }
+    const cfg = loadConfig();
+    const next = flag === "on";
+    const already = cfg.keepNativeChatGptOnV1 === true === next;
+    if (next) cfg.keepNativeChatGptOnV1 = true;
+    else delete cfg.keepNativeChatGptOnV1;
+    saveConfig(cfg);
+    try {
+      const sync = deps.sync ?? (await import("../codex/sync")).syncModelsToCodex;
+      await sync(findPort ? await findPort() : undefined);
+    } catch (err) {
+      log.error(`catalog resync failed: ${err instanceof Error ? err.message : String(err)} — run 'ocx sync' manually.`);
+      return 1;
+    }
+    if (already) {
+      log.log(next
+        ? "keep_native_chatgpt_on_v1 already ON — catalog re-synced."
+        : "keep_native_chatgpt_on_v1 already OFF — catalog re-synced.");
+      return 0;
+    }
+    log.log(next
+      ? "keep_native_chatgpt_on_v1: ON — ChatGPT-native rows stay v1 when mode is v2 (new sessions)."
+      : "keep_native_chatgpt_on_v1: OFF — ChatGPT-native rows follow v1/base/v2 (new sessions).");
+    return 0;
+  }
   if (verb !== "on" && verb !== "off") {
-    log.error(`v2: unknown verb '${verb}' (expected status|on|off|mode <v1|default|v2>|threads <n>|mode-hint <text|--clear>)`);
+    log.error(`v2: unknown verb '${verb}' (expected status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>)`);
     return 1;
   }