@iislee/opencodex 2.11.0 → 2.31.0

package/src/cli/claude.ts

@@ -12,11 +12,15 @@ import { injectClaudeAgentDefs } from "../claude/agents-inject";
 import { effectiveModelEnv, resolveAutoContext } from "../claude/context-windows";
 import { refreshGatewayModelCacheFromProxy } from "../claude/gateway-cache";
 import { commandInvocation } from "../lib/win-exec";
+import { isProxyAdmissionSecret } from "../server/auth-cors";
 import { findLiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import { configuredAdminToken } from "../lib/admin-secrets";
 import { PROXY_MARKER, ownAdmissionTokens, defaultAuthDetectDeps, detectClaudeAuth, type AuthDetectDeps } from "../claude/auth-detect";
 import { resolveClaudeAuthMode } from "../claude/auth-mode";
+import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
+import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { ANTHROPIC_PARENT_ENV_SLOTS, trustedNodeLauncherContext, type AnthropicParentEnvSlot } from "./launcher-context";
 
 export interface ClaudeLaunchEnv {
   [key: string]: string | undefined;
@@ -26,13 +30,41 @@ export interface ClaudeLaunchEnv {
  * Injectable IO for tests. `env` is deliberately NOT injectable: it is bound to the
  * launch base so detection and the spawned process can never disagree (audit R3-3).
  */
-export type ClaudeEnvDeps = { authDetect?: Omit<Partial<AuthDetectDeps>, "env" | "ownTokens"> };
+export type ClaudeEnvDeps = {
+  authDetect?: Omit<Partial<AuthDetectDeps>, "env" | "ownTokens">;
+  /** Test seam; production uses the authenticated Node-launcher context. */
+  preBunAnthropicSlots?: readonly AnthropicParentEnvSlot[] | null;
+};
+
+function isClaudeLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname.toLowerCase().replace(/\.$/, "");
+  return normalized === "localhost"
+    || normalized === "127.0.0.1"
+    || normalized === "::1"
+    || normalized === "[::1]";
+}
+
+function targetsLocalClaudeProxy(value: string | undefined, port: number): boolean {
+  if (!value) return false;
+  try {
+    const parsed = new URL(value);
+    const effectivePort = parsed.port === "" ? 80 : Number(parsed.port);
+    return parsed.protocol === "http:"
+      && isClaudeLoopbackHostname(parsed.hostname)
+      && effectivePort === port
+      && parsed.username === ""
+      && parsed.password === "";
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Pure env assembly (unit-tested): never sets ANTHROPIC_API_KEY (setting both
  * token vars triggers Claude Code's auth-conflict warning, 003 E1), and never
- * overrides variables the user already exported, apart from stale loopback
- * ANTHROPIC_BASE_URL values owned by a previous opencodex launch.
+ * preserves Anthropic variables proven to exist in the parent Node launcher,
+ * apart from stale loopback ANTHROPIC_BASE_URL values owned by a previous
+ * opencodex launch. Unproven ambient values fail closed as project dotenv.
  */
 export function buildClaudeEnv(
   config: OcxConfig,
@@ -47,28 +79,37 @@ export function buildClaudeEnv(
   // stale marker left in place would suppress the admission key and then be removed,
   // leaving the child with no token at all (audit R2-1). It is opencodex state, never
   // user auth, so dropping it unconditionally is safe.
-  if (env.ANTHROPIC_AUTH_TOKEN === PROXY_MARKER) delete env.ANTHROPIC_AUTH_TOKEN;
-  // Step 1b — drop Anthropic credentials that the bundled Bun runtime synthesized from a
-  // project `.env`/`.env.local` (issue #701). Claude Code disables claude.ai connectors the
-  // moment either token slot is populated, so an ambient project file silently moved a
-  // subscriber onto API billing while their OAuth login stayed healthy. The npm launcher
-  // runs under Node, which does NOT auto-load dotenv, so it records the slots that existed
-  // before Bun started; anything populated now but absent then came from the working
-  // directory, not from the user. A genuine shell export is still honored, which keeps
-  // auto-mode API-key auth working. An ABSENT marker means provenance is unknowable
-  // (a direct `bun src/cli/index.ts` run, a test, or an older launcher), and then we
-  // change nothing rather than guess — an EMPTY marker is different: the launcher ran
-  // and saw no pre-existing slots.
-  const preBunSlots = base.OCX_PRE_BUN_ANTHROPIC_ENV;
-  if (preBunSlots !== undefined) {
-    const exported = new Set(preBunSlots.split(",").filter(name => name.length > 0));
-    for (const name of ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"] as const) {
-      const value = env[name];
-      if (value !== undefined && value !== "" && !exported.has(name)) delete env[name];
-    }
+  if (env.ANTHROPIC_AUTH_TOKEN?.trim() === PROXY_MARKER) delete env.ANTHROPIC_AUTH_TOKEN;
+  // Step 1b — drop Anthropic credentials AND destinations that Bun may have synthesized
+  // from a project `.env`/`.env.local`. The plain-Node launcher records genuine parent
+  // exports before Bun starts and pairs that context with an argv proof, so with a
+  // trusted context we know exactly which slots the user really exported.
+  //
+  // Without a trusted context all three slots are treated as project-controlled. An
+  // earlier revision of this branch preserved credentials here, reasoning that the
+  // destination is pinned below so a dotenv key would only ever reach the local proxy.
+  // That reasoning is wrong, and review caught it: `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`
+  // is only set when we own an auth token (see below, and #253 for why asserting it
+  // otherwise logs a subscriber out), so on a subscription launch Claude Code's
+  // settings.env merge can still replace `ANTHROPIC_BASE_URL` after we return. A
+  // preserved key then travels to that host. The repository documents that residual for
+  // subscription mode; it must not be widened into a credential leak.
+  //
+  // Direct `bun src/cli/index.ts` therefore loses ambient Anthropic values. That is a
+  // real cost to a documented entry point, and the escape hatch is the launcher: run
+  // through `ocx` (the published bin) and genuine shell exports are preserved by proof.
+  const explicitSlots = deps.preBunAnthropicSlots;
+  const trustedSlots = explicitSlots === undefined
+    ? trustedNodeLauncherContext()?.anthropicEnvSlots ?? []
+    : explicitSlots ?? [];
+  const exported = new Set<AnthropicParentEnvSlot>(trustedSlots);
+  for (const name of ANTHROPIC_PARENT_ENV_SLOTS) {
+    const value = env[name];
+    if (value !== undefined && value !== "" && !exported.has(name)) delete env[name];
   }
-  // Never forward the seam itself to Claude Code.
+  // Never forward old or current provenance seams to Claude Code.
   delete env.OCX_PRE_BUN_ANTHROPIC_ENV;
+  delete env.OCX_NODE_LAUNCH_CONTEXT;
   const setDefault = (name: string, value: string | undefined) => {
     if (value === undefined || value.length === 0) return;
     if (env[name] !== undefined && env[name] !== "") return; // user wins
@@ -79,10 +120,12 @@ export function buildClaudeEnv(
   if (existingBaseUrl) {
     try {
       const parsed = new URL(existingBaseUrl);
-      const isLoopback = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
-      if (isLoopback && parsed.port !== "" && Number(parsed.port) !== port) {
+      const effectivePort = parsed.port === "" ? 80 : Number(parsed.port);
+      if (parsed.protocol === "http:"
+        && isClaudeLoopbackHostname(parsed.hostname)
+        && effectivePort !== port) {
         const replacement = `http://127.0.0.1:${port}`;
-        console.error(`⚠ Replacing stale opencodex ANTHROPIC_BASE_URL ${existingBaseUrl} with ${replacement}.`);
+        console.error(`⚠ Replacing stale opencodex ANTHROPIC_BASE_URL ${parsed.origin} with ${replacement}.`);
         env.ANTHROPIC_BASE_URL = replacement;
       }
     } catch {
@@ -94,8 +137,26 @@ export function buildClaudeEnv(
   // the user's Claude login. Only inject a token when the proxy actually requires an
   // admission key; otherwise Claude Code keeps its own OAuth and sends it to us —
   // native claude models then pass through verbatim (see server/claude-messages.ts).
-  if ((config.apiKeys?.length ?? 0) > 0) {
-    setDefault("ANTHROPIC_AUTH_TOKEN", config.apiKeys![0].key);
+  const ownTokens = ownAdmissionTokens(config);
+  const targetsLocalProxy = targetsLocalClaudeProxy(env.ANTHROPIC_BASE_URL, port);
+  const inheritedApiKey = env.ANTHROPIC_API_KEY;
+  if (typeof inheritedApiKey === "string" && isProxyAdmissionSecret(inheritedApiKey, config)) {
+    delete env.ANTHROPIC_API_KEY;
+  }
+  const hasUserApiKey = Boolean(env.ANTHROPIC_API_KEY?.trim());
+  const inheritedAuthToken = env.ANTHROPIC_AUTH_TOKEN;
+  const inheritedTokenIsOurs = typeof inheritedAuthToken === "string"
+    && isProxyAdmissionSecret(inheritedAuthToken, config);
+  // system-env may have injected the proxy's admission key into the parent. A
+  // proof-bound external BASE_URL is still user-owned, so never let our inherited
+  // key follow it. A user API key also wins on a local launch; remove only the token
+  // values recognized by the shared proxy-admission contract and preserve every
+  // other token.
+  if (inheritedTokenIsOurs && (!targetsLocalProxy || hasUserApiKey)) {
+    delete env.ANTHROPIC_AUTH_TOKEN;
+  }
+  if (targetsLocalProxy && !hasUserApiKey && ownTokens.length > 0) {
+    setDefault("ANTHROPIC_AUTH_TOKEN", ownTokens[0]);
   }
   // Detection reads the SANITIZED launch env — the exact object spawned below — so the
   // resolver and the spawned process cannot disagree. It deliberately does NOT read the
@@ -110,11 +171,19 @@ export function buildClaudeEnv(
     ...defaultAuthDetectDeps(env as NodeJS.ProcessEnv),
     ...(deps.authDetect ?? {}),
     env: () => env as NodeJS.ProcessEnv,
-    ownTokens: ownAdmissionTokens(config),
+    ownTokens,
   }));
-  if (!env.ANTHROPIC_AUTH_TOKEN && resolved.markerMode === "proxy") {
+  if (!env.ANTHROPIC_AUTH_TOKEN && !hasUserApiKey && targetsLocalProxy && resolved.markerMode === "proxy") {
     env.ANTHROPIC_AUTH_TOKEN = PROXY_MARKER;
   }
+  const finalAuthToken = env.ANTHROPIC_AUTH_TOKEN;
+  const hostOwnsAuthentication = targetsLocalProxy
+    && !hasUserApiKey
+    && typeof finalAuthToken === "string"
+    && (
+      finalAuthToken.trim() === PROXY_MARKER
+      || isProxyAdmissionSecret(finalAuthToken, config)
+    );
   if (resolved.origin === "auto-unknown") {
     console.error("⚠ Claude 인증을 확인하지 못했습니다 — 구독 방식으로 진행합니다. GUI에서 인증 모드를 직접 지정하면 이 판단을 덮어쓸 수 있습니다.");
   }
@@ -136,7 +205,7 @@ export function buildClaudeEnv(
   // Claude Code 2.1.206+ also treats this as a host-auth assertion. Injecting it
   // without a host token makes a valid claude.ai subscription look logged out,
   // so the guard is only safe when opencodex actually owns authentication.
-  if (env.ANTHROPIC_AUTH_TOKEN) {
+  if (hostOwnsAuthentication) {
     setDefault("CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST", "1");
   }
   // Opt-in effort forcing (devlog 136 B6): opus-shaped aliases already carry
@@ -201,11 +270,11 @@ async function ensureProxyForClaude(): Promise<number | null> {
   if (live) return live.port;
   const cfgPort = loadConfig().port;
   const pinPort = typeof cfgPort === "number" && cfgPort > 0 ? cfgPort : 10100;
-  const child = spawn(process.execPath, [process.argv[1], "start", "--port", String(pinPort)], {
+  const child = spawn(process.execPath, selfLaunchArgv(["start", "--port", String(pinPort)]), {
     detached: true,
     stdio: "ignore",
     windowsHide: true,
-    env: { ...process.env, OCX_SERVICE: "1" },
+    env: withProcessRuntimeProvenance({ ...process.env, OCX_SERVICE: "1" }),
   });
   child.unref();
   const deadline = Date.now() + 8_000;
@@ -248,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/codex-shim-autorestore.ts

@@ -17,6 +17,8 @@ const DEFAULT_DEPS: CodexShimAutoRestoreCliDeps = {
 
 export function skipsCodexShimAutoRestore(command: string | undefined, args: string[]): boolean {
   if (command === "uninstall" || command === "remove") return true;
+  // `lab` is read-only inspection; it must not trigger shim side effects.
+  if (command === "lab") return true;
   return command === "codex-shim" && ["install", "uninstall", "remove"].includes(args[1] ?? "");
 }
 

package/src/cli/codex-shim-readiness.ts

@@ -0,0 +1,76 @@
+import {
+  currentExternalCodexModelProvider,
+  getCodexRoutingKind,
+  type CodexRoutingKind,
+} from "../codex/inject";
+import { loadConfig, resolveEnvValue } from "../config";
+
+const PROXY_ENV_KEYS = [
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "all_proxy",
+] as const;
+
+export interface CodexShimReadinessInputs {
+  routingKind: CodexRoutingKind;
+  externalProvider: string | null;
+  processProxyEnvPresent: boolean;
+  configuredProxyResolved: boolean;
+}
+
+function externalProviderLabel(provider: string | null): string {
+  return provider
+    ? `external model_provider ${JSON.stringify(provider)}`
+    : "the active Codex route";
+}
+
+export function codexShimReadinessWarnings(
+  inputs: CodexShimReadinessInputs,
+): string[] {
+  const warnings: string[] = [];
+  const provider = externalProviderLabel(inputs.externalProvider);
+
+  if (inputs.routingKind === "unknown") {
+    warnings.push(
+      inputs.externalProvider
+        ? `Codex still selects ${provider}. The shim can start OpenCodex, but it does not redirect that provider; point it at the live OpenCodex /v1 endpoint with wire_api = "responses", or switch to the built-in openai provider and run 'ocx sync'.`
+        : "Codex routing could not be verified. The shim can start OpenCodex, but it may not redirect Codex; run 'ocx doctor' before relying on autostart.",
+    );
+  } else if (inputs.routingKind === "custom-local") {
+    warnings.push(
+      `Codex uses ${provider} through a user-owned local gateway. The shim can start OpenCodex, but OpenCodex does not own that route; run 'ocx doctor' to verify its lifecycle.`,
+    );
+  } else if (inputs.routingKind === "custom-remote") {
+    warnings.push(
+      `Codex uses ${provider} through a remote gateway. The shim only starts a local OpenCodex proxy and will not affect those requests.`,
+    );
+  }
+
+  if (inputs.processProxyEnvPresent && !inputs.configuredProxyResolved) {
+    warnings.push(
+      "Proxy environment variables are present only in this process while config.proxy is unset or unresolved. Codex launchers and background services may not inherit them; persist config.proxy before relying on autostart.",
+    );
+  }
+
+  return warnings;
+}
+
+export function collectCodexShimReadinessWarnings(): string[] {
+  const config = loadConfig();
+  let externalProvider: string | null = null;
+  try {
+    externalProvider = currentExternalCodexModelProvider();
+  } catch {
+    // Routing readiness is advisory; getCodexRoutingKind() already reports an
+    // unreadable config as unknown, so preserve that warning instead of failing.
+  }
+  return codexShimReadinessWarnings({
+    routingKind: getCodexRoutingKind(),
+    externalProvider,
+    processProxyEnvPresent: PROXY_ENV_KEYS.some(key => Boolean(process.env[key]?.trim())),
+    configuredProxyResolved: Boolean(resolveEnvValue(config.proxy)?.trim()),
+  });
+}

package/src/cli/combo.ts

@@ -16,6 +16,7 @@ const USAGE = `Usage:
   ocx combo set <id> --targets <provider/model[:weight],...>
       [--strategy <failover|round-robin>] [--sticky <1-100>]
       [--effort <low|medium|high|xhigh|max|ultra|->] [--alias <name|->]
+      [--native-alias] [--display-name <label|->]
       [--rename-from <id>] [--json]
   ocx combo remove <id> --yes [--json]`;
 
@@ -77,6 +78,8 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   if (stickyLimit > 100) throw new CliUsageError("--sticky must be <= 100", USAGE);
   const effort = takeOption(args, "--effort");
   const alias = takeOption(args, "--alias");
+  const nativeAlias = takeFlag(args, "--native-alias");
+  const displayName = takeOption(args, "--display-name");
   const renameFrom = takeOption(args, "--rename-from");
   rejectArgs(args, USAGE);
   const combo: Record<string, unknown> = {
@@ -86,6 +89,11 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   };
   if (effort !== undefined) combo.defaultEffort = effort === "-" ? null : effort;
   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";
   const result = await runtimeRequest("/api/combos", {
     method: "PUT",
     body: JSON.stringify({ id, combo, ...(renameFrom ? { renameFrom } : {}) }),

package/src/cli/config-command.ts

@@ -1,6 +1,9 @@
 import { readFileSync, writeFileSync } from "node:fs";
-import { getConfigPath, readConfigDiagnostics, saveConfig, validateConfigCandidate } from "../config";
+import { clearCodexAccountPin } from "../codex/account-priority";
+import { getConfigPath, mutatePersistedConfig, readConfigDiagnostics, sanitizeModelCostsForDisplay, saveConfig, validateConfigCandidate } from "../config";
+import { VISION_REASONING_EFFORTS, isVisionReasoningEffort } from "../reasoning-effort";
 import type { OcxConfig } from "../types";
+import { normalizeVisionReasoningForModel } from "../vision/reasoning";
 import { CliUsageError, printData, rejectArgs, runCliAction, takeFlag } from "./runtime-api";
 
 const USAGE = `Usage:
@@ -17,6 +20,9 @@ const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
 
 function redact(value: unknown, key = ""): unknown {
   if (SECRET_KEYS.test(key) && typeof value === "string") return value ? "********" : value;
+  // modelCosts rows are keyed by model id; a pasted API key in a key position
+  // must not be echoed back by config show/get (values are already redacted).
+  if (key === "modelCosts") return sanitizeModelCostsForDisplay(value);
   if (Array.isArray(value)) return value.map(item => redact(item));
   if (value && typeof value === "object") {
     return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([childKey, child]) => [childKey, redact(child, childKey)]));
@@ -64,10 +70,36 @@ function loadInput(path: string): unknown {
   catch { throw new CliUsageError(`invalid JSON in ${path}`); }
 }
 
+function visionReasoningError(value: unknown): string | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const vision = (value as Record<string, unknown>).visionSidecar;
+  if (!vision || typeof vision !== "object" || Array.isArray(vision)) return null;
+  const reasoning = (vision as Record<string, unknown>).reasoning;
+  if (reasoning === undefined || isVisionReasoningEffort(reasoning)) return null;
+  return `schema_invalid: visionSidecar.reasoning: must be one of ${VISION_REASONING_EFFORTS.join(", ")}`;
+}
+
+function validateCandidate(value: unknown): ReturnType<typeof validateConfigCandidate> {
+  const error = visionReasoningError(value);
+  return error ? { ok: false, error } : validateConfigCandidate(value);
+}
+
+function normalizeVisionConfig(config: OcxConfig): OcxConfig {
+  const vision = config.visionSidecar;
+  if (!vision || vision.reasoning === undefined) return config;
+  // Keep CLI import/set semantics aligned with the execution path: an omitted or blank model means
+  // the bounded OpenAI vision default, gpt-5.4-mini, not the Dashboard's web-search default.
+  const model = vision.model || "gpt-5.4-mini";
+  const normalized = normalizeVisionReasoningForModel(model, vision.reasoning);
+  if (normalized === undefined) delete vision.reasoning;
+  else vision.reasoning = normalized;
+  return config;
+}
+
 function validate(value: unknown): OcxConfig {
-  const result = validateConfigCandidate(value);
+  const result = validateCandidate(value);
   if (!result.ok) throw new CliUsageError(result.error);
-  return result.config;
+  return normalizeVisionConfig(result.config);
 }
 
 export async function handleConfigCommand(argv: string[]): Promise<number> {
@@ -98,11 +130,42 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       const raw = action === "set" ? args.shift() : undefined;
       if (!path || (action === "set" && raw === undefined)) throw new CliUsageError("config path and value are required", USAGE);
       rejectArgs(args, USAGE);
-      const candidate = structuredClone(readConfigDiagnostics().config) as unknown as Record<string, unknown>;
-      setPath(candidate, path, raw === undefined ? undefined : parseValue(raw), action === "unset");
-      const config = validate(candidate);
-      const savedValue = action === "unset" ? null : getPath(config, path);
-      saveConfig(config);
+      // #1835/#1838: the read used to happen OUTSIDE the mutation lock, so a concurrent
+      // edit landing between it and the save was reverted by this whole-snapshot write.
+      // `mutatePersistedConfig` reruns this callback against the latest validated disk
+      // state, so the operation is applied to what is actually there at commit time.
+      let savedValue: unknown = null;
+      const outcome = mutatePersistedConfig(fresh => {
+        // Snapshot BEFORE mutating: comparing after the write compares a value with
+        // itself and would report every no-op as a change, bumping the generation.
+        const before = JSON.stringify(fresh);
+        const candidate = structuredClone(fresh) as unknown as Record<string, unknown>;
+        setPath(candidate, path, raw === undefined ? undefined : parseValue(raw), action === "unset");
+        const config = validate(candidate);
+        savedValue = action === "unset" ? null : getPath(config, path);
+        // Setting the order here is the operator restating it, exactly as through
+        // `ocx account priority` or the management route, so it releases the manual pin
+        // for the same reason those do: a pin made before any order existed would
+        // otherwise outrank every order set afterwards, capping the pool at the pinned
+        // account's tier with nothing on any surface explaining why. `import` is
+        // deliberately not covered — that file supplies its own pin, so there is no
+        // stale one to release.
+        if (pathSegments(path)[0] === "codexAccountPriorities") clearCodexAccountPin(config);
+        // REPLACE rather than merge: `Object.assign` alone cannot remove a key that
+        // `unset` deleted, which would make unset silently succeed while changing nothing.
+        for (const key of Object.keys(fresh)) {
+          if (!(key in (config as unknown as Record<string, unknown>))) {
+            delete (fresh as unknown as Record<string, unknown>)[key];
+          }
+        }
+        Object.assign(fresh, config);
+        return { changed: JSON.stringify(fresh) !== before, value: undefined };
+      });
+      if (outcome.status === "unavailable") {
+        throw new Error(outcome.reason === "conflict"
+          ? "config changed while applying this update; retry"
+          : `config is ${outcome.reason}`);
+      }
       printData({ ok: true, path, value: redact(savedValue, path.split(".").at(-1)) }, wantsJson,
         [`${action === "unset" ? "Unset" : "Set"} ${path}.`]);
       return;
@@ -110,9 +173,10 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
     if (action === "validate") {
       const path = args.shift();
       rejectArgs(args, USAGE);
-      const result = path ? validateConfigCandidate(loadInput(path)) : (() => {
+      const result = path ? validateCandidate(loadInput(path)) : (() => {
         const diagnostics = readConfigDiagnostics();
-        return diagnostics.error ? { ok: false as const, error: diagnostics.error } : { ok: true as const, config: diagnostics.config };
+        if (diagnostics.error) return { ok: false as const, error: diagnostics.error };
+        return validateCandidate(diagnostics.config);
       })();
       printData(result.ok ? { ok: true, source: path ?? getConfigPath() } : result, wantsJson,
         [result.ok ? "Config is valid." : `Config is invalid: ${result.error}`]);