@bitkyc08/opencodex 2.68.0-preview.20260927 → 2.69.0-preview.20260928

package/src/cli/cross-home-owner.ts

@@ -0,0 +1,138 @@
+/** Best-effort discovery of a live proxy named by shared, OpenCodex-managed client state. */
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { getConfigDir } from "../config/paths";
+import { readRuntimePort } from "../config/process-state";
+import { getCodexHome } from "../codex/paths";
+import { detectCodexRoutingDrift } from "../codex/routing-drift";
+import { readBoundedCodexConfig } from "../codex/inject/bounded-config-reader";
+import { currentExternalCodexModelProvider } from "../codex/inject";
+import { reconcileJournal } from "../codex/journal";
+import { markSiblingStart, siblingOfLivePort } from "../codex/sibling-start";
+import { readClientConnectionState } from "../client/state";
+import { findManagedRegion, resolveGrokHome } from "../grok/inject";
+import { providerTableString } from "../codex/injected-marker";
+import { probePortOwner, START_OWNERSHIP_LIVENESS } from "../server/proxy-liveness";
+
+const MAX_HINT_BYTES = 256 * 1024;
+// Far above any real Grok config; discovery must not stall startup when Grok sync is off.
+const MAX_GROK_CONFIG_BYTES = 16 * 1024 * 1024;
+
+/** Nonblocking open (a FIFO cannot stall startup), regular files only, capped at maxBytes. */
+function readBoundedRegularFile(path: string, maxBytes: number): string | null {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > maxBytes) return null;
+    const bytes = Buffer.alloc(stat.size + 1);
+    let count = 0;
+    while (count < bytes.length) {
+      const next = readSync(fd, bytes, count, bytes.length - count, count);
+      if (next === 0) break;
+      count += next;
+    }
+    return count > maxBytes || count > stat.size ? null : bytes.toString("utf8", 0, count);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function validPort(value: unknown): value is number {
+  return Number.isInteger(value) && Number(value) > 0 && Number(value) <= 65535;
+}
+
+function loopbackPort(raw: string | null): number | null {
+  if (!raw) return null;
+  try {
+    const url = new URL(raw);
+    if (!url.port || !["http:", "https:"].includes(url.protocol)) return null;
+    const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if (!["127.0.0.1", "localhost", "::1"].includes(host)) return null;
+    const port = Number(url.port);
+    return validPort(port) ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Returns only a different process with an identity-checked /healthz response. */
+export async function findCrossHomeOwner(options: { homeDir?: string } = {}): Promise<number | null> {
+  const candidates = new Set<number>();
+  const defaultHome = join(options.homeDir ?? homedir(), ".opencodex");
+  if (resolve(getConfigDir()) !== resolve(defaultHome)) {
+    const raw = readBoundedRegularFile(join(defaultHome, "runtime-port.json"), MAX_HINT_BYTES);
+    if (raw) {
+      try {
+        const record: unknown = JSON.parse(raw);
+        if (record && typeof record === "object" && validPort((record as { port?: unknown }).port)) {
+          candidates.add((record as { port: number }).port);
+        }
+      } catch { /* stale or malformed hint */ }
+    }
+  }
+
+  // Grok's writer reads its config in full; cap discovery separately so startup stays bounded.
+  const grok = readBoundedRegularFile(join(resolveGrokHome(), "config.toml"), MAX_GROK_CONFIG_BYTES);
+  const region = grok === null ? null : findManagedRegion(grok);
+  if (grok && region && !region.orphaned) {
+    const port = loopbackPort(providerTableString(grok.slice(region.start, region.end), "opencodex", "base_url"));
+    if (port !== null) candidates.add(port);
+  }
+
+  try {
+    const codex = readBoundedCodexConfig(join(getCodexHome(), "config.toml"));
+    if (codex) {
+      const drift = detectCodexRoutingDrift(codex, { ownPorts: [] });
+      if (drift.kind === "foreign") {
+        for (const target of drift.targets) {
+          // Every drift target is owned, loopback, and has an explicit port (including Design B roots).
+          candidates.add(target.port);
+        }
+      }
+    }
+  } catch { /* an absent or invalid client home is not owner evidence */ }
+
+  for (const port of candidates) {
+    const owner = await probePortOwner(port, {}, START_OWNERSHIP_LIVENESS);
+    if (owner && Number.isSafeInteger(owner.pid) && owner.pid! > 0 && owner.pid !== process.pid) return port;
+  }
+  return null;
+}
+
+/** Mark this process before any shared-client write when another home owns the clients. */
+export async function markCrossHomeSibling(): Promise<boolean> {
+  const port = await findCrossHomeOwner();
+  if (port === null) return false;
+  markSiblingStart(port);
+  return true;
+}
+
+/** A live proxy in this home can publish its sibling owner even while that owner is down. */
+export async function markLiveHomeSibling(live: { pid: number | null; port: number }): Promise<boolean> {
+  const runtime = readRuntimePort();
+  if (live.pid !== null && runtime?.pid === live.pid && runtime.port === live.port
+    && runtime.siblingOfPort !== undefined && runtime.siblingOfPort !== live.port) {
+    markSiblingStart(runtime.siblingOfPort);
+    return true;
+  }
+  const otherPort = await findCrossHomeOwner();
+  if (otherPort === null || otherPort === live.port) return false;
+  markSiblingStart(otherPort);
+  return true;
+}
+
+/**
+ * Recovery follows the full owner decision; a sibling never replays another home's journal.
+ * A marked sibling's owner can be down mid-restart; its journal is still not ours to replay.
+ */
+export function reconcileStartupJournal(): void {
+  if (currentExternalCodexModelProvider() || siblingOfLivePort() !== null) return;
+  const clientState = readClientConnectionState();
+  reconcileJournal(clientState.kind === "connected"
+    ? { activeClientApiKeyId: clientState.value.apiKeyId }
+    : undefined);
+}

package/src/cli/dispatch.ts

@@ -512,7 +512,7 @@ const commandRunners: Record<string, CommandRunner> = {
             },
             config,
             port: live.port,
-          }, ["mcode", "pi", "raycast", "omo", "cline"]));
+          }, ["mcode", "pi", "raycast", "omo", "cline", "droid"]));
         } catch (error) {
           console.warn(`Client integrations were not refreshed: ${error instanceof Error ? error.message : String(error)}`);
         }

