@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/codex/catalog/sync.ts

@@ -1,3 +1,5 @@
+import { effectiveProviderAlias } from "../../providers/default-aliases";
+import { pendingModelSelectionProviders } from "../../providers/initial-model-selection";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
@@ -73,7 +75,15 @@ import {
 } from "../internal/catalog-writer";
 import { codexRuntimeStatePath } from "../runtime";
 import { accountBoundNativeDisplayName, CODEX_ACCOUNT_BOUND_CATALOG_KIND, trustedAccountBoundNativeCatalogSlug, visibleCodexAccountSelectors } from "./account-models";
-import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./native-models";
+import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_RESERVE_MODEL } from "./native-models";
+import { observedReserveCatalogSource } from "./metadata";
+import {
+  createReserveCatalogProjection,
+  isReserveCatalogProjection,
+  RESERVE_LUNA_METADATA_SOURCE,
+  RESERVE_SOURCE_CATALOG_FIELD,
+  type ReserveCatalogProjection,
+} from "./reserve";
 
 export const MAX_SPAWN_AGENT_MODEL_OVERRIDES = 5;
 
@@ -267,17 +277,30 @@ function isExactComboCatalogEntry(
  * ids differ by a single dash (`command-code` vs `commandcode`), so relabel them to the
  * lowercase-dash style the opencode presets use: `commandcode-auth/x` and `commandcode-api/x`.
  * The model-id portion also carries a redundant `<vendor>-` prefix (`deepseek-deepseek-v4-flash`)
- * that is dropped for display. All other providers keep the raw slug exactly as before.
+ * that is dropped for display. Google Antigravity is relabeled to the compact `agy/` prefix for
+ * the same reason: `google-antigravity/` alone consumes most of the picker row. That prefix comes
+ * from the row's own `providerAlias`, decided once per gather flight; `null` means a cross-provider
+ * collision suppressed it and the canonical slug stands. This is the raw-slug path only -- a
+ * configured `modelAliases` entry is labeled by the effective-alias path in
+ * catalog/provider-fetch.ts (#2960) and keeps the canonical provider name. All other providers
+ * keep the raw slug exactly as before.
  */
-function routedDisplayName(slug: string): string {
+function routedDisplayName(slug: string, model?: CatalogModel, config?: Pick<OcxConfig, "providers">): string {
   const slash = slug.indexOf("/");
   if (slash <= 0) return slug;
   const provider = slug.slice(0, slash);
-  let model = slug.slice(slash + 1);
+  let modelId = slug.slice(slash + 1);
+  if (provider === "google-antigravity") {
+    if (model?.providerAlias === null) return slug;
+    const alias = (typeof model?.providerAlias === "string" && model.providerAlias.trim().length > 0)
+      ? model.providerAlias.trim()
+      : effectiveProviderAlias(provider, undefined, config);
+    return alias ? `${alias}/${modelId}` : slug;
+  }
   if (provider === "command-code" || provider === "commandcode") {
-    const m = model.match(/^([a-z0-9]+)-([a-z0-9]+(?:-[a-z0-9]+)+)$/i);
-    if (m && model.startsWith(`${m[1]}-${m[1]}-`)) model = model.slice(m[1]!.length + 1);
-    return `${provider === "command-code" ? "commandcode-auth" : "commandcode-api"}/${model}`;
+    const m = modelId.match(/^([a-z0-9]+)-([a-z0-9]+(?:-[a-z0-9]+)+)$/i);
+    if (m && modelId.startsWith(`${m[1]}-${m[1]}-`)) modelId = modelId.slice(m[1]!.length + 1);
+    return `${provider === "command-code" ? "commandcode-auth" : "commandcode-api"}/${modelId}`;
   }
   return slug;
 }
@@ -306,7 +329,7 @@ export function deriveEntry(
   if (template || codexForwardNativeCapabilityAlias) {
     const e = JSON.parse(JSON.stringify(codexForwardNativeCapabilityAlias ?? template)) as RawEntry;
     e.slug = slug;
-    e.display_name = routedDisplayName(slug);
+    e.display_name = routedDisplayName(slug, model);
     e.description = desc;
     e.priority = priority;
     e.visibility = "list";
@@ -375,7 +398,7 @@ export function deriveEntry(
   // Cursor still omits hosted web-search metadata because runTurn bypasses that separate sidecar.
   const isCursorFallback = isRouted && model?.provider === "cursor";
   const entry: RawEntry = {
-    slug, display_name: routedDisplayName(slug), description: desc,
+    slug, display_name: routedDisplayName(slug, model), description: desc,
     shell_type: "unified_exec", visibility: "list", supported_in_api: true,
     priority, base_instructions: "You are a helpful coding assistant.",
     ...(isRouted
@@ -422,6 +445,8 @@ export interface ObservedCatalogEntryBuildInput {
   readonly accountNativeSlugs?: readonly string[];
   /** Per-selector account ids; unknown observations must not be copied to unrelated accounts. */
   readonly accountNativeSlugsBySelector?: ReadonlyMap<string, readonly string[]>;
+  /** Codex-only manual selector metadata; deliberately independent of live permission. */
+  readonly reserve?: ReserveCatalogProjection;
 }
 
 /** Build entries with the process-observed Codex feature state. */
@@ -478,6 +503,7 @@ export function buildCatalogEntriesFromObservedState({
   openaiContextCap,
   accountNativeSlugs,
   accountNativeSlugsBySelector,
+  reserve,
 }: ObservedCatalogEntryBuildInput): RawEntry[] {
   // Codex's models-manager sorts by `priority` ASC and advertises the first 5 picker-visible
   // models to spawn_agent (sort_by_key(priority) + MAX_MODEL_OVERRIDES_IN_SPAWN_AGENT=5). Catalog
@@ -574,15 +600,17 @@ export function buildCatalogEntriesFromObservedState({
     const selectorNativeSlugs = accountNativeSlugsBySelector?.get(selector)
       ?? accountNativeSlugs
       ?? gptSlugs;
-    const accountNativeEntries = selectorNativeSlugs.map(slug => (
+    const accountNativeEntries = selectorNativeSlugs.filter(slug => slug !== NATIVE_RESERVE_MODEL).map(slug => (
       nativeEntriesBySlug.get(slug)
         ?? deriveEntry(template, slug, "OpenAI native model (Codex OAuth passthrough).", 9, undefined, new Set(), openaiContextCap)
     ));
+    if (reserve?.mainSelectors.includes(selector)) accountNativeEntries.push(reserve.source);
     for (const [nativeIndex, native] of accountNativeEntries.entries()) {
       const nativeSlug = String(native.slug);
       if (disabledNativeAccountSlugs.has(nativeSlug)) continue;
       const e = JSON.parse(JSON.stringify(native)) as RawEntry;
       const catalogSlug = `${selector}/${nativeSlug}`;
+      if (nativeSlug === NATIVE_RESERVE_MODEL && disabledNativeAccountSlugs.has(catalogSlug)) continue;
       e.slug = catalogSlug;
       e.display_name = accountBoundNativeDisplayName(selector, native);
       // Codex ignores this OpenCodex extension; preserve the native comp_hash unchanged.
@@ -656,6 +684,7 @@ export function buildCatalogEntriesFromObservedState({
   }
   return applyMultiAgentMode(out, multiAgentMode, multiAgentV2Enabled, {
     keepNativeChatGptOnV1,
+    preserveDefaultMultiAgentVersion: isReserveCatalogProjection,
   });
 }
 
@@ -761,6 +790,7 @@ export interface ObservedCatalogMergeInput {
   readonly disabledModels: ReadonlySet<string>;
   readonly selectedModelsByProvider: ReadonlyMap<string, ReadonlySet<string>>;
   readonly gatheredProviderNames: ReadonlySet<string>;
+  readonly pendingProviderNames?: ReadonlySet<string>;
   readonly degradedProviderNames: ReadonlySet<string>;
   readonly legacyCustomModelSlugs: ReadonlySet<string>;
   readonly multiAgentMode: MultiAgentMode;
@@ -792,6 +822,7 @@ export function mergeCatalogEntriesFromObservedState({
   disabledModels,
   selectedModelsByProvider,
   gatheredProviderNames,
+  pendingProviderNames = new Set(),
   degradedProviderNames,
   legacyCustomModelSlugs,
   multiAgentMode,
@@ -841,6 +872,7 @@ export function mergeCatalogEntriesFromObservedState({
     if (disabledModelKeys.has(key)) return false;
     const slash = slug.indexOf("/");
     const provider = slug.slice(0, slash);
+    if (pendingProviderNames.has(provider)) return false;
     const selected = selectedModelKeysByProvider.get(provider);
     if (selected !== undefined && !selected.has(key)) return false;
     return !gatheredProviderNames.has(provider) || degradedProviderNames.has(provider);
@@ -946,7 +978,7 @@ export function mergeCatalogEntriesFromObservedState({
       const preserved = normalizeServiceTiers({ ...m, priority: nativePriority(slug, m.priority) });
       // Older natives kept from disk still need the mock top tiers (max + ultra always
       // for subagent max spawns; wire-clamped to the model's real top rung).
-      if (!isGpt56NativeSlug(slug)) ensureUltraReasoningLevel(preserved);
+      if (!isGpt56NativeSlug(slug) && slug !== NATIVE_RESERVE_MODEL) ensureUltraReasoningLevel(preserved);
       return preserved;
     })
     : [];
@@ -981,6 +1013,9 @@ export function mergeCatalogEntriesFromObservedState({
     typeof entry.slug === "string" ? [[entry.slug, entry] as const] : []
   ));
   const alignedAccountBoundEntries = detachedAccountBoundEntries.map(entry => {
+    // The explicit Reserve source is already chosen (actual row or documented Luna adaptation).
+    // A generic native merge must not replace its provenance or capability ladder.
+    if (isReserveCatalogProjection(entry)) return entry;
     const nativeSlug = trustedAccountBoundNativeCatalogSlug(entry);
     const source = nativeSlug === undefined ? undefined : nativeSourceBySlug.get(nativeSlug);
     if (!source) return entry;
@@ -1036,6 +1071,7 @@ export function mergeCatalogEntriesFromObservedState({
     if (freshExactComboEntries.has(entry)) return true;
     const slash = slug.indexOf("/");
     const provider = slug.slice(0, slash);
+    if (pendingProviderNames.has(provider)) return false;
     const selected = selectedModelKeysByProvider.get(provider);
     return selected === undefined || selected.has(slugEquivalenceKey(slug));
   });
@@ -1087,17 +1123,18 @@ export function mergeCatalogEntriesFromObservedState({
   }));
   for (const slug of policy.nativeBackfillSlugs) observedNativeSlugs.add(slug);
   const mergedEntries = [...native, ...managedEntries].map(m => {
-    const normalized = normalizeServiceTiers(m);
-    if (!isNativeAliasCatalogEntry(normalized)) applyNativeOpenAiContextOverride(normalized, openaiContextCap);
+    const reserveProjection = isReserveCatalogProjection(m);
+    const normalized = reserveProjection ? m : normalizeServiceTiers(m);
+    if (!reserveProjection && !isNativeAliasCatalogEntry(normalized)) applyNativeOpenAiContextOverride(normalized, openaiContextCap);
     const exactCombo = isExactComboCatalogEntry(m, exactComboSlugs);
-    const e = ensureStrictCatalogFields(normalized, {
+    const e = reserveProjection ? normalized : ensureStrictCatalogFields(normalized, {
       preserveExactInputModalities: exactCombo,
       isRouted: finalRoutedEntrySet.has(m),
     });
     // Mock-max universality (260709): preserved routed entries from disk may predate
     // the max rung — ensure it here so subagent max spawns validate on every
     // reasoning-capable entry. max only: 5.6 exact ladders (luna: no ultra) stay intact.
-    if (!exactCombo) {
+    if (!exactCombo && !reserveProjection) {
       const levels = Array.isArray(e.supported_reasoning_levels)
         ? e.supported_reasoning_levels as Array<{ effort?: string }>
         : [];
@@ -1122,7 +1159,7 @@ export function mergeCatalogEntriesFromObservedState({
     applyNativeVisibility(mergedEntries, disabledModels, alignedAccountBoundEntries.length > 0, observedNativeSlugs),
     multiAgentMode,
     multiAgentV2Enabled,
-    { keepNativeChatGptOnV1 },
+    { keepNativeChatGptOnV1, preserveDefaultMultiAgentVersion: isReserveCatalogProjection },
   );
   for (const entry of versionedEntries) {
     const kind = entry.opencodex_catalog_kind;
@@ -1610,6 +1647,36 @@ function writeRetainedCatalogSync({
       trustedAccountBoundNativeCatalogSlug(entry) !== undefined),
   ];
   const accountTargets = new Map(codexAccountNamespaceEntries(config));
+  const reserveMainSelectors = accountSelectors.filter(selector =>
+    isMainCodexAccountTarget(accountTargets.get(selector) ?? ""));
+  // The active file can own a bare source even when the bundled catalog is the build base.
+  // A previously clamped qualified projection must not shorten a retained genuine ladder.
+  const reserveObservations = [
+    ...(onDiskCatalog?.models ?? []),
+    ...(read.modelsCache?.models ?? []),
+    ...(catalog.models ?? []),
+  ];
+  const retainedReserve = onDiskCatalog?.[RESERVE_SOURCE_CATALOG_FIELD];
+  const retainedReserveSource = retainedReserve && typeof retainedReserve === "object" && !Array.isArray(retainedReserve)
+    ? observedReserveCatalogSource([retainedReserve as RawEntry], [])
+    : null;
+  const observedReserveSource = observedReserveCatalogSource(
+    // Cache invalidation carries historical bare observations alongside emitted models.
+    // Only unmarked observations are fresh enough to supersede the retained source.
+    reserveObservations.filter(entry => entry.slug === NATIVE_RESERVE_MODEL
+      && entry.opencodex_account_observed_native === undefined), reserveMainSelectors,
+  ) ?? retainedReserveSource ?? observedReserveCatalogSource(reserveObservations, reserveMainSelectors);
+  // This root is read only by OCX. Upstream ModelsResponse ignores unknown root fields.
+  // Retain before final runtime clamping: an omitted row must not turn into Luna next sync.
+  if (observedReserveSource) catalog[RESERVE_SOURCE_CATALOG_FIELD] = structuredClone(observedReserveSource);
+  else delete catalog[RESERVE_SOURCE_CATALOG_FIELD];
+  const lunaSource = upstreamNativeEntry(RESERVE_LUNA_METADATA_SOURCE);
+  const reserve = createReserveCatalogProjection(
+    config,
+    reserveMainSelectors,
+    observedReserveSource,
+    lunaSource ? finishUpstreamNativeEntry(lunaSource, 9, openaiContextCap) : null,
+  );
   const accountNativeSlugsBySelector = accountSelectors.length > 0
     ? new Map([...accountBoundNativeOpenAiSlugsBySelector(config, observedAccountNativeEntries)].map(([selector, slugs]) => {
       const target = accountTargets.get(selector);
@@ -1691,6 +1758,7 @@ function writeRetainedCatalogSync({
       openaiContextCap,
       accountNativeSlugs,
       accountNativeSlugsBySelector,
+      reserve,
     }).filter(entry => trustedAccountBoundNativeCatalogSlug(entry) !== undefined)
     : [];
   catalog.models = mergeCatalogEntriesFromObservedState({
@@ -1704,6 +1772,7 @@ function writeRetainedCatalogSync({
     disabledModels: new Set(config.disabledModels ?? []),
     selectedModelsByProvider,
     gatheredProviderNames,
+    pendingProviderNames: pendingModelSelectionProviders(config),
     degradedProviderNames,
     legacyCustomModelSlugs: legacyCustomModelCatalogSlugs(config),
     multiAgentMode,
@@ -1806,6 +1875,10 @@ export async function syncCatalogModels(
   config: OcxConfig,
   options?: CodexCatalogSyncOptions,
 ): Promise<RetainedCatalogSyncResult> {
+  if (pendingModelSelectionProviders(config).size) {
+    const { resolvePendingInitialModelSelection } = await import("../../providers/initial-model-selection-runtime");
+    await resolvePendingInitialModelSelection(config);
+  }
   const owningCodexHome = getCodexHome();
   const preflightRead = readRetainedCatalogSync(config);
   if (preflightRead === null) {

package/src/codex/convergence-types.ts

@@ -429,6 +429,7 @@ export interface CatalogTrustedOpenAiApiPolicySnapshot {
   readonly models?: readonly string[];
   readonly modelContextWindows?: Readonly<Record<string, number>>;
   readonly modelMaxInputTokens?: Readonly<Record<string, number>>;
+  readonly modelMaxOutputTokens?: Readonly<Record<string, number>>;
   readonly virtualModels?: Readonly<Record<string, Readonly<{ wireModelId: string; reasoningMode: "pro" }>>>;
   readonly modelInputModalities?: Readonly<Record<string, readonly string[]>>;
   readonly modelReasoningEfforts?: Readonly<Record<string, readonly string[]>>;

package/src/codex/convergence.ts

@@ -2,6 +2,7 @@ import { join } from "node:path";
 
 import { getConfigDir, saveConfigPreservingClaudeCode, websocketsEnabled, withExpectedConfigGenerationSync } from "../config";
 import { reconcileSuccessfulModelDiscoveries } from "../providers/new-model-policy";
+import { pendingModelSelectionProviders } from "../providers/initial-model-selection";
 import { COMBO_NAMESPACE } from "../combos";
 import { getAuthStorePath } from "../oauth/store";
 import type { OcxConfig } from "../types";
@@ -351,6 +352,7 @@ function prepareCatalog(
     disabledModels: new Set(config.disabledModels ?? []),
     selectedModelsByProvider,
     gatheredProviderNames,
+    pendingProviderNames: pendingModelSelectionProviders(config),
     degradedProviderNames,
     legacyCustomModelSlugs: legacyCustomModelCatalogSlugs(config),
     multiAgentMode,

package/src/codex/data/upstream-models.json

@@ -1018,7 +1018,7 @@
         {
           "id": "priority",
           "name": "Fast",
-          "description": "1.5x speed, increased usage"
+          "description": "2x speed, increased usage"
         }
       ],
       "additional_speed_tiers": [

package/src/codex/forward-transport-headers.ts

@@ -0,0 +1,25 @@
+/** Native request metadata shared by the HTTP adapter and WS preparation. */
+export const CODEX_RESPONSES_LITE_HEADER = "x-openai-internal-codex-responses-lite";
+export const CODEX_RESPONSES_LITE_METADATA_KEY = "ws_request_header_x_openai_internal_codex_responses_lite";
+export const CODEX_ROUTING_HINT_HEADER = "x-codex-routing-hint";
+
+const MAX_ROUTING_MODEL_BYTES = 256;
+const MAX_ROUTING_TIER_BYTES = 64;
+
+function isRoutingHintComponent(value: unknown, maxBytes: number): value is string {
+  // Printable non-whitespace ASCII makes code-unit length equal to byte length.
+  return typeof value === "string" && value.length > 0 && value.length <= maxBytes
+    && /^[\x21-\x7e]+$/.test(value) && !/[;=]/.test(value);
+}
+
+/** The final wire body is authoritative; an invalid component never revives a stale hint. */
+export function applyCodexRoutingHint(headers: Headers, body: unknown): void {
+  headers.delete(CODEX_ROUTING_HINT_HEADER);
+  if (typeof body !== "object" || body === null || Array.isArray(body)) return;
+  const record = body as Record<string, unknown>;
+  if (!isRoutingHintComponent(record.model, MAX_ROUTING_MODEL_BYTES)) return;
+  const tier = record.service_tier;
+  if (tier !== undefined && !isRoutingHintComponent(tier, MAX_ROUTING_TIER_BYTES)) return;
+  headers.set(CODEX_ROUTING_HINT_HEADER,
+    `model=${record.model}${tier === undefined ? "" : `;tier=${tier}`}`);
+}

package/src/codex/inject.ts

@@ -77,6 +77,9 @@ import {
   type ManagedSubagentDefaults,
 } from "./subagent-defaults";
 import type { OcxConfig } from "../types";
+import { isLoopbackHostname, shouldInjectApiAuthHeader } from "./loopback-target";
+
+export { isLoopbackHostname, shouldInjectApiAuthHeader } from "./loopback-target";
 
 // Ownership predicates live in `./injected-marker` so `journal.ts` can reach them
 // without importing this module back. Re-exported for existing external callers.
@@ -233,23 +236,6 @@ function configuredManagedSubagentDefaults(
  * whatever `[table]` happened to be open last (e.g. `[plugins."chrome@openai-bundled"]`), so Codex
  * never saw a global model_provider and silently fell back to the `openai` (ChatGPT) provider.
  */
-/**
- * True only for hostnames that bind loopback ONLY. Wildcard binds ("0.0.0.0", "::") are NOT
- * loopback: they expose the proxy on every interface and therefore require the admission token.
- * Do not use `providerBaseHost` for this decision — it folds wildcards to 127.0.0.1 because it
- * answers "what address do I dial", which is a different question from "is this exposed".
- */
-export function isLoopbackHostname(hostname: string | undefined): boolean {
-  const normalized = (hostname ?? "127.0.0.1").trim().toLowerCase();
-  return (
-    normalized === "" ||
-    normalized === "localhost" ||
-    normalized === "127.0.0.1" ||
-    normalized === "::1" ||
-    normalized === "[::1]"
-  );
-}
-
 export function providerBaseHost(hostname: string | undefined): string {
   const trimmed = (hostname ?? "127.0.0.1").trim();
   const lower = trimmed.toLowerCase();
@@ -267,17 +253,6 @@ export function providerBaseHost(hostname: string | undefined): string {
   return trimmed.includes(":") ? `[${trimmed}]` : trimmed;
 }
 
-export function shouldInjectApiAuthHeader(
-  config: Pick<OcxConfig, "hostname" | "unauthenticatedLoopbackListener"> | undefined,
-): boolean {
-  // The unauthenticated loopback listener is a loopback bind, so it admits without a
-  // credential (#1102). Emitting the env header anyway would be worse than useless: the
-  // directly-spawned app-server this exists for has no OPENCODEX_API_AUTH_TOKEN in its
-  // environment, and Codex would send an empty header value.
-  if (config?.unauthenticatedLoopbackListener?.enabled) return false;
-  return !isLoopbackHostname(config?.hostname);
-}
-
 export function buildProviderTableBlock(
   port: number,
   supportsWebsockets?: boolean,

package/src/codex/legacy-config-keys.ts

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { resolveCodexHomeDir } from "./home";
+import { parseTomlDocument } from "./project-config-warnings";
+import { redactUserPath } from "../lib/redact";
+
+/**
+ * Keys that are valid in model catalog data but not at the top level of the
+ * user config. Codex rejects them when strict config parsing is enabled.
+ */
+const LEGACY_KEYS = ["persistent_instructions"] as const;
+
+export type LegacyCodexConfigKey = (typeof LEGACY_KEYS)[number];
+
+export interface LegacyCodexConfigKeyDiagnostic {
+  readonly path: string;
+  readonly code: LegacyCodexConfigKey;
+  readonly detail: string;
+}
+
+export type LegacyCodexConfigKeyDiagnosticsResult =
+  | { readonly status: "available"; readonly path: string; readonly diagnostics: readonly LegacyCodexConfigKeyDiagnostic[] }
+  | { readonly status: "unavailable"; readonly path: string; readonly reason: "read_failed" | "not_a_file" };
+
+function resolveCodexConfigPath(codexConfigPath?: string): string {
+  if (codexConfigPath) return codexConfigPath;
+  return join(resolveCodexHomeDir(), "config.toml");
+}
+
+export function collectLegacyCodexConfigKeyDiagnostics(
+  options: { codexConfigPath?: string } = {},
+): LegacyCodexConfigKeyDiagnosticsResult {
+  const path = resolveCodexConfigPath(options.codexConfigPath);
+  if (!existsSync(path)) return { status: "available", path, diagnostics: [] };
+  let content: string;
+  try {
+    if (!statSync(path).isFile()) return { status: "unavailable", path, reason: "not_a_file" };
+    content = readFileSync(path, "utf-8");
+  } catch { // no-excuse-ok: catch -- optional doctor diagnostics must not fail on an unreadable file.
+    return { status: "unavailable", path, reason: "read_failed" };
+  }
+  const { root } = parseTomlDocument(content);
+  const found: LegacyCodexConfigKeyDiagnostic[] = [];
+  for (const key of LEGACY_KEYS) {
+    if (key in root) {
+      found.push({
+        path,
+        code: key,
+        detail: `top-level '${key}' is not a valid Codex config key. `
+          + "codex --strict-config rejects the whole file. Remove the key and put durable guidance in AGENTS.md.",
+      });
+    }
+  }
+  return { status: "available", path, diagnostics: found };
+}
+
+export function formatLegacyCodexConfigKeyDiagnosticsForDoctor(
+  result: LegacyCodexConfigKeyDiagnosticsResult,
+): string[] {
+  const displayPath = redactUserPath(result.path);
+  if (result.status === "unavailable") {
+    return [`  --     Codex config at ${displayPath} could not be read (${result.reason}); legacy-key check skipped`];
+  }
+  if (result.diagnostics.length === 0) {
+    return ["  ok     no unsupported legacy top-level keys in the Codex config"];
+  }
+  return result.diagnostics.map(diagnostic => `[WARN] ${redactUserPath(diagnostic.path)}: ${diagnostic.detail}`);
+}

package/src/codex/log-guard/inspect-schema.ts

@@ -0,0 +1,137 @@
+import type { Database } from "bun:sqlite";
+
+interface CurrentLogColumn {
+  name: string;
+  type: string;
+  notnull: number;
+  defaultValue: string | null;
+  pk: number;
+}
+
+// Pinned to Codex logs migration 0002. Keep this schema private: inspection reports
+// compatibility, not column names, so sensitive payload-bearing fields never leak through
+// the management API. Any additive/rebuilt future schema is monitor-only until reviewed.
+const CURRENT_LOG_SCHEMA: readonly CurrentLogColumn[] = [
+  { name: "id", type: "INTEGER", notnull: 0, defaultValue: null, pk: 1 },
+  { name: "ts", type: "INTEGER", notnull: 1, defaultValue: null, pk: 0 },
+  { name: "ts_nanos", type: "INTEGER", notnull: 1, defaultValue: null, pk: 0 },
+  { name: "level", type: "TEXT", notnull: 1, defaultValue: null, pk: 0 },
+  { name: "target", type: "TEXT", notnull: 1, defaultValue: null, pk: 0 },
+  { name: "feedback_log_body", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "module_path", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "file", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "line", type: "INTEGER", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "thread_id", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "process_uuid", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "estimated_bytes", type: "INTEGER", notnull: 1, defaultValue: "0", pk: 0 },
+] as const;
+
+const CURRENT_LOG_TABLE_SQL = `CREATE TABLE logs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL,
+  ts_nanos INTEGER NOT NULL,
+  level TEXT NOT NULL,
+  target TEXT NOT NULL,
+  feedback_log_body TEXT,
+  module_path TEXT,
+  file TEXT,
+  line INTEGER,
+  thread_id TEXT,
+  process_uuid TEXT,
+  estimated_bytes INTEGER NOT NULL DEFAULT 0
+)`;
+
+const CURRENT_LOG_INDEX_SQL = {
+  idx_logs_ts: "CREATE INDEX idx_logs_ts ON logs(ts DESC, ts_nanos DESC, id DESC)",
+  idx_logs_thread_id: "CREATE INDEX idx_logs_thread_id ON logs(thread_id)",
+  idx_logs_thread_id_ts: "CREATE INDEX idx_logs_thread_id_ts ON logs(thread_id, ts DESC, ts_nanos DESC, id DESC)",
+  idx_logs_process_uuid_threadless_ts: `CREATE INDEX idx_logs_process_uuid_threadless_ts
+    ON logs(process_uuid, ts DESC, ts_nanos DESC, id DESC)
+    WHERE thread_id IS NULL`,
+} as const;
+
+
+export interface ColumnRow {
+  cid: number;
+  name: string;
+  type: string;
+  notnull: number;
+  dflt_value: string | null;
+  pk: number;
+}
+interface SchemaObjectRow { name: string; type: string; sql: string | null }
+
+function normalizeDeclaredType(type: string): string {
+  return String(type ?? "").trim().toUpperCase();
+}
+
+function normalizeDefault(value: string | null): string | null {
+  return value === null ? null : String(value).trim();
+}
+
+function normalizeSchemaSql(sql: string | null | undefined): string {
+  return (sql ?? "").trim().replace(/;\s*$/, "").replace(/\s+/g, " ");
+}
+
+function sameColumns(columns: ColumnRow[]): boolean {
+  if (columns.length !== CURRENT_LOG_SCHEMA.length) return false;
+  return columns.every((column, index) => {
+    const expected = CURRENT_LOG_SCHEMA[index];
+    return column.cid === index
+      && column.name === expected.name
+      && normalizeDeclaredType(column.type) === expected.type
+      && Number(column.notnull) === expected.notnull
+      && normalizeDefault(column.dflt_value) === expected.defaultValue
+      && Number(column.pk) === expected.pk;
+  });
+}
+
+/**
+ * The authoritative compatibility predicate: exact table SQL, exact column
+ * metadata, and every canonical index.
+ *
+ * Exported because the mutation paths must apply the SAME test inside their
+ * write transaction. They used to check column NAMES only, which is strictly
+ * weaker than what the inspector reports, so a schema change landing between
+ * the outer inspection and the locked write let Protect install a row-dropping
+ * trigger and let Reclaim vacuum pages on a database the inspector classifies
+ * as monitor-only. The lock serializes OpenCodex against itself; it does not
+ * stop Codex or another SQLite writer, so that TOCTOU window is real.
+ */
+export function hasCurrentLogsSchema(db: Database): boolean {
+  const columns = db.query<ColumnRow, []>("PRAGMA table_info(logs)").all();
+  return hasCurrentLogsTable(db, columns);
+}
+
+export function hasCurrentLogsTable(db: Database, columns: ColumnRow[]): boolean {
+  const table = db.query<SchemaObjectRow, []>(
+    "SELECT name, type, sql FROM sqlite_schema WHERE name = 'logs' LIMIT 1",
+  ).get();
+  if (table?.type !== "table"
+    || !sameColumns(columns)
+    || normalizeSchemaSql(table.sql) !== normalizeSchemaSql(CURRENT_LOG_TABLE_SQL)) {
+    return false;
+  }
+
+  const indexes = db.query<SchemaObjectRow, []>(`
+    SELECT name, type, sql FROM sqlite_schema
+    WHERE name IN (
+      'idx_logs_ts',
+      'idx_logs_thread_id',
+      'idx_logs_thread_id_ts',
+      'idx_logs_process_uuid_threadless_ts'
+    )
+  `).all();
+  const byName = new Map(indexes.map(row => [row.name, row]));
+  for (const [name, expectedSql] of Object.entries(CURRENT_LOG_INDEX_SQL)) {
+    const row = byName.get(name);
+    if (row?.type !== "index" || normalizeSchemaSql(row.sql) !== normalizeSchemaSql(expectedSql)) {
+      return false;
+    }
+  }
+
+  // Extra indexes and triggers do not redefine the table contract. In particular,
+  // Protect intentionally installs OpenCodex-owned triggers and unrelated user triggers
+  // are supported, so compatibility is based on the canonical table plus required indexes.
+  return true;
+}