@yansigit/opencodex 2.31.3 → 2.33.0

package/src/cli/observe.ts

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

package/src/cli/provider.ts

@@ -8,7 +8,8 @@
  *   show <name>   Show provider config details (secrets masked)
  *   set-default <name>  Change the default provider
  */
-import { apiKeyTransportConfigError, hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
+import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
+import { apiKeyTransportConfigError } from "../config/provider-validation";
 import { hasHelpFlag } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
 import { providerConfigSeed } from "../providers/derive";
@@ -359,6 +360,12 @@ function handleShow(args: string[]): void {
     ...(prov.modelCosts !== undefined ? { modelCosts: sanitizeModelCostsForDisplay(prov.modelCosts) } : {}),
     ...(prov.apiKey ? { apiKey: maskSecret(prov.apiKey) } : {}),
     ...(prov.apiKeyPool ? { apiKeyPool: prov.apiKeyPool.map(e => ({ ...e, key: maskSecret(e.key) })) } : {}),
+    ...(prov.azureCredential ? {
+      azureCredential: {
+        type: prov.azureCredential.type,
+        hasManagedIdentityClientId: Boolean(prov.azureCredential.managedIdentityClientId?.trim()),
+      },
+    } : {}),
   };
 
   if (wantsJson) {

package/src/cli/registry.ts

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

package/src/cli/status.ts

@@ -1,5 +1,6 @@
 import { durableBunRuntime } from "../lib/bun-runtime";
-import { codexAutoStartEnabled, getConfigPath, getPidPath, readConfigDiagnostics, readPid, readRuntimePort, type RuntimePortState } from "../config";
+import { codexAutoStartEnabled, getConfigPath, readConfigDiagnostics } from "../config";
+import { getPidPath, readPid, readRuntimePort, type RuntimePortState } from "../config/process-state";
 import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../codex/plugins-doctor";
 import { findLiveProxy, isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";
@@ -117,6 +118,29 @@ export function proxyHealthFailureReason(error: unknown, signal: AbortSignal): "
     : "unreachable";
 }
 
+/**
+ * `ocx status` greens on process liveness alone, so a proxy that answers
+ * /healthz reads healthy even when Codex is not pointed at it and every routed
+ * request goes to OpenAI instead (#2411). The proxy line is not wrong — the
+ * listener really is up — so it keeps its check, and this supplies the signal
+ * that was missing rather than corrupting the one that was already honest.
+ *
+ * Only `native` warns. `custom-local` and `unknown` are also "this proxy is
+ * unused", but startupHealthSummary already renders both as AT RISK with a
+ * remedy command, and `custom-remote` is a deliberate operator choice. Warning
+ * on all four would teach operators to skip the line that matters.
+ */
+export function unusedProxyWarningLines(input: {
+  proxyUp: boolean;
+  routingKind: StartupHealth["routingKind"];
+}): string[] {
+  if (!input.proxyUp || input.routingKind !== "native") return [];
+  return [
+    "⚠️  Codex routing is native — the running proxy is unused.",
+    "   Codex requests go to OpenAI, not this proxy. Re-point with: ocx start",
+  ];
+}
+
 async function checkProxyHealth(target: ListenTarget): Promise<HealthCheck> {
   const url = target.healthUrl;
   const controller = new AbortController();

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

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

package/src/cli/usage-report.ts

@@ -0,0 +1,134 @@
+/**
+ * Human rendering for `ocx usage`.
+ *
+ * Kept out of `observe.ts` and away from the shared `summaryLines()` helper on
+ * purpose. `summaryLines()` is a generic depth-1 flattener shared with
+ * storage/memory/debug/claude-inbound/injection; it renders any array as
+ * "N item(s)", which is why every per-model and per-provider cost the server
+ * computes used to vanish before reaching the terminal. Deepening it would
+ * change five unrelated commands.
+ *
+ * Formatting follows the existing CLI house style: dynamic `padEnd` columns
+ * (as in `formatAccountTable`), plain text, no ANSI colour.
+ */
+
+interface CostRow {
+  provider: string;
+  model?: string;
+  requests: number;
+  totalTokens: number;
+  estimatedCostUsd?: number;
+}
+
+interface UsageReportInput {
+  range?: string;
+  surface?: string;
+  since?: number | null;
+  summary?: {
+    requests?: number;
+    totalTokens?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    estimatedCostUsd?: number;
+    unpricedRequests?: number;
+    unmeteredRequests?: number;
+  };
+  models?: CostRow[];
+  providers?: CostRow[];
+  days?: { date: string; requests: number; totalTokens: number; estimatedCostUsd?: number }[];
+  filter?: { provider: string | null; model: string | null; matched: boolean; comboOverlap: boolean };
+}
+
+const MAX_MODEL_ROWS = 10;
+
+function count(value: number | undefined): string {
+  return (value ?? 0).toLocaleString("en-US");
+}
+
+/**
+ * Matches the dashboard's `~$` with four fraction digits. Estimates below a
+ * hundredth of a cent still read as a number rather than collapsing to $0.00,
+ * which matters when a single request is being inspected.
+ */
+function usd(value: number | undefined): string {
+  if (typeof value !== "number" || !Number.isFinite(value)) return "—";
+  return `~$${value.toFixed(4)}`;
+}
+
+function table(header: string[], rows: string[][]): string[] {
+  if (rows.length === 0) return [];
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map(r => (r[i] ?? "").length)));
+  const line = (cols: string[]): string => cols.map((c, i) => (c ?? "").padEnd(widths[i]!)).join("  ").trimEnd();
+  return [line(header), ...rows.map(line)];
+}
+
+function describeScope(data: UsageReportInput): string {
+  const parts = [`Usage — ${data.range ?? "?"}`];
+  if (data.surface && data.surface !== "all") parts.push(`surface=${data.surface}`);
+  if (data.filter?.provider) parts.push(`provider=${data.filter.provider}`);
+  if (data.filter?.model) parts.push(`model=${data.filter.model}`);
+  return parts.join(", ");
+}
+
+export function formatUsageReport(data: UsageReportInput): string[] {
+  const summary = data.summary ?? {};
+  const lines: string[] = [describeScope(data), ""];
+
+  if (data.filter && !data.filter.matched) {
+    const what = [data.filter.provider && `provider "${data.filter.provider}"`, data.filter.model && `model "${data.filter.model}"`]
+      .filter(Boolean).join(" and ");
+    lines.push(`No usage recorded for ${what} in this range.`);
+    lines.push("Check the spelling against `ocx usage --json`, or widen --range.");
+    return lines;
+  }
+
+  const tokenSplit = [
+    summary.inputTokens !== undefined ? `in ${count(summary.inputTokens)}` : null,
+    summary.outputTokens !== undefined ? `out ${count(summary.outputTokens)}` : null,
+    summary.cachedInputTokens ? `cached ${count(summary.cachedInputTokens)}` : null,
+  ].filter(Boolean).join(" / ");
+
+  lines.push(`Requests   ${count(summary.requests)}`);
+  lines.push(`Tokens     ${count(summary.totalTokens)}${tokenSplit ? `  (${tokenSplit})` : ""}`);
+  lines.push(`Est. cost  ${usd(summary.estimatedCostUsd)}    API list-price equivalent (this range)`);
+
+  const unpriced = summary.unpricedRequests ?? 0;
+  const unmetered = summary.unmeteredRequests ?? 0;
+  if (unpriced > 0 || unmetered > 0) {
+    // Spelled out because a $0 total is ambiguous otherwise: it can mean "no
+    // spend" or "no price row matched", and those are very different answers.
+    lines.push(`           ${count(unpriced)} unpriced, ${count(unmetered)} unmetered excluded from ~$`);
+  }
+
+  const providers = (data.providers ?? []).filter(row => row.requests > 0);
+  if (providers.length > 0) {
+    lines.push("");
+    lines.push(...table(
+      ["PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
+      providers.map(row => [row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),
+    ));
+  }
+
+  const models = (data.models ?? []).filter(row => row.requests > 0);
+  if (models.length > 0) {
+    lines.push("");
+    const shown = models.slice(0, MAX_MODEL_ROWS);
+    lines.push(...table(
+      ["MODEL", "PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
+      shown.map(row => [row.model ?? "-", row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),
+    ));
+    if (models.length > shown.length) {
+      lines.push(`... ${models.length - shown.length} more (use --json)`);
+    }
+  }
+
+  if (data.filter?.comboOverlap) {
+    lines.push("");
+    lines.push("Some requests ran as combos, so per-model request counts can overlap. Cost does not.");
+  }
+
+  lines.push("");
+  lines.push("Not a billing receipt. Subscription usage or provider credits may apply instead.");
+  return lines;
+}

package/src/codex/app-server-processes.ts

@@ -17,7 +17,8 @@ import {
 import { readCodexCatalogPath } from "./catalog/parsing";
 
 export const STALE_CODEX_APP_SERVER_HINT =
-  "If Codex still shows an older model list, restart its long-lived app-server process after sync (ocx sync --restart-codex).";
+  "If Codex still shows an older model list, restart its long-lived app-server process after sync (ocx sync --restart-codex). "
+  + "On Windows the desktop app itself may also need a full restart (ocx sync --restart-desktop-app).";
 
 /** Attach the shared dashboard hint only after a catalog or models_cache write. */
 export function attachStaleAppServerHint<T extends {
@@ -505,6 +506,7 @@ export function formatStaleCodexAppServerWarning(
     `WARNING: ${processes.length} Codex app-server process(es) still running (PID${processes.length === 1 ? "" : "s"}: ${pids}). `
     + "Disk catalog/cache were updated, but Codex may keep showing the old model list until those processes restart. "
     + "Re-run with `ocx sync --restart-codex` (or `ocx sync-cache --restart-codex`) to send SIGTERM only to matching app-server processes. "
+    + "On Windows the desktop app itself may also need a full restart (`ocx sync --restart-desktop-app`). "
     + "Active turns may be interrupted."
   );
 }

package/src/codex/auth-api.ts

@@ -1806,7 +1806,7 @@ export async function handleCodexAuthAPI(
   }
 
   if (url.pathname === "/api/codex-auth/login" && req.method === "POST") {
-    const body = (await req.json().catch(() => ({}))) as { id?: string; reauth?: boolean };
+    const body = (await req.json().catch(() => ({}))) as { id?: string; reauth?: boolean; openBrowser?: unknown };
     const requestedAccountId = body.id?.trim();
     const reauth = body.reauth === true;
     if (requestedAccountId && !isValidCodexAccountId(requestedAccountId)) {
@@ -1840,7 +1840,9 @@ export async function handleCodexAuthAPI(
 
       // Open the browser server-side (same pattern as /api/oauth/login in management-api.ts).
       // The GUI's window.open is popup-blocked because it runs after an await, not a direct click.
-      if (result.url) {
+      // Both login routes share one resolver so this surface cannot drift from the other.
+      const { shouldOpenBrowserForLogin } = await import("../oauth/open-browser-choice");
+      if (result.url && shouldOpenBrowserForLogin(body.openBrowser, runtimeConfig)) {
         const { openUrl } = await import("../lib/open-url");
         openUrl(result.url);
       }

package/src/codex/autostart-health.ts

@@ -154,3 +154,19 @@ export function startupHealthSummary(health: StartupHealth): string {
   if (health.serviceInstalled && !health.serviceViable) return `AT RISK after restart (installed service is disabled, stopped, or unhealthy; run '${command}')`;
   return `AT RISK after restart (no viable background service; run '${command}')`;
 }
+
+/**
+ * The routing/service/shim token `ocx doctor` prints under restart safety.
+ * Extracted so `ocx status` can show the same string rather than growing a
+ * second copy that drifts (#2411). Two management routes computing the same
+ * thing separately is exactly how #2457 happened.
+ */
+export function formatStartupRoutingDetail(health: StartupHealth): string {
+  const service = health.serviceViable
+    ? "viable"
+    : health.serviceInstalled ? "installed-but-unhealthy" : "absent";
+  const shim = health.shimHealthy
+    ? "healthy"
+    : health.shimInstalled ? "stale" : "absent";
+  return `routing=${health.routingKind}, service=${service}, shim=${shim}`;
+}

package/src/codex/catalog/aggregation.ts

@@ -13,6 +13,7 @@ import { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, r
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
 import { getProviderRegistryEntry } from "../../providers/registry";
 import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap";
+import { clampAutoCompactTokenLimit } from "../../providers/auto-compact-budget";
 import { routedSlug, slugEquals, slugEquivalenceKey, slugsEquivalent } from "../../providers/slug-codec";
 import { CODEX_GPT5_IDENTITY_LINE } from "../../adapters/identity";
 import { filterCursorConfiguredModelsByLiveDiscovery } from "../../adapters/cursor/discovery";
@@ -154,8 +155,16 @@ export function deriveComboCatalogModel(
   // combo would have the same window even without the cap.
   const contextCapped = limitingMembers.every(member => member.contextCapped === true);
   const maxInputTokens = Math.min(
+    contextWindow,
     ...members.map(member => member.maxInputTokens ?? member.contextWindow!),
   );
+  const autoCompactTokenLimit = Math.min(
+    ...members.map(member => clampAutoCompactTokenLimit(
+      member.contextWindow!,
+      member.maxInputTokens,
+      member.autoCompactTokenLimit,
+    )),
+  );
   const defaultReasoningEffort = effectiveComboDefault(
     combo.defaultEffort,
     reasoningEfforts,
@@ -167,6 +176,7 @@ export function deriveComboCatalogModel(
     owned_by: COMBO_NAMESPACE,
     contextWindow,
     maxInputTokens,
+    autoCompactTokenLimit,
     ...(hasLimitingContextCapMetadata ? { contextCapped } : {}),
     inputModalities,
     reasoningEfforts,
@@ -210,6 +220,7 @@ export function comboCatalogWarningSignature(
       key,
       contextWindow: member?.contextWindow ?? null,
       maxInputTokens: member?.maxInputTokens ?? null,
+      autoCompactTokenLimit: member?.autoCompactTokenLimit ?? null,
       inputModalities: [...new Set(member?.inputModalities ?? [])].sort(),
       reasoningEfforts: [...new Set(member?.reasoningEfforts ?? [])].sort(),
       parallelToolCalls: member?.parallelToolCalls === true,
@@ -299,6 +310,7 @@ export function normalizedOpenAiApiSignature(model: CatalogModel): string {
     id: model.id,
     contextWindow: model.contextWindow ?? null,
     maxInputTokens: model.maxInputTokens ?? null,
+    autoCompactTokenLimit: model.autoCompactTokenLimit ?? null,
     inputModalities: [...new Set(model.inputModalities ?? [])].sort(),
     reasoningEfforts: [...new Set(model.reasoningEfforts ?? [])].sort(),
     ownedBy: model.owned_by ?? null,

package/src/codex/catalog/effort.ts

@@ -13,6 +13,7 @@ import { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, r
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
 import { getProviderRegistryEntry } from "../../providers/registry";
 import { applyProviderContextCap, providerContextCap, resolveUnknownRoutedContextWindow } from "../../providers/context-cap";
+import { clampAutoCompactTokenLimit } from "../../providers/auto-compact-budget";
 import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec";
 import { CODEX_GPT5_IDENTITY_LINE } from "../../adapters/identity";
 import { filterCursorConfiguredModelsByLiveDiscovery } from "../../adapters/cursor/discovery";
@@ -33,6 +34,7 @@ import upstreamModelsSnapshot from "../data/upstream-models.json";
 
 import { generatedModelMetadata, readCatalog, readCodexCatalogPath } from "./parsing";
 import type { CatalogModel, RawEntry } from "./parsing";
+import { shouldStampContextProvenance } from "./model-metadata";
 import { UPSTREAM_NATIVE_ENTRIES } from "./metadata";
 import { nativeOpenAiCapabilitySourceSlug } from "./native-models";
 import { loadBundledCodexCatalog } from "./bundled";
@@ -128,9 +130,23 @@ export function applyCatalogModelMetadata(entry: RawEntry, model?: CatalogModel)
   if (typeof resolvedContext === "number" && resolvedContext > 0) {
     entry.context_window = resolvedContext;
     entry.max_context_window = resolvedContext;
-    entry.auto_compact_token_limit = Math.min(
-      Math.floor(resolvedContext * 0.9),
-      model.maxInputTokens ?? Number.POSITIVE_INFINITY,
+    entry.auto_compact_token_limit = clampAutoCompactTokenLimit(
+      resolvedContext,
+      model.maxInputTokens,
+      model.autoCompactTokenLimit,
+    );
+  } else if (
+    typeof entry.context_window === "number"
+    && entry.context_window > 0
+    && typeof model.maxInputTokens === "number"
+    && model.maxInputTokens > 0
+  ) {
+    // A conservative routed fallback is not evidence for applying the optional soft policy,
+    // but a measured/configured input ceiling is still a hard bound. Compact before that
+    // ceiling even when the provider supplied no authoritative context window.
+    entry.auto_compact_token_limit = clampAutoCompactTokenLimit(
+      entry.context_window,
+      model.maxInputTokens,
     );
   }
   if (Array.isArray(model.inputModalities) && model.inputModalities.length > 0) {
@@ -171,33 +187,47 @@ export function applyCatalogModelMetadata(entry: RawEntry, model?: CatalogModel)
  * live in that table.
  */
 function stampCapabilityProvenance(entry: RawEntry, model: CatalogModel): void {
-  // Virtual combo rows are synthesized from last-resort defaults (a generic 128k
-  // context and a `["text"]` modality), so their values are placeholders rather
-  // than assertions. Stamping them would reintroduce the exact false-evidence
-  // defect this block exists to prevent.
-  if (model.provider === COMBO_NAMESPACE) return;
+  // Virtual combo rows without derived member evidence are placeholders
+  // (generic 128k / `["text"]`). Stamping those would reintroduce the
+  // false-evidence defect this block exists to prevent. Combos that actually
+  // min() real member windows carry `metadataSource: "derived"`.
+  if (model.provider === COMBO_NAMESPACE && model.metadataSource !== "derived") return;
 
   const meta = generatedModelMetadata(model.provider, model.id);
   const metaContext = typeof meta?.contextWindow === "number" && meta.contextWindow > 0
-    // The generated context is capped before it reaches the entry, so provenance
-    // must apply the same cap or routing would advertise a window the cap refused.
     ? applyProviderContextCap(meta.contextWindow, model.contextCap) ?? meta.contextWindow
     : undefined;
-  const contextWindow = typeof model.contextWindow === "number" && model.contextWindow > 0
+  const stampModelContext = shouldStampContextProvenance(model);
+  const contextWindow = stampModelContext
     ? model.contextWindow
-    : metaContext;
+    : (model.metadataSource === undefined ? metaContext : undefined);
   const inputModalities = Array.isArray(model.inputModalities) && model.inputModalities.length > 0
     ? model.inputModalities
     : (Array.isArray(meta?.input) && meta.input.length > 0 ? meta.input : undefined);
+  const maxInputTokens = typeof model.maxInputTokens === "number" && model.maxInputTokens > 0
+    ? model.maxInputTokens
+    : undefined;
+  const source = model.metadataSource;
+  const stampSource = source === "live" || source === "registry" || source === "snapshot" || source === "derived";
+
+  if (contextWindow === undefined && inputModalities === undefined
+    && !(Array.isArray(model.capabilities) && model.capabilities.length > 0)) {
+    return;
+  }
 
   entry.opencodex_capability_provenance = {
     provider: model.provider,
     model_id: model.id,
     ...(contextWindow !== undefined ? { context_window: contextWindow } : {}),
+    ...(maxInputTokens !== undefined && stampModelContext ? { max_input_tokens: maxInputTokens } : {}),
     ...(inputModalities !== undefined ? { input_modalities: [...inputModalities] } : {}),
     ...(Array.isArray(model.capabilities) && model.capabilities.length > 0
       ? { capabilities: [...model.capabilities] }
       : {}),
+    ...(stampSource ? { source } : {}),
+    ...(typeof model.metadataObservedAt === "string" && stampSource
+      ? { observed_at: model.metadataObservedAt }
+      : {}),
   };
 }
 

package/src/codex/catalog/metadata.ts

@@ -14,6 +14,7 @@ import { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, r
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
 import { getProviderRegistryEntry, providerCodexAccountMode } from "../../providers/registry";
 import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap";
+import { clampAutoCompactTokenLimit } from "../../providers/auto-compact-budget";
 import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec";
 import { identifyRoutedModel } from "../../adapters/identity";
 import { filterCursorConfiguredModelsByLiveDiscovery } from "../../adapters/cursor/discovery";
@@ -204,6 +205,8 @@ export interface NativeContextLimits {
   readonly providerWindow?: number;
   /** `providers.openai.modelContextWindows` — per-model, wins over `providerWindow`. */
   readonly modelWindows?: Readonly<Record<string, number>>;
+  /** `providers.openai.modelAutoCompactTokenLimits` — soft, lowering-only budgets. */
+  readonly modelAutoCompactTokenLimits?: Readonly<Record<string, number>>;
 }
 
 export type NativeContextLimitsInput = NativeContextLimits | number | undefined;
@@ -227,12 +230,18 @@ export function nativeContextLimits(
     const window = positiveInt(value);
     if (window !== undefined) modelWindows[slug] = window;
   }
+  const modelAutoCompactTokenLimits: Record<string, number> = {};
+  for (const [slug, value] of Object.entries(provider?.modelAutoCompactTokenLimits ?? {})) {
+    const budget = positiveInt(value);
+    if (budget !== undefined) modelAutoCompactTokenLimits[slug] = budget;
+  }
   return {
     ...(positiveInt(providerContextCap(config, OPENAI_CODEX_PROVIDER_ID)) !== undefined
       ? { cap: providerContextCap(config, OPENAI_CODEX_PROVIDER_ID) }
       : {}),
     ...(positiveInt(provider?.contextWindow) !== undefined ? { providerWindow: provider!.contextWindow } : {}),
     ...(Object.keys(modelWindows).length > 0 ? { modelWindows } : {}),
+    ...(Object.keys(modelAutoCompactTokenLimits).length > 0 ? { modelAutoCompactTokenLimits } : {}),
   };
 }
 
@@ -277,6 +286,21 @@ export function nativeOpenAiMaxInputTokens(slug: string, limits?: NativeContextL
   return window === undefined ? narrowed : Math.min(narrowed, window);
 }
 
+/** Effective native soft budget after every hard window/input limit is resolved. */
+export function nativeOpenAiAutoCompactTokenLimit(
+  slug: string,
+  limits?: NativeContextLimitsInput,
+): number | undefined {
+  const contextWindow = nativeOpenAiContextWindow(slug, limits);
+  if (contextWindow === undefined) return undefined;
+  const configured = positiveInt(asLimits(limits).modelAutoCompactTokenLimits?.[slug]);
+  return clampAutoCompactTokenLimit(
+    contextWindow,
+    nativeOpenAiMaxInputTokens(slug, limits),
+    configured,
+  );
+}
+
 export function nativeInputModalities(slug: string): string[] {
   const upstream = PINNED_NATIVE_CAPABILITY_ENTRIES.get(slug);
   if (Array.isArray(upstream?.input_modalities) && upstream!.input_modalities!.length > 0) {
@@ -387,7 +411,7 @@ export function desktopVisibleNativeSlugs(
   ]);
 }
 
-export function nativeModelRows(config: Pick<OcxConfig, "disabledModels" | "combos" | "providerContextCaps" | "providers">): Array<{ slug: string; disabled: boolean; contextWindow?: number; maxInputTokens?: number }> {
+export function nativeModelRows(config: Pick<OcxConfig, "disabledModels" | "combos" | "providerContextCaps" | "providers">): Array<{ slug: string; disabled: boolean; contextWindow?: number; maxInputTokens?: number; autoCompactTokenLimit?: number }> {
   const disabled = disabledNativeSlugs(config);
   const shadowed = configuredNativeAliasSlugs(config);
   // Both user levers, not just the cap: a per-model window set from the dashboard has to show
@@ -403,11 +427,13 @@ export function nativeModelRows(config: Pick<OcxConfig, "disabledModels" | "comb
     .filter(slug => !shadowed.has(slug)).map(slug => {
     const contextWindow = nativeOpenAiContextWindow(slug, limits);
     const maxInputTokens = nativeOpenAiMaxInputTokens(slug, limits);
+    const autoCompactTokenLimit = nativeOpenAiAutoCompactTokenLimit(slug, limits);
     return {
       slug,
       disabled: disabled.has(slug),
       ...(contextWindow !== undefined ? { contextWindow } : {}),
       ...(maxInputTokens !== undefined ? { maxInputTokens } : {}),
+      ...(autoCompactTokenLimit !== undefined ? { autoCompactTokenLimit } : {}),
     };
   });
 }