package/src/cli/doctor.ts

@@ -12,7 +12,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { getConfigDir, getConfigPath, readConfigDiagnostics } from "../config";
 import { readPid } from "../config/process-state";
-import { probeUncleanExitState } from "./status";
+import { fetchLiveStartupHealth, probeUncleanExitState, selectStatusStartupHealth } from "./status";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";
 import { BUN_RUNTIME_SOURCES } from "../lib/bun-runtime";
@@ -61,6 +61,7 @@ import {
   formatLegacyCodexConfigKeyDiagnosticsForDoctor,
 } from "../codex/legacy-config-keys";
 import { collectStartupHealth, formatStartupRoutingDetail, startupHealthSummary } from "../codex/autostart-health";
+import { collectDesktopSystemProxy, formatDesktopSystemProxyLines } from "../claude/desktop-system-proxy";
 import {
   displayCodexRuntimePath,
   effortClampAppliesToRuntime,
@@ -1354,7 +1355,14 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     diagnoseCodexShim(),
     serviceTokenPresent,
   );
-  const startup = collectStartupHealth(doctorConfig);
+  // Use the same attested live startup verdict as `ocx status` when the proxy is already
+  // identity-verified. A shell-local systemd probe can be a false negative for a system-wide
+  // service because the shell does not inherit the manager-owned environment.
+  const live = await findLiveProxy({
+    configFn: () => ({ port: doctorConfig.port, hostname: doctorConfig.hostname }),
+  });
+  const liveStartup = live ? await fetchLiveStartupHealth(live) : null;
+  const startup = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(doctorConfig));
   console.log("\nCodex restart safety");
   console.log(`  ${startup.rebootSafe ? "ok " : "!! "} ${startupHealthSummary(startup)}`);
   console.log(`       ${formatStartupRoutingDetail(startup)}`);
@@ -1393,12 +1401,6 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     }
   }
 
-  // #618: identity-verified liveness first so pid-file absence does not hide a live service.
-  // Reuse the diagnostics config already loaded above so doctor stays read-only on malformed JSON.
-  const live = await findLiveProxy({
-    configFn: () => ({ port: doctorConfig.port, hostname: doctorConfig.hostname }),
-  });
-
   // Mirrors `ocx status` through the same comparison rather than a second implementation:
   // two diagnostics disagreeing about whether an install is stale is worse than one (#2701).
   // No extra probe -- findLiveProxy already carried the version back.
@@ -1427,6 +1429,14 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   console.log("\nConfigured proxy (value hidden)");
   console.log(`  ${configuredProxy.present ? "set    " : "unset  "} ${configuredProxy.key} (${configuredProxy.source}; ${configuredProxy.detail})`);
 
+  // Observe-only and warning-level: a bypassed Desktop first-party install still serves the
+  // CLI and every non-Desktop client, so this never records a doctor failure.
+  const desktopSystemProxyLines = formatDesktopSystemProxyLines(collectDesktopSystemProxy(doctorConfig));
+  if (desktopSystemProxyLines.length > 0) {
+    console.log("\nClaude Desktop first-party vs Windows system proxy");
+    for (const line of desktopSystemProxyLines) console.log(line);
+  }
+
   const providerApiKeys = collectProviderApiKeyDiagnostics(doctorConfig.providers);
   console.log("\nProvider API keys (value hidden)");
   if (providerApiKeys.length === 0) {

package/src/cli/ensure-desired-integrations.ts

@@ -30,6 +30,7 @@ import {
   shouldSyncGrokOnStart,
 } from "../codex/desired-state";
 import type { OcxConfig } from "../types";
+import { siblingOfLivePort, siblingSkipMessage } from "../codex/sibling-start";
 
 export function grokSyncFailureMessage(err: unknown): string {
   const detail = err instanceof Error ? err.message : String(err);
@@ -101,6 +102,10 @@ export async function ensureGrokFenceMatchesDesired(
 ): Promise<void> {
   const config = deps.loadConfig();
   const { log, error } = io(deps);
+  if (siblingOfLivePort() !== null) {
+    log(`   ${siblingSkipMessage()} ~/.grok/config.toml was left exactly as it is.`);
+    return;
+  }
   // A hub-gated skip is NOT "the user turned Grok off" (#4236). Stripping the managed block
   // there deleted a fence the operator still wants — and `ocx ensure` reported it as the
   // Grok toggle doing its job. Only an explicit OFF authorizes the strip; the gate just

package/src/cli/export-command.ts

@@ -1,8 +1,8 @@
 /**
  * `ocx export --client <id>` — print a client config for the live proxy.
  *
- * Fourteen clients, five formats. The accepted list is `EXPORT_CLIENT_IDS`, not
- * this comment: OpenCode, Pi, Prime, Aside, ZCode and omo are JSON; OMP,
+ * The accepted clients span five formats. The accepted list is `EXPORT_CLIENT_IDS`, not
+ * this comment: OpenCode, Pi, Prime, Aside, ZCode, omo and Kilo are JSON; OMP,
  * Hermes, gjc, DSH, MiniMax Code and Raycast are YAML; OpenClaw is JSON5; Kimi
  * is TOML.
  *
@@ -159,16 +159,16 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
     const spec = EXPORT_CLIENTS[client];
     const root = await runtimeBaseUrl(deps);
     let built: { document: unknown; text: string };
-    if (client === "raycast") {
+    if (client === "raycast" || client === "droid") {
       // The dial address alone cannot distinguish a wildcard authenticated bind
       // from loopback. Let the live server resolve its admission/listener policy;
       // saved config can differ from the process serving this request.
       const exported = await runtimeRequest<{
         client: string; format: string; config: unknown; text: string;
-      }>("/api/client-config?client=raycast", {}, { ...deps, baseUrl: root });
-      if (!exported || exported.client !== "raycast" || exported.format !== "yaml"
+      }>(`/api/client-config?client=${client}`, {}, { ...deps, baseUrl: root });
+      if (!exported || exported.client !== client || exported.format !== spec.format
         || typeof exported.text !== "string" || exported.config === undefined) {
-        throw new RuntimeApiError("Management API returned an unexpected Raycast export payload.", 502, null);
+        throw new RuntimeApiError(`Management API returned an unexpected ${client} export payload.`, 502, null);
       }
       built = { document: exported.config, text: exported.text };
     } else {

package/src/cli/help.ts

@@ -83,7 +83,7 @@ Usage:
   ocx api-key <sub>           Alias of ocx access key
   ocx access <sub>            External API keys and endpoint information
   ocx api <sub>               Protocol paths: vocabulary, request-path preview, and policy
-  ocx export --client <id>    Print a client config wired to the running proxy (15 clients)
+  ocx export --client <id>    Print a client config wired to the running proxy (17 clients)
   ocx integration client <sub> Enable, disable, inspect or roll back a client integration
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, OpenCodex updates, and Codex CLI inspection

package/src/cli/index.ts

@@ -38,7 +38,7 @@ import {
   resolveCodexHistoryJobTarget,
   runCodexHistoryJob,
 } from "../codex/history-job";
-import { reconcileJournal } from "../codex/journal";
+import { findCrossHomeOwner, markCrossHomeSibling, markLiveHomeSibling, reconcileStartupJournal } from "./cross-home-owner";
 import { inspectClientRotationRecoveryGate, readClientConnectionState } from "../client/state";
 import {
   codexAutoStartEnabled,
@@ -355,24 +355,15 @@ async function findProxyOwnerBeforeJournalRecovery(
   const pidSnapshot = readPidFileValue();
   const hasRuntimeOwner = readRuntimePort() !== null;
   const shouldProbe = pidSnapshot !== null || hasRuntimeOwner || options.probeConfiguredPort === true;
-  // A negative answer here is acted on twice over: the caller walks past a proxy it was
-  // supposed to find, and the lines below delete this home's pid record and reconcile the
-  // journal. One 750ms probe is not enough evidence for either (#5004) — a transport
+  // A negative answer lets the caller walk past a proxy it was supposed to find and
+  // deletes this home's stale pid record. Journal recovery follows cross-home discovery.
+  // One 750ms probe is not enough evidence for that (#5004) — a transport
   // failure is indistinguishable from an empty port, and the reported Windows duplicate
   // came from exactly that answer on a proxy the previous command had just found healthy.
   const live = shouldProbe ? await findLiveProxy(START_OWNERSHIP_LIVENESS) : null;
   if (live) return { live, pidSnapshot };
 
-  // The probe established that the snapshotted owner is stale. Compare before
-  // deleting so a concurrent start that rewrote the PID file keeps its state.
   removePidIfValueIs(pidSnapshot);
-  // A marked sibling's owner can be down mid-restart; its journal is still not ours to replay.
-  if (!currentExternalCodexModelProvider() && siblingOfLivePort() === null) {
-    const clientState = readClientConnectionState();
-    reconcileJournal(clientState.kind === "connected"
-      ? { activeClientApiKeyId: clientState.value.apiKeyId }
-      : undefined);
-  }
   return { live: null, pidSnapshot };
 }
 
@@ -413,8 +404,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     }
   }
   const requestedPort = startOpts.port;
-  // Probe the configured port even without state files: a fallback sibling can remove them,
-  // and an unprobed start could shadow the owner and reroute Codex to a short-lived port.
+  // Probe the configured port even without state files: a fallback sibling can remove them.
   // Consume a sibling replacement's handoff before probing, even if its owner is momentarily down.
   let siblingStart = honorSiblingMarker(process.env, consumeSiblingHandoff) !== null;
   // A restart replacement waits out its draining parent instead of refusing it, and bounds its handoff log (restart-handoff.ts).
@@ -448,6 +438,8 @@ async function handleStart(options: { block?: boolean } = {}) {
       + `Startup continues only for an independent OPENCODEX_HOME; one state directory has one spend-ledger writer.`,
     );
   }
+  if (!owner.live && !siblingStart) siblingStart = await markCrossHomeSibling();
+  if (!siblingStart) reconcileStartupJournal();
 
   const clientState = readClientConnectionState();
   if (clientState.kind === "invalid" || clientState.kind === "mismatched") {
@@ -504,6 +496,7 @@ async function handleStart(options: { block?: boolean } = {}) {
           siblingStart = true;
           markSiblingStart(fencedLive.port);
         }
+        if (!fencedLive && !siblingStart) siblingStart = await markCrossHomeSibling();
 
         // Port selection is check-then-bind. The lease prevents every cooperating start or
         // updater from turning that check into a different ownership decision.
@@ -733,6 +726,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     // to explain it. Name the failure and the one command that repairs it.
     console.error(`⚠️  ${grokSyncFailureMessage(err)}`);
   }
+  console.log("Client startup work complete.");
   if (options.block ?? true) {
     setInterval(() => {}, 60_000);
     await new Promise<void>(() => {});
@@ -749,6 +743,9 @@ function detachedStartEnvironment(): NodeJS.ProcessEnv {
 
 async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Promise<boolean> {
   const owner = await findProxyOwnerBeforeJournalRecovery({ probeConfiguredPort: true });
+  if (!owner.live && !(await markCrossHomeSibling())) reconcileStartupJournal();
+  // A later ensure can find this home's sibling alive; the other port still owns shared clients.
+  if (owner.live) await markLiveHomeSibling(owner.live);
   const config = loadConfig();
   if (!codexAutoStartEnabled(config)) {
     console.log("Codex autostart is disabled.");
@@ -772,13 +769,13 @@ async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Prom
       // owns catalog refresh; ensure must not overwrite a working destination.
       // Ensure env file exists for already-running proxy (may have been deleted or pre-dates this feature).
       const systemEnv = await injectSystemEnv(live.port, config).catch(() => ({ injected: false }));
-      reportShellHookFailure(reconcileShellHook(systemEnv.injected));
+      if (siblingOfLivePort() === null) reportShellHookFailure(reconcileShellHook(systemEnv.injected));
       if (!systemEnv.injected) await syncClaudeAgentDefsAtProxyStartup(config, live.port);
       // Refresh the Grok Build fence too (same contract as start). live.hostname is the
       // hostname the running proxy actually bound — config.hostname may have drifted.
       // The reconciler re-reads immediately before each client-file mutation; only
       // the live proxy's observed bind host is safe to carry across this boundary.
-      await reconcileEnsureDesiredIntegrations(
+      if (siblingOfLivePort() === null) await reconcileEnsureDesiredIntegrations(
         live.port,
         { kind: "live", hostname: live.hostname },
       );
@@ -806,7 +803,7 @@ async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Prom
   // responds — align here too so `ocx ensure` never returns with a stale ON/OFF mismatch.
   // Persisted state is loaded inside each mutation after waitForProxy, so a
   // toggle while the child starts wins over the pre-spawn snapshot.
-  await reconcileEnsureDesiredIntegrations(port, { kind: "spawned" });
+  if (siblingOfLivePort() === null) await reconcileEnsureDesiredIntegrations(port, { kind: "spawned" });
   // Always sync the LIVE port: after a fallback-port start, config.port still names the
   // busy preferred port — syncing that would point Codex at a dead listener.
   const synced = await syncModelsToCodex(port).catch(e => {

package/src/cli/integrations.ts

@@ -126,7 +126,14 @@ export async function handleClaudeConfigCommand(argv: string[], deps: RuntimeApi
     }
     if (Object.keys(body).length === 0) throw new CliUsageError("at least one Claude setting is required", CLAUDE_USAGE);
     const result = await runtimeRequest("/api/claude-code", { method: "PUT", body: JSON.stringify(body) }, deps);
-    printData(result, wantsJson, ["Claude Code settings updated."]);
+    const warnings = (result as { warnings?: unknown }).warnings;
+    const retained = Array.isArray(warnings) && warnings.includes("shared_proxy_retained");
+    printData(result, wantsJson, [
+      "Claude Code settings updated.",
+      // The route kept the shared proxy env because Claude Desktop may still rely on it. Say so,
+      // or an operator who turned first-party off believes the local interception is gone.
+      ...(retained ? ["Warning: Claude Desktop still uses the shared proxy settings. Run `ocx claude desktop apply --gateway` to release them."] : []),
+    ]);
   });
 }
 

package/src/cli/models-runtime-subcommands.ts

@@ -18,6 +18,7 @@ export const MODELS_RUNTIME_SUBCOMMANDS = [
   "price",
   "set-price",
   "edit",
+  "set",
   "enable",
   "disable",
   "provider",

package/src/cli/models-runtime.ts

@@ -18,6 +18,7 @@ import { isValidProviderName } from "../config/provider-name";
 import { isValidModelDiscoveryModelId } from "../providers/model-discovery-limits";
 import { redactSecretString } from "../lib/redact";
 import type { ProviderCostOverlay } from "../types";
+import { resolveMatchedPrice } from "../usage/cost";
 import { MAX_COST4_RATE } from "../usage/expected-prices";
 import { isValidCost4Rate } from "../usage/user-cost-overlays";
 
@@ -30,6 +31,10 @@ const USAGE = `Usage:
       [--context-window <tokens|0>] [--modalities <text,image,audio|->]
       [--reasoning-efforts <none,minimal,low,medium,high,xhigh,max,ultra|->]
       [--default-reasoning-effort <level|->] [--json]
+  ocx models set <provider/model> [--context-window <tokens|0|->]
+      [--modalities <text,image,audio|->]
+      [--reasoning-efforts <none,minimal,low,medium,high,xhigh,max,ultra|"">|->]
+      [--default-reasoning-effort <level|->] [--reset] [--json]
   ocx models <enable|disable> <provider/model|native-model> [--native] [--json]
   ocx models provider <name> <on|off> [--json]
   ocx models selected <provider> [--set <id,id...>|--clear] [--json]
@@ -124,8 +129,12 @@ async function priceRequest(write: boolean, argv: string[], deps: RuntimeApiDeps
       if (!validPriceCost(stored)) throw new Error("Invalid model price response");
       cost = { ...stored };
     }
-    printData({ provider, modelId, cost }, wantsJson, [
-      cost === null ? `${selector}: automatic pricing` : `${selector}: ${JSON.stringify(cost)} USD per 1M tokens`,
+    // The API map owns manual overrides; bundled defaults remain derived rather
+    // than being persisted as overrides that would mask later catalog updates.
+    const effectiveCost = cost ?? resolveMatchedPrice(provider, modelId, undefined, [])?.cost4 ?? null;
+    printData({ provider, modelId, cost, effectiveCost }, wantsJson, [
+      effectiveCost === null ? `${selector}: automatic pricing (unknown)`
+        : `${selector}: ${JSON.stringify(effectiveCost)} USD per 1M tokens${cost === null ? " (automatic estimate)" : ""}`,
     ]);
     return;
   }
@@ -199,7 +208,7 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   if (displayName !== undefined) patch.displayName = displayName === "-" ? "" : displayName;
   if (contextRaw !== undefined) {
     const value = Number(contextRaw.replace(/[_,]/g, ""));
-    if (!Number.isInteger(value) || value < 0) throw new CliUsageError("--context-window must be an integer >= 0", USAGE);
+    if (!Number.isSafeInteger(value) || value < 0) throw new CliUsageError("--context-window must be a safe integer >= 0", USAGE);
     patch.contextWindow = value === 0 ? null : value;
   }
   if (modalitiesRaw !== undefined) patch.inputModalities = modalitiesRaw === "-" ? [] : csv(modalitiesRaw);
@@ -240,6 +249,98 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, [`Updated custom model ${id}.`]);
 }
 
+/**
+ * Per-model overrides on a routed row: the twin of `ocx models edit` for rows that already
+ * exist, rather than for a custom definition.
+ *
+ * Every option has a clear spelling instead of an empty-value sentinel, because the API treats
+ * `null` as "hand this fact back to the registry, the catalog and the provider default". That is
+ * a different intent from storing a value that merely looks blank, and collapsing the two is how
+ * an override outlives the data it was copied from.
+ */
+async function setModelSettings(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const selector = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  const reset = takeFlag(args, "--reset");
+  if (!selector) throw new CliUsageError("model selector is required", USAGE);
+  const contextRaw = takeOption(args, "--context-window");
+  const modalitiesRaw = takeOption(args, "--modalities");
+  const reasoningEffortsRaw = takeOption(args, "--reasoning-efforts");
+  const defaultEffortRaw = takeOption(args, "--default-reasoning-effort");
+  rejectArgs(args, USAGE);
+  const target = parseSelector(selector, false);
+  if (target.native) {
+    throw new CliUsageError(
+      "model settings address a routed model; use provider/model (the native openai lane has no per-model overrides)",
+      USAGE,
+    );
+  }
+  const patch: Record<string, unknown> = {};
+  if (contextRaw !== undefined) {
+    const raw = contextRaw.trim();
+    if (raw === "-") patch.contextWindow = null;
+    else {
+      const value = Number(raw.replace(/[_,]/g, ""));
+      if (!Number.isSafeInteger(value) || value < 0) {
+        throw new CliUsageError("--context-window must be a safe integer >= 0 (0 or - clears the override)", USAGE);
+      }
+      patch.contextWindow = value === 0 ? null : value;
+    }
+  }
+  if (modalitiesRaw !== undefined) {
+    // "-" is the one spelling that clears. A blank value or a blank member would otherwise
+    // become [] after CSV normalization, which the server also reads as "clear".
+    const trimmed = modalitiesRaw.trim();
+    if (trimmed === "-") patch.inputModalities = null;
+    else {
+      const members = trimmed.split(",").map(item => item.trim());
+      if (members.some(item => !["text", "image", "audio"].includes(item))) {
+        throw new CliUsageError("--modalities must list text, image or audio (comma-separated), or - to clear", USAGE);
+      }
+      patch.inputModalities = [...new Set(members)];
+    }
+  }
+  if (reasoningEffortsRaw !== undefined) {
+    // "-" restores inheritance by clearing the stored ladder (null); "" stores an explicit empty
+    // ladder, which is the "this model does not reason" override. Embedded blank CSV members
+    // (`low,,high`) are malformed and rejected rather than normalized away.
+    const trimmed = reasoningEffortsRaw.trim();
+    if (trimmed === "-") {
+      patch.reasoningEfforts = null;
+    } else if (trimmed === "") {
+      patch.reasoningEfforts = [];
+    } else {
+      const values = trimmed.split(",").map(value => value.trim());
+      if (values.some(value => value === "")) {
+        throw new CliUsageError("--reasoning-efforts must be comma-separated values from none, minimal, low, medium, high, xhigh, max, ultra (\"\" for no reasoning, \"-\" to inherit)", USAGE);
+      }
+      patch.reasoningEfforts = values;
+    }
+  }
+  if (defaultEffortRaw !== undefined) patch.defaultReasoningEffort = defaultEffortRaw.trim() === "-" ? null : defaultEffortRaw.trim();
+  if (reset) {
+    if (Object.keys(patch).length > 0) {
+      throw new CliUsageError("--reset clears every override and cannot be combined with other options", USAGE);
+    }
+    for (const key of ["contextWindow", "inputModalities", "reasoningEfforts", "defaultReasoningEffort"]) patch[key] = null;
+  }
+  if (Object.keys(patch).length === 0) throw new CliUsageError("at least one setting or --reset is required", USAGE);
+  const result = await runtimeRequest<{ changed?: boolean; hasOverrides?: boolean; saved?: boolean; catalogRefresh?: { status?: string; retryable?: boolean } }>("/api/model-settings", {
+    method: "PUT",
+    body: JSON.stringify({ provider: target.provider, modelId: target.id, ...patch }),
+  }, deps);
+  const message = result?.changed === false
+    ? (reset && result.hasOverrides === false ? "Nothing to restore for " + selector + "." : "No settings changed for " + selector + ".")
+    : "Updated model settings for " + selector + ".";
+  printData(result, wantsJson, [message,
+    // A non-retryable skip means there is no managed Codex catalog to refresh, which is normal.
+    ...(result?.saved && (result.catalogRefresh?.status === "failed"
+      || (result.catalogRefresh?.status === "skipped" && result.catalogRefresh.retryable === true))
+      ? ["Settings saved, but the Codex model catalog did not refresh. Run `ocx sync` so Codex picks up the change."] : []),
+  ]);
+}
+
 function parseSelector(selector: string, forceNative: boolean): { provider: string; id: string; native: boolean } {
   if (forceNative || !selector.includes("/")) return { provider: "openai", id: selector, native: true };
   const slash = selector.indexOf("/");
@@ -410,7 +511,7 @@ async function context(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     const raw = args.shift();
     if (!raw) throw new CliUsageError("context value is required", USAGE);
     const value = Number(raw.replace(/[_,]/g, ""));
-    if (!Number.isInteger(value) || value <= 0) throw new CliUsageError("context value must be a positive integer", USAGE);
+    if (!Number.isSafeInteger(value) || value <= 0) throw new CliUsageError("context value must be a positive safe integer", USAGE);
     body = { value };
     // Explicit apply-to-all switch for headless use: re-points every routed provider to
     // the new value, mirroring the dashboard's "apply to every routed provider" toggle.
@@ -470,6 +571,7 @@ export async function handleModelsRuntimeCommand(sub: string, argv: string[], de
   else if (sub === "price") action = () => price(false, argv, deps);
   else if (sub === "set-price") action = () => price(true, argv, deps);
   else if (sub === "edit") action = () => edit(argv, deps);
+  else if (sub === "set") action = () => setModelSettings(argv, deps);
   else if (sub === "enable") action = () => visibility(true, argv, deps);
   else if (sub === "disable") action = () => visibility(false, argv, deps);
   else if (sub === "provider") action = () => providerVisibility(argv, deps);

package/src/cli/models.ts

@@ -1,6 +1,7 @@
 /**
  * `ocx models` subcommand — list configured models and manage custom models.
  */
+import { resolveMatchedPrice, type MatchedPrice } from "../usage/cost";
 import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline/promises";
 import { syncModelsToCodex } from "../codex/sync";
@@ -85,6 +86,7 @@ interface ModelEntry {
   contextWindow: number | null;
   inputModalities: string[] | null;
   reasoningEfforts: string[] | null;
+  price: MatchedPrice | null;
 }
 
 /**
@@ -132,6 +134,7 @@ function collectModels(config: OcxConfig, providerFilter?: string): ModelEntry[]
         contextWindow: configuredContextWindow(prov, model) ?? null,
         inputModalities: modalities,
         reasoningEfforts: efforts,
+        price: resolveMatchedPrice(provName, model),
       });
     };
 
@@ -428,7 +431,9 @@ function handleConfiguredModels(args: string[]): void {
     for (const m of provModels) {
       const marker = m.isDefault ? " *" : "";
       const ctx = m.contextWindow ? ` (${Math.round(m.contextWindow / 1000)}k)` : "";
-      console.log(`  ${m.model}${marker}${ctx}`);
+      const rates = m.price?.cost4;
+      const pricing = rates ? ` ~$${rates.input}/$${rates.output} input/output per 1M tokens` : " price unknown";
+      console.log(`  ${m.model}${marker}${ctx}${pricing}`);
     }
     console.log();
   }