codex-configurator 0.2.5 → 0.2.6

package/README.md

@@ -120,6 +120,8 @@ You can override either command with:
 - `CODEX_CONFIGURATOR_CODEX_BIN=<command-or-path>`
 - `CODEX_CONFIGURATOR_NPM_BIN=<command-or-path>`
 
+The status bar shows `Using Codex v<version>` only after Codex version detection completes. During startup schema sync it shows `Checking schema`, and after that it shows `Checking Codex version` until the Codex check finishes. When needed, it shows Codex update state as `Update available` or `Version check unavailable`; if there is no warning badge, assume Codex is up to date. The schema-progress state is kept visible for at least `1.2s` so it is observable even on very fast connections. The Codex version check starts only after schema sync completes.
+
 ## Self-update behavior
 
 On startup, the app checks the npm registry for the latest `codex-configurator` version.
@@ -132,7 +134,17 @@ This uses the `npm` command from `PATH` (or `CODEX_CONFIGURATOR_NPM_BIN` if set)
 ## Upstream reference
 
 - Canonical config schema: https://developers.openai.com/codex/config-schema.json
-- The local menu reads directly from `src/reference/config-schema.json`, which is downloaded from the canonical schema.
+- Runtime behavior:
+  - App starts with bundled fallback schema from `src/reference/config-schema.json`.
+  - App then checks for updates on startup in the background.
+  - If a valid cached schema exists, it is loaded immediately.
+  - If upstream has a newer valid schema, it is applied immediately and cached for future launches.
+  - If the check fails, the app silently continues with the already-active schema.
+- Runtime cache location: `<codex-dir>/codex-configurator-cache/`
+  - Default codex dir: `~/.codex`
+  - Cached files:
+    - `config-schema.json`
+    - `config-schema.meta.json`
 - To refresh the reference snapshot after a new stable Codex release:
   - `npm run sync:reference`
 - Snapshot currently synced against Codex stable reference updates published on 2026-02-25.

package/index.js

@@ -36,6 +36,7 @@ import {
 import {
 	APP_MODES,
 	APP_STATE_ACTION,
+	REFERENCE_SCHEMA_CHANGED_ACTION,
 	appStateReducer,
 	buildInitialAppState,
 } from './src/appState.js';
@@ -43,6 +44,7 @@ import { pathToKey, clamp, computeListViewportRows } from './src/layout.js';
 import { Header } from './src/components/Header.js';
 import { ConfigNavigator } from './src/components/ConfigNavigator.js';
 import { filterRowsByQuery } from './src/fuzzySearch.js';
+import { syncReferenceSchemaAtStartup } from './src/schemaRuntimeSync.js';
 import { executeInputCommand, getModeHint } from './src/ui/commands.js';
 import { CommandBar } from './src/ui/panes/CommandBar.js';
 import { HelpBubble } from './src/ui/panes/HelpBubble.js';
@@ -75,6 +77,7 @@ const UPDATE_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const CODEX_BIN_ENV_VAR = 'CODEX_CONFIGURATOR_CODEX_BIN';
 const NPM_BIN_ENV_VAR = 'CODEX_CONFIGURATOR_NPM_BIN';
 const CONFIGURATOR_PACKAGE_NAME = 'codex-configurator';
+const SCHEMA_STATUS_MIN_VISIBLE_MS = 1200;
 const FILE_SWITCH_MAX_VISIBLE_ENTRIES = 6;
 const FILE_SWITCH_PANEL_BASE_ROWS = 3;
 const FILE_SWITCH_LAYOUT_EXTRA_GAP_ROWS = 1;
@@ -174,6 +177,11 @@ const runCommand = async (command, args = [], options = {}) => {
 	return result.stdout;
 };
 
+const waitForMilliseconds = (milliseconds) =>
+	new Promise((resolve) => {
+		setTimeout(resolve, Math.max(0, Number(milliseconds) || 0));
+	});
+
 const getConfiguredCommand = (environmentVariableName, fallbackCommand) => {
 	const configuredCommand = String(
 		process.env[environmentVariableName] || '',
@@ -364,7 +372,7 @@ const getCodexUpdateStatus = async () => {
 		return {
 			installed: installedLabel,
 			latest: 'unknown',
-			status: 'version check unavailable',
+			status: 'Version check unavailable',
 		};
 	}
 
@@ -380,7 +388,7 @@ const getCodexUpdateStatus = async () => {
 		return {
 			installed,
 			latest: 'unknown',
-			status: 'version check unavailable',
+			status: 'Version check unavailable',
 		};
 	}
 
@@ -389,14 +397,14 @@ const getCodexUpdateStatus = async () => {
 		return {
 			installed,
 			latest,
-			status: `update available: ${latest}`,
+			status: 'Update available',
 		};
 	}
 
 	return {
 		installed,
 		latest,
-		status: 'up to date',
+		status: 'Up to date',
 	};
 };
 
@@ -470,6 +478,8 @@ const App = () => {
 		});
 	const setStateBatch = (updates) =>
 		dispatch({ type: APP_STATE_ACTION, payload: { updates } });
+	const resetSchemaDerivedEditState = () =>
+		dispatch({ type: REFERENCE_SCHEMA_CHANGED_ACTION });
 
 	const setSnapshot = (valueOrUpdater) =>
 		setAppState('snapshot', valueOrUpdater);
@@ -517,6 +527,10 @@ const App = () => {
 		setAppState('codexVersion', valueOrUpdater);
 	const setCodexVersionStatus = (valueOrUpdater) =>
 		setAppState('codexVersionStatus', valueOrUpdater);
+	const setIsSchemaCheckInProgress = (valueOrUpdater) =>
+		setAppState('isSchemaCheckInProgress', valueOrUpdater);
+	const setSchemaCheckStatusText = (valueOrUpdater) =>
+		setAppState('schemaCheckStatusText', valueOrUpdater);
 	const {
 		snapshot,
 		snapshotByFileId,
@@ -538,6 +552,8 @@ const App = () => {
 		showHelp,
 		codexVersion,
 		codexVersionStatus,
+		isSchemaCheckInProgress,
+		schemaCheckStatusText,
 	} = state;
 	commandInputRef.current = String(commandInput || '');
 	const { exit } = useApp();
@@ -552,6 +568,10 @@ const App = () => {
 					: APP_MODES.BROWSE;
 
 	useEffect(() => {
+		if (isSchemaCheckInProgress) {
+			return undefined;
+		}
+
 		let isCancelled = false;
 
 		const loadVersionStatus = async () => {
@@ -570,9 +590,56 @@ const App = () => {
 			await ensureLatestConfiguratorVersion(commands.npmCommand);
 		};
 
+		setCodexVersionStatus('Checking Codex version');
 		loadVersionStatus();
 		ensureLatestConfigurator();
 
+		return () => {
+			isCancelled = true;
+		};
+	}, [isSchemaCheckInProgress]);
+
+	useEffect(() => {
+		let isCancelled = false;
+
+		const syncSchemaReference = async () => {
+			const checkStartedAt = Date.now();
+			const updateSchemaStatus = (status) => {
+				if (isCancelled) {
+					return;
+				}
+
+				setSchemaCheckStatusText(status);
+			};
+
+			await syncReferenceSchemaAtStartup({
+				mainConfigPath: initialMainSnapshot.path,
+				onSchemaChange: () => {
+					if (isCancelled) {
+						return;
+					}
+
+					resetSchemaDerivedEditState();
+				},
+				onStatus: updateSchemaStatus,
+			});
+
+			const elapsed = Date.now() - checkStartedAt;
+			const remainingVisibleMs = SCHEMA_STATUS_MIN_VISIBLE_MS - elapsed;
+			if (remainingVisibleMs > 0) {
+				await waitForMilliseconds(remainingVisibleMs);
+			}
+
+			if (isCancelled) {
+				return;
+			}
+
+			setSchemaCheckStatusText('');
+			setIsSchemaCheckInProgress(false);
+		};
+
+		syncSchemaReference();
+
 		return () => {
 			isCancelled = true;
 		};
@@ -1447,6 +1514,8 @@ const App = () => {
 		React.createElement(StatusLine, {
 			codexVersion,
 			codexVersionStatus,
+			isSchemaCheckInProgress,
+			schemaCheckStatusText,
 			activeConfigFile,
 			appMode,
 		}),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codex-configurator",
-	"version": "0.2.5",
+	"version": "0.2.6",
 	"description": "TOML-aware Ink TUI for Codex Configurator",
 	"main": "index.js",
 	"type": "module",

package/src/appState.js

@@ -1,4 +1,5 @@
 export const APP_STATE_ACTION = 'APP_STATE_ACTION';
+export const REFERENCE_SCHEMA_CHANGED_ACTION = 'REFERENCE_SCHEMA_CHANGED_ACTION';
 
 export const APP_MODES = {
   BROWSE: 'browse',
@@ -9,6 +10,14 @@ export const APP_MODES = {
 };
 
 export const appStateReducer = (state, action) => {
+  if (action.type === REFERENCE_SCHEMA_CHANGED_ACTION) {
+    return {
+      ...state,
+      editMode: null,
+      editError: '',
+    };
+  }
+
   if (action.type !== APP_STATE_ACTION) {
     return state;
   }
@@ -66,4 +75,6 @@ export const buildInitialAppState = (initialMainSnapshot, initialCatalog, initia
   showHelp: false,
   codexVersion: 'version loading...',
   codexVersionStatus: '',
+  isSchemaCheckInProgress: true,
+  schemaCheckStatusText: 'Checking schema',
 });

package/src/components/Header.js

@@ -26,9 +26,4 @@ export const Header = ({ packageVersion }) =>
 				`v${packageVersion || 'unknown'}`,
 			),
 		),
-		React.createElement(
-			Text,
-			{ color: 'white', dimColor: false },
-			'TUI Mode ',
-		),
 	);

package/src/configFeatures.js

@@ -35,25 +35,24 @@ const buildFeatureDefinitionFromReference = (key) => {
   };
 };
 
-const DOCUMENTED_REFERENCE_FEATURE_KEYS = getReferenceFeatureKeys();
-
-export const CONFIG_FEATURE_DEFINITIONS = DOCUMENTED_REFERENCE_FEATURE_KEYS
-  .map((key) => buildFeatureDefinitionFromReference(key))
-  .filter(Boolean);
-
-const FEATURE_DEFINITION_MAP = CONFIG_FEATURE_DEFINITIONS.reduce((acc, definition) => {
-  acc[definition.key] = definition;
-
-  return acc;
-}, {});
+const buildFeatureDefinitionMap = () =>
+  getReferenceFeatureKeys()
+    .map((key) => buildFeatureDefinitionFromReference(key))
+    .filter(Boolean)
+    .reduce((acc, definition) => {
+      acc[definition.key] = definition;
+      return acc;
+    }, {});
 
 export const getConfigFeatureKeys = () => {
-  return DOCUMENTED_REFERENCE_FEATURE_KEYS;
+  return getReferenceFeatureKeys();
 };
 
-export const getConfigFeatureDefinition = (key) => FEATURE_DEFINITION_MAP[key];
+export const getConfigFeatureDefinition = (key) =>
+  buildFeatureDefinitionMap()[String(key || '').trim()];
 
 export const getConfigFeatureDefinitionOrFallback = (key) => {
+  const normalizedKey = String(key || '').trim();
   if (!key) {
     return {
       short: `${prettifyFeatureName(String(key))}`,
@@ -64,9 +63,9 @@ export const getConfigFeatureDefinitionOrFallback = (key) => {
   }
 
   return (
-    FEATURE_DEFINITION_MAP[key] || {
-      key,
-      short: prettifyFeatureName(String(key)),
+    getConfigFeatureDefinition(normalizedKey) || {
+      key: normalizedKey,
+      short: prettifyFeatureName(normalizedKey),
       usage: 'This configured key is not in the official feature list.',
       defaultValue: false,
       isDocumented: false,

package/src/configReference.js

@@ -1,7 +1,7 @@
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const CONFIG_SCHEMA_DATA = require('./reference/config-schema.json');
+const BUNDLED_CONFIG_SCHEMA_DATA = require('./reference/config-schema.json');
 
 const ROOT_PLACEHOLDER = '<name>';
 const PLACEHOLDER_SEGMENT = /^<[^>]+>$/;
@@ -38,6 +38,8 @@ const normalizeType = (type) => String(type || '').replace(/\s+/g, ' ').trim();
 const isObject = (value) =>
   value !== null && typeof value === 'object' && !Array.isArray(value);
 
+const buildSchemaRevision = (schema) => JSON.stringify(schema);
+
 const isPrimitiveValue = (type) =>
   type === 'string' || type === 'number' || type === 'integer' || type === 'boolean';
 
@@ -966,9 +968,62 @@ const fullPathMatches = (referencePath, actualPath) =>
 const countConcreteSegments = (segments) =>
   segments.reduce((count, segment) => count + (isPlaceholderSegment(segment) ? 0 : 1), 0);
 
-const referenceOptions = buildReferenceOptions(CONFIG_SCHEMA_DATA);
+const buildFeatureKeys = (referenceOptions) => [
+  ...new Set(
+    referenceOptions
+      .filter(
+        (option) =>
+          option.keyPath.length === 2 &&
+          option.keyPath[0] === 'features' &&
+          !isPlaceholderSegment(option.keyPath[1])
+      )
+      .map((option) => option.keyPath[1])
+  ),
+].sort((left, right) => left.localeCompare(right));
+
+const prepareReferenceState = (schema) => {
+  if (!isObject(schema)) {
+    return null;
+  }
+
+  const referenceOptions = buildReferenceOptions(schema);
+  if (!Array.isArray(referenceOptions) || referenceOptions.length === 0) {
+    return null;
+  }
+
+  return {
+    schema,
+    revision: buildSchemaRevision(schema),
+    referenceOptions,
+    optionsByKey: new Map(referenceOptions.map((option) => [option.key, option])),
+    featureKeys: buildFeatureKeys(referenceOptions),
+  };
+};
+
+let activeReferenceState = prepareReferenceState(BUNDLED_CONFIG_SCHEMA_DATA);
+if (!activeReferenceState) {
+  throw new Error('Bundled config schema is invalid.');
+}
 
-const optionsByKey = new Map(referenceOptions.map((option) => [option.key, option]));
+const getReferenceState = () => activeReferenceState;
+
+export const isReferenceSchemaValid = (schema) => Boolean(prepareReferenceState(schema));
+
+export const getReferenceSchemaRevision = () => getReferenceState().revision;
+
+export const setReferenceSchema = (schema) => {
+  const nextState = prepareReferenceState(schema);
+  if (!nextState) {
+    return false;
+  }
+
+  if (activeReferenceState?.revision === nextState.revision) {
+    return true;
+  }
+
+  activeReferenceState = nextState;
+  return true;
+};
 
 const mergeDefinition = (map, definition) => {
   const existing = map.get(definition.key);
@@ -988,6 +1043,7 @@ const mergeDefinition = (map, definition) => {
 };
 
 export const getReferenceOptionForPath = (pathSegments) => {
+  const { optionsByKey, referenceOptions } = getReferenceState();
   const normalizedPath = normalizeSegments(pathSegments);
   if (normalizedPath.length === 0) {
     return null;
@@ -1016,7 +1072,7 @@ export const getReferenceOptionForPath = (pathSegments) => {
   return candidates[0];
 };
 
-const getVariantObjectPaths = (normalizedPath) => {
+const getVariantObjectPaths = (normalizedPath, referenceOptions) => {
   const depth = normalizedPath.length;
   const paths = referenceOptions
     .filter((option) => pathPrefixMatches(option.keyPath, normalizedPath))
@@ -1028,6 +1084,7 @@ const getVariantObjectPaths = (normalizedPath) => {
 };
 
 export const getReferenceVariantForPath = (pathSegments = []) => {
+  const { referenceOptions } = getReferenceState();
   const normalizedPath = normalizeSegments(pathSegments);
   if (normalizedPath.length === 0) {
     return null;
@@ -1061,11 +1118,12 @@ export const getReferenceVariantForPath = (pathSegments = []) => {
               : {},
         }))
       : [],
-    objectSchemaPaths: getVariantObjectPaths(normalizedPath),
+    objectSchemaPaths: getVariantObjectPaths(normalizedPath, referenceOptions),
   };
 };
 
 export const getReferenceTableDefinitions = (pathSegments = []) => {
+  const { referenceOptions } = getReferenceState();
   const normalizedPath = normalizeSegments(pathSegments);
   const childDefinitions = new Map();
   const depth = normalizedPath.length;
@@ -1099,22 +1157,10 @@ export const getReferenceTableDefinitions = (pathSegments = []) => {
 
 export const getReferenceRootDefinitions = () => getReferenceTableDefinitions([]);
 
-const featureKeys = [
-  ...new Set(
-    referenceOptions
-      .filter(
-        (option) =>
-          option.keyPath.length === 2 &&
-          option.keyPath[0] === 'features' &&
-          !isPlaceholderSegment(option.keyPath[1])
-      )
-      .map((option) => option.keyPath[1])
-  ),
-].sort((left, right) => left.localeCompare(right));
-
-export const getReferenceFeatureKeys = () => featureKeys;
+export const getReferenceFeatureKeys = () => [...getReferenceState().featureKeys];
 
 export const getReferenceCustomIdPlaceholder = (pathSegments = []) => {
+  const { referenceOptions } = getReferenceState();
   const normalizedPath = normalizeSegments(pathSegments);
   const depth = normalizedPath.length;
   const placeholders = new Set();
@@ -1139,6 +1185,7 @@ export const getReferenceCustomIdPlaceholder = (pathSegments = []) => {
 };
 
 export const getReferenceDescendantOptions = (pathSegments = []) => {
+  const { referenceOptions } = getReferenceState();
   const normalizedPath = normalizeSegments(pathSegments);
 
   return referenceOptions

package/src/schemaRuntimeSync.js

@@ -0,0 +1,282 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  getReferenceSchemaRevision,
+  setReferenceSchema,
+} from './configReference.js';
+import { logConfiguratorError } from './errorLogger.js';
+
+const CONFIG_SCHEMA_URL = 'https://developers.openai.com/codex/config-schema.json';
+const SCHEMA_CACHE_DIRECTORY_NAME = 'codex-configurator-cache';
+const SCHEMA_CACHE_FILE_NAME = 'config-schema.json';
+const SCHEMA_METADATA_FILE_NAME = 'config-schema.meta.json';
+const FETCH_TIMEOUT_MS = 10000;
+const MAX_SCHEMA_BYTES = 512 * 1024;
+
+const isObject = (value) =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const normalizeText = (value) => String(value || '').trim();
+
+const resolveCodexDirectory = ({ mainConfigPath = '', homeDir = os.homedir() } = {}) => {
+  const normalizedPath = normalizeText(mainConfigPath);
+  if (!normalizedPath) {
+    return path.join(homeDir, '.codex');
+  }
+
+  return path.dirname(path.resolve(normalizedPath));
+};
+
+export const resolveSchemaCachePaths = ({ mainConfigPath = '', homeDir = os.homedir() } = {}) => {
+  const codexDirectory = resolveCodexDirectory({ mainConfigPath, homeDir });
+  const cacheDirectory = path.join(codexDirectory, SCHEMA_CACHE_DIRECTORY_NAME);
+  return {
+    codexDirectory,
+    cacheDirectory,
+    schemaPath: path.join(cacheDirectory, SCHEMA_CACHE_FILE_NAME),
+    metadataPath: path.join(cacheDirectory, SCHEMA_METADATA_FILE_NAME),
+  };
+};
+
+const readJsonFile = (targetPath) => {
+  try {
+    const payload = fs.readFileSync(targetPath, 'utf8');
+    return JSON.parse(payload);
+  } catch {
+    return null;
+  }
+};
+
+const writeJsonFileAtomic = (targetPath, payload) => {
+  const directoryPath = path.dirname(targetPath);
+  const fileName = path.basename(targetPath);
+  const tempPath = path.join(
+    directoryPath,
+    `.${fileName}.${process.pid}.${Date.now()}.tmp`
+  );
+
+  if (!fs.existsSync(directoryPath)) {
+    fs.mkdirSync(directoryPath, { recursive: true, mode: 0o700 });
+  }
+
+  let fileDescriptor = null;
+
+  try {
+    fileDescriptor = fs.openSync(tempPath, 'wx', 0o600);
+    fs.writeFileSync(fileDescriptor, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+    fs.fsyncSync(fileDescriptor);
+    fs.closeSync(fileDescriptor);
+    fileDescriptor = null;
+    fs.renameSync(tempPath, targetPath);
+  } finally {
+    if (fileDescriptor !== null) {
+      try {
+        fs.closeSync(fileDescriptor);
+      } catch {}
+    }
+
+    if (fs.existsSync(tempPath)) {
+      try {
+        fs.unlinkSync(tempPath);
+      } catch {}
+    }
+  }
+};
+
+const applySchema = (schema) => {
+  const previousRevision = getReferenceSchemaRevision();
+  const ok = setReferenceSchema(schema);
+  if (!ok) {
+    return {
+      ok: false,
+      changed: false,
+    };
+  }
+
+  return {
+    ok: true,
+    changed: previousRevision !== getReferenceSchemaRevision(),
+  };
+};
+
+const buildConditionalHeaders = (metadata = {}) => {
+  const headers = {
+    accept: 'application/json',
+  };
+  const etag = normalizeText(metadata.etag);
+  const lastModified = normalizeText(metadata.lastModified);
+
+  if (etag) {
+    headers['if-none-match'] = etag;
+  }
+
+  if (lastModified) {
+    headers['if-modified-since'] = lastModified;
+  }
+
+  return headers;
+};
+
+const fetchRemoteSchema = async ({
+  fetchImpl = fetch,
+  metadata = {},
+}) => {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  try {
+    const response = await fetchImpl(CONFIG_SCHEMA_URL, {
+      headers: buildConditionalHeaders(metadata),
+      signal: controller.signal,
+    });
+
+    if (response.status === 304) {
+      return {
+        status: 'not-modified',
+      };
+    }
+
+    if (!response.ok) {
+      throw new Error(
+        `Schema request failed (${response.status} ${response.statusText})`
+      );
+    }
+
+    const contentType = normalizeText(response.headers.get('content-type')).toLowerCase();
+    if (!contentType.includes('application/json')) {
+      throw new Error('Schema response content-type is not application/json.');
+    }
+
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length > MAX_SCHEMA_BYTES) {
+      throw new Error(
+        `Schema response exceeded max size (${bytes.length} bytes > ${MAX_SCHEMA_BYTES} bytes).`
+      );
+    }
+
+    let parsedSchema = null;
+    try {
+      parsedSchema = JSON.parse(bytes.toString('utf8'));
+    } catch (error) {
+      throw new Error(
+        `Schema response was not valid JSON (${String(error?.message || 'parse failed')}).`
+      );
+    }
+
+    return {
+      status: 'updated',
+      schema: parsedSchema,
+      metadata: {
+        etag: normalizeText(response.headers.get('etag')) || null,
+        lastModified: normalizeText(response.headers.get('last-modified')) || null,
+      },
+    };
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};
+
+export const syncReferenceSchemaAtStartup = async ({
+  mainConfigPath = '',
+  fetchImpl = fetch,
+  onSchemaChange,
+  onStatus,
+} = {}) => {
+  const cachePaths = resolveSchemaCachePaths({ mainConfigPath });
+  const notifySchemaChange = (source) => {
+    if (typeof onSchemaChange === 'function') {
+      onSchemaChange({ source });
+    }
+  };
+  const updateStatus = (value) => {
+    if (typeof onStatus === 'function') {
+      onStatus(String(value || '').trim());
+    }
+  };
+
+  let source = 'bundled';
+  let canReuseCachedValidators = false;
+
+  try {
+    updateStatus('Schema: Loading cache...');
+
+    const cachedSchema = readJsonFile(cachePaths.schemaPath);
+    const metadataPayload = readJsonFile(cachePaths.metadataPath);
+    const cachedMetadata = isObject(metadataPayload) ? metadataPayload : {};
+
+    if (cachedSchema !== null) {
+      const cacheApplyResult = applySchema(cachedSchema);
+      if (cacheApplyResult.ok) {
+        source = 'cache';
+        canReuseCachedValidators = true;
+        if (cacheApplyResult.changed) {
+          notifySchemaChange('cache');
+        }
+      } else {
+        logConfiguratorError('schema.cache.invalid', {
+          schemaPath: cachePaths.schemaPath,
+        });
+      }
+    }
+
+    updateStatus('Schema: Checking upstream...');
+
+    const fetchResult = await fetchRemoteSchema({
+      fetchImpl,
+      metadata: canReuseCachedValidators ? cachedMetadata : {},
+    });
+
+    if (fetchResult.status === 'not-modified') {
+      return {
+        ok: true,
+        updated: false,
+        source,
+      };
+    }
+
+    const remoteApplyResult = applySchema(fetchResult.schema);
+    if (!remoteApplyResult.ok) {
+      throw new Error('Downloaded schema did not pass local validation.');
+    }
+    if (remoteApplyResult.changed) {
+      notifySchemaChange('remote');
+    }
+
+    updateStatus('Schema: Saving cache...');
+
+    const mergedMetadata = {
+      etag: fetchResult.metadata.etag || normalizeText(cachedMetadata.etag) || null,
+      lastModified:
+        fetchResult.metadata.lastModified ||
+        normalizeText(cachedMetadata.lastModified) ||
+        null,
+      updatedAt: new Date().toISOString(),
+      sourceUrl: CONFIG_SCHEMA_URL,
+    };
+
+    writeJsonFileAtomic(cachePaths.schemaPath, fetchResult.schema);
+    writeJsonFileAtomic(cachePaths.metadataPath, mergedMetadata);
+
+    return {
+      ok: true,
+      updated: true,
+      source: 'remote',
+    };
+  } catch (error) {
+    const message = String(error?.message || 'Unknown schema sync error.');
+    logConfiguratorError('schema.sync.failed', {
+      error: message,
+      source,
+      schemaPath: cachePaths.schemaPath,
+      metadataPath: cachePaths.metadataPath,
+    });
+
+    return {
+      ok: false,
+      updated: false,
+      source,
+      error: message,
+    };
+  }
+};

package/src/ui/panes/StatusLine.js

@@ -2,18 +2,57 @@ import React from 'react';
 import { Box, Text } from 'ink';
 import { formatActiveFileSummary } from '../../layout.js';
 
+const SEMVER_PREFIX_PATTERN = /^\d+\.\d+\.\d+(?:[-+._][0-9A-Za-z.-]+)*$/;
+const CHECKING_BADGE_TEXT_COLOR = 'white';
+const CHECKING_BADGE_BACKGROUND_COLOR = 'green';
+
+const formatCodexVersion = (version) => {
+	const versionText = String(version || '').trim();
+	if (!versionText) {
+		return '—';
+	}
+
+	return SEMVER_PREFIX_PATTERN.test(versionText)
+		? `v${versionText}`
+		: versionText;
+};
+
 export const StatusLine = ({
 	codexVersion,
 	codexVersionStatus,
+	isSchemaCheckInProgress,
+	schemaCheckStatusText,
 	activeConfigFile,
 	appMode,
 }) => {
-	const statusText = codexVersionStatus || 'checking...';
-	const isUpToDate = statusText === 'up to date';
+	const codexStatusText = codexVersionStatus || 'Checking Codex version';
+	const schemaStatus =
+		String(schemaCheckStatusText || '').trim() || 'Checking schema';
+	const statusText = codexStatusText;
+	const isUpToDate = !isSchemaCheckInProgress && statusText === 'Up to date';
+	const isCodexChecking =
+		!isSchemaCheckInProgress &&
+		String(statusText).trim() === 'Checking Codex version';
 	const isUpdateAvailable =
+		!isSchemaCheckInProgress &&
 		typeof statusText === 'string' &&
-		statusText.startsWith('update available');
-	const statusPrefix = isUpToDate ? '✓' : isUpdateAvailable ? '⚠️' : '';
+		statusText.startsWith('Update available');
+	const shouldShowCodexStatus =
+		!isSchemaCheckInProgress && !isUpToDate && !isCodexChecking;
+	const statusPrefix = isUpdateAvailable ? '⚠️ ' : '';
+	const statusTextColor = isUpToDate ? 'white' : 'black';
+	const statusBackgroundColor = isUpToDate ? undefined : 'yellow';
+	const isCheckingLabelVisible = isSchemaCheckInProgress || isCodexChecking;
+	const versionText = isCheckingLabelVisible
+		? ` ${isSchemaCheckInProgress ? schemaStatus : codexStatusText} `
+		: `Using Codex ${formatCodexVersion(codexVersion)}`;
+	const versionTextColor = isCheckingLabelVisible
+		? CHECKING_BADGE_TEXT_COLOR
+		: 'white';
+	const versionTextBackgroundColor = isCheckingLabelVisible
+		? CHECKING_BADGE_BACKGROUND_COLOR
+		: undefined;
+	const codexStatusTextLabel = `${statusText} `;
 	const activeFileSummary = formatActiveFileSummary(activeConfigFile);
 
 	return React.createElement(
@@ -47,34 +86,38 @@ export const StatusLine = ({
 			{ flexDirection: 'row', gap: 2 },
 			React.createElement(
 				Text,
-				{ color: 'white' },
-				`Codex installed: ${codexVersion || '—'}`,
+				{
+					color: versionTextColor,
+					backgroundColor: versionTextBackgroundColor,
+					bold: isCheckingLabelVisible,
+				},
+				versionText,
 			),
-			React.createElement(
-				Box,
-				{ flexDirection: 'row' },
-				statusPrefix
-					? React.createElement(
+			shouldShowCodexStatus
+				? React.createElement(
+						Box,
+						{ flexDirection: 'row' },
+						statusPrefix
+							? React.createElement(
+									Text,
+									{
+										color: statusTextColor,
+										backgroundColor: statusBackgroundColor,
+									},
+									` ${statusPrefix} `,
+								)
+							: null,
+						React.createElement(
 							Text,
 							{
-								color: isUpToDate ? 'white' : 'black',
-								backgroundColor: isUpToDate
-									? undefined
-									: 'yellow',
+								color: statusTextColor,
+								backgroundColor: statusBackgroundColor,
+								bold: true,
 							},
-							` ${statusPrefix} `,
-						)
-					: null,
-				React.createElement(
-					Text,
-					{
-						color: isUpToDate ? 'white' : 'black',
-						backgroundColor: isUpToDate ? undefined : 'yellow',
-						bold: true,
-					},
-					`${statusText} `,
-				),
-			),
+							codexStatusTextLabel,
+						),
+					)
+				: null,
 		),
 	);
 };