feat: clean config loading and config api (#7924)

Check the README of the `config_loader` for details

codex-rs/core/src/config_loader/README.md

@@ -0,0 +1,64 @@
+# `codex-core` config loader
+
+This module is the canonical place to **load and describe Codex configuration layers** (user config, CLI/session overrides, managed config, and MDM-managed preferences) and to produce:
+
+- An **effective merged** TOML config.
+- **Per-key origins** metadata (which layer “wins” for a given key).
+- **Per-layer versions** (stable fingerprints) used for optimistic concurrency / conflict detection.
+
+## Public surface
+
+Exported from `codex_core::config_loader`:
+
+- `load_config_layers_state(codex_home, cli_overrides, overrides) -> ConfigLayerStack`
+- `ConfigLayerStack`
+  - `effective_config() -> toml::Value`
+  - `origins() -> HashMap<String, ConfigLayerMetadata>`
+  - `layers_high_to_low() -> Vec<ConfigLayer>`
+  - `with_user_config(user_config) -> ConfigLayerStack`
+- `ConfigLayerEntry` (one layer’s `{name, source, config, version}`)
+- `LoaderOverrides` (test/override hooks for managed config sources)
+- `merge_toml_values(base, overlay)` (public helper used elsewhere)
+
+## Layering model
+
+Precedence is **top overrides bottom**:
+
+1. **MDM** managed preferences (macOS only)
+2. **System** managed config (e.g. `managed_config.toml`)
+3. **Session flags** (CLI overrides, applied as dotted-path TOML writes)
+4. **User** config (`config.toml`)
+
+This is what `ConfigLayerStack::effective_config()` implements.
+
+## Typical usage
+
+Most callers want the effective config plus metadata:
+
+```rust
+use codex_core::config_loader::{load_config_layers_state, LoaderOverrides};
+use toml::Value as TomlValue;
+
+let cli_overrides: Vec<(String, TomlValue)> = Vec::new();
+let layers = load_config_layers_state(
+    &codex_home,
+    &cli_overrides,
+    LoaderOverrides::default(),
+).await?;
+
+let effective = layers.effective_config();
+let origins = layers.origins();
+let layers_for_ui = layers.layers_high_to_low();
+```
+
+## Internal layout
+
+Implementation is split by concern:
+
+- `state.rs`: public types (`ConfigLayerEntry`, `ConfigLayerStack`) + merge/origins convenience methods.
+- `layer_io.rs`: reading `config.toml`, managed config, and managed preferences inputs.
+- `overrides.rs`: CLI dotted-path overrides → TOML “session flags” layer.
+- `merge.rs`: recursive TOML merge.
+- `fingerprint.rs`: stable per-layer hashing and per-key origins traversal.
+- `macos.rs`: managed preferences integration (macOS only).
+

codex-rs/core/src/config_loader/fingerprint.rs

@@ -0,0 +1,67 @@
+use codex_app_server_protocol::ConfigLayerMetadata;
+use serde_json::Value as JsonValue;
+use sha2::Digest;
+use sha2::Sha256;
+use std::collections::HashMap;
+use toml::Value as TomlValue;
+
+pub(super) fn record_origins(
+    value: &TomlValue,
+    meta: &ConfigLayerMetadata,
+    path: &mut Vec<String>,
+    origins: &mut HashMap<String, ConfigLayerMetadata>,
+) {
+    match value {
+        TomlValue::Table(table) => {
+            for (key, val) in table {
+                path.push(key.clone());
+                record_origins(val, meta, path, origins);
+                path.pop();
+            }
+        }
+        TomlValue::Array(items) => {
+            for (idx, item) in (0_i32..).zip(items.iter()) {
+                path.push(idx.to_string());
+                record_origins(item, meta, path, origins);
+                path.pop();
+            }
+        }
+        _ => {
+            if !path.is_empty() {
+                origins.insert(path.join("."), meta.clone());
+            }
+        }
+    }
+}
+
+pub(super) fn version_for_toml(value: &TomlValue) -> String {
+    let json = serde_json::to_value(value).unwrap_or(JsonValue::Null);
+    let canonical = canonical_json(&json);
+    let serialized = serde_json::to_vec(&canonical).unwrap_or_default();
+    let mut hasher = Sha256::new();
+    hasher.update(serialized);
+    let hash = hasher.finalize();
+    let hex = hash
+        .iter()
+        .map(|byte| format!("{byte:02x}"))
+        .collect::<String>();
+    format!("sha256:{hex}")
+}
+
+fn canonical_json(value: &JsonValue) -> JsonValue {
+    match value {
+        JsonValue::Object(map) => {
+            let mut sorted = serde_json::Map::new();
+            let mut keys = map.keys().cloned().collect::<Vec<_>>();
+            keys.sort();
+            for key in keys {
+                if let Some(val) = map.get(&key) {
+                    sorted.insert(key, canonical_json(val));
+                }
+            }
+            JsonValue::Object(sorted)
+        }
+        JsonValue::Array(items) => JsonValue::Array(items.iter().map(canonical_json).collect()),
+        other => other.clone(),
+    }
+}

codex-rs/core/src/config_loader/layer_io.rs

@@ -0,0 +1,100 @@
+use super::LoaderOverrides;
+use super::macos::load_managed_admin_config_layer;
+use super::overrides::default_empty_table;
+use crate::config::CONFIG_TOML_FILE;
+use std::io;
+use std::path::Path;
+use std::path::PathBuf;
+use tokio::fs;
+use toml::Value as TomlValue;
+
+#[cfg(unix)]
+const CODEX_MANAGED_CONFIG_SYSTEM_PATH: &str = "/etc/codex/managed_config.toml";
+
+#[derive(Debug, Clone)]
+pub(super) struct LoadedConfigLayers {
+    pub base: TomlValue,
+    pub managed_config: Option<TomlValue>,
+    pub managed_preferences: Option<TomlValue>,
+}
+
+pub(super) async fn load_config_layers_internal(
+    codex_home: &Path,
+    overrides: LoaderOverrides,
+) -> io::Result<LoadedConfigLayers> {
+    #[cfg(target_os = "macos")]
+    let LoaderOverrides {
+        managed_config_path,
+        managed_preferences_base64,
+    } = overrides;
+
+    #[cfg(not(target_os = "macos"))]
+    let LoaderOverrides {
+        managed_config_path,
+    } = overrides;
+
+    let managed_config_path =
+        managed_config_path.unwrap_or_else(|| managed_config_default_path(codex_home));
+
+    let user_config_path = codex_home.join(CONFIG_TOML_FILE);
+    let user_config = read_config_from_path(&user_config_path, true).await?;
+    let managed_config = read_config_from_path(&managed_config_path, false).await?;
+
+    #[cfg(target_os = "macos")]
+    let managed_preferences =
+        load_managed_admin_config_layer(managed_preferences_base64.as_deref()).await?;
+
+    #[cfg(not(target_os = "macos"))]
+    let managed_preferences = load_managed_admin_config_layer(None).await?;
+
+    Ok(LoadedConfigLayers {
+        base: user_config.unwrap_or_else(default_empty_table),
+        managed_config,
+        managed_preferences,
+    })
+}
+
+pub(super) async fn read_config_from_path(
+    path: &Path,
+    log_missing_as_info: bool,
+) -> io::Result<Option<TomlValue>> {
+    match fs::read_to_string(path).await {
+        Ok(contents) => match toml::from_str::<TomlValue>(&contents) {
+            Ok(value) => Ok(Some(value)),
+            Err(err) => {
+                tracing::error!("Failed to parse {}: {err}", path.display());
+                Err(io::Error::new(io::ErrorKind::InvalidData, err))
+            }
+        },
+        Err(err) if err.kind() == io::ErrorKind::NotFound => {
+            if log_missing_as_info {
+                tracing::info!("{} not found, using defaults", path.display());
+            } else {
+                tracing::debug!("{} not found", path.display());
+            }
+            Ok(None)
+        }
+        Err(err) => {
+            tracing::error!("Failed to read {}: {err}", path.display());
+            Err(err)
+        }
+    }
+}
+
+/// Return the default managed config path (honoring `CODEX_MANAGED_CONFIG_PATH`).
+pub(super) fn managed_config_default_path(codex_home: &Path) -> PathBuf {
+    if let Ok(path) = std::env::var("CODEX_MANAGED_CONFIG_PATH") {
+        return PathBuf::from(path);
+    }
+
+    #[cfg(unix)]
+    {
+        let _ = codex_home;
+        PathBuf::from(CODEX_MANAGED_CONFIG_SYSTEM_PATH)
+    }
+
+    #[cfg(not(unix))]
+    {
+        codex_home.join("managed_config.toml")
+    }
+}

codex-rs/core/src/config_loader/merge.rs

@@ -0,0 +1,18 @@
+use toml::Value as TomlValue;
+
+/// Merge config `overlay` into `base`, giving `overlay` precedence.
+pub fn merge_toml_values(base: &mut TomlValue, overlay: &TomlValue) {
+    if let TomlValue::Table(overlay_table) = overlay
+        && let TomlValue::Table(base_table) = base
+    {
+        for (key, value) in overlay_table {
+            if let Some(existing) = base_table.get_mut(key) {
+                merge_toml_values(existing, value);
+            } else {
+                base_table.insert(key.clone(), value.clone());
+            }
+        }
+    } else {
+        *base = overlay.clone();
+    }
+}

codex-rs/core/src/config_loader/mod.rs

@@ -1,319 +1,74 @@
+mod fingerprint;
+mod layer_io;
 mod macos;
+mod merge;
+mod overrides;
+mod state;
+
+#[cfg(test)]
+mod tests;
 
 use crate::config::CONFIG_TOML_FILE;
-use macos::load_managed_admin_config_layer;
+use codex_app_server_protocol::ConfigLayerName;
 use std::io;
 use std::path::Path;
 use std::path::PathBuf;
-use tokio::fs;
 use toml::Value as TomlValue;
 
-#[cfg(unix)]
-const CODEX_MANAGED_CONFIG_SYSTEM_PATH: &str = "/etc/codex/managed_config.toml";
+pub use merge::merge_toml_values;
+pub use state::ConfigLayerEntry;
+pub use state::ConfigLayerStack;
+pub use state::LoaderOverrides;
 
-#[derive(Debug, Clone)]
-pub struct LoadedConfigLayers {
-    pub base: TomlValue,
-    pub managed_config: Option<TomlValue>,
-    pub managed_preferences: Option<TomlValue>,
-}
+const SESSION_FLAGS_SOURCE: &str = "--config";
+const MDM_SOURCE: &str = "com.openai.codex/config_toml_base64";
 
-#[derive(Debug, Default, Clone)]
-pub struct LoaderOverrides {
-    pub managed_config_path: Option<PathBuf>,
-    #[cfg(target_os = "macos")]
-    pub managed_preferences_base64: Option<String>,
-}
-
-// Configuration layering pipeline (top overrides bottom):
-//
-//        +-------------------------+
-//        | Managed preferences (*) |
-//        +-------------------------+
-//                    ^
-//                    |
-//        +-------------------------+
-//        |  managed_config.toml   |
-//        +-------------------------+
-//                    ^
-//                    |
-//        +-------------------------+
-//        |    config.toml (base)   |
-//        +-------------------------+
-//
-// (*) Only available on macOS via managed device profiles.
-
-pub async fn load_config_as_toml(codex_home: &Path) -> io::Result<TomlValue> {
-    load_config_as_toml_with_overrides(codex_home, LoaderOverrides::default()).await
-}
-
-pub async fn load_config_layers(codex_home: &Path) -> io::Result<LoadedConfigLayers> {
-    load_config_layers_with_overrides(codex_home, LoaderOverrides::default()).await
-}
-
-fn default_empty_table() -> TomlValue {
-    TomlValue::Table(Default::default())
-}
-
-pub async fn load_config_layers_with_overrides(
+/// Configuration layering pipeline (top overrides bottom):
+///
+///        +-------------------------+
+///        | Managed preferences (*) |
+///        +-------------------------+
+///                    ^
+///                    |
+///        +-------------------------+
+///        |  managed_config.toml   |
+///        +-------------------------+
+///                    ^
+///                    |
+///        +-------------------------+
+///        |    config.toml (base)   |
+///        +-------------------------+
+///
+/// (*) Only available on macOS via managed device profiles.
+pub async fn load_config_layers_state(
     codex_home: &Path,
+    cli_overrides: &[(String, TomlValue)],
     overrides: LoaderOverrides,
-) -> io::Result<LoadedConfigLayers> {
-    load_config_layers_internal(codex_home, overrides).await
-}
+) -> io::Result<ConfigLayerStack> {
+    let managed_config_path = overrides
+        .managed_config_path
+        .clone()
+        .unwrap_or_else(|| layer_io::managed_config_default_path(codex_home));
 
-async fn load_config_as_toml_with_overrides(
-    codex_home: &Path,
-    overrides: LoaderOverrides,
-) -> io::Result<TomlValue> {
-    let layers = load_config_layers_internal(codex_home, overrides).await?;
-    Ok(apply_managed_layers(layers))
-}
+    let layers = layer_io::load_config_layers_internal(codex_home, overrides).await?;
+    let cli_overrides = overrides::build_cli_overrides_layer(cli_overrides);
 
-async fn load_config_layers_internal(
-    codex_home: &Path,
-    overrides: LoaderOverrides,
-) -> io::Result<LoadedConfigLayers> {
-    #[cfg(target_os = "macos")]
-    let LoaderOverrides {
-        managed_config_path,
-        managed_preferences_base64,
-    } = overrides;
-
-    #[cfg(not(target_os = "macos"))]
-    let LoaderOverrides {
-        managed_config_path,
-    } = overrides;
-
-    let managed_config_path =
-        managed_config_path.unwrap_or_else(|| managed_config_default_path(codex_home));
-
-    let user_config_path = codex_home.join(CONFIG_TOML_FILE);
-    let user_config = read_config_from_path(&user_config_path, true).await?;
-    let managed_config = read_config_from_path(&managed_config_path, false).await?;
-
-    #[cfg(target_os = "macos")]
-    let managed_preferences =
-        load_managed_admin_config_layer(managed_preferences_base64.as_deref()).await?;
-
-    #[cfg(not(target_os = "macos"))]
-    let managed_preferences = load_managed_admin_config_layer(None).await?;
-
-    Ok(LoadedConfigLayers {
-        base: user_config.unwrap_or_else(default_empty_table),
-        managed_config,
-        managed_preferences,
+    Ok(ConfigLayerStack {
+        user: ConfigLayerEntry::new(
+            ConfigLayerName::User,
+            codex_home.join(CONFIG_TOML_FILE),
+            layers.base,
+        ),
+        session_flags: ConfigLayerEntry::new(
+            ConfigLayerName::SessionFlags,
+            PathBuf::from(SESSION_FLAGS_SOURCE),
+            cli_overrides,
+        ),
+        system: layers.managed_config.map(|cfg| {
+            ConfigLayerEntry::new(ConfigLayerName::System, managed_config_path.clone(), cfg)
+        }),
+        mdm: layers
+            .managed_preferences
+            .map(|cfg| ConfigLayerEntry::new(ConfigLayerName::Mdm, PathBuf::from(MDM_SOURCE), cfg)),
     })
 }
-
-async fn read_config_from_path(
-    path: &Path,
-    log_missing_as_info: bool,
-) -> io::Result<Option<TomlValue>> {
-    match fs::read_to_string(path).await {
-        Ok(contents) => match toml::from_str::<TomlValue>(&contents) {
-            Ok(value) => Ok(Some(value)),
-            Err(err) => {
-                tracing::error!("Failed to parse {}: {err}", path.display());
-                Err(io::Error::new(io::ErrorKind::InvalidData, err))
-            }
-        },
-        Err(err) if err.kind() == io::ErrorKind::NotFound => {
-            if log_missing_as_info {
-                tracing::info!("{} not found, using defaults", path.display());
-            } else {
-                tracing::debug!("{} not found", path.display());
-            }
-            Ok(None)
-        }
-        Err(err) => {
-            tracing::error!("Failed to read {}: {err}", path.display());
-            Err(err)
-        }
-    }
-}
-
-/// Merge config `overlay` into `base`, giving `overlay` precedence.
-pub fn merge_toml_values(base: &mut TomlValue, overlay: &TomlValue) {
-    if let TomlValue::Table(overlay_table) = overlay
-        && let TomlValue::Table(base_table) = base
-    {
-        for (key, value) in overlay_table {
-            if let Some(existing) = base_table.get_mut(key) {
-                merge_toml_values(existing, value);
-            } else {
-                base_table.insert(key.clone(), value.clone());
-            }
-        }
-    } else {
-        *base = overlay.clone();
-    }
-}
-
-fn managed_config_default_path(codex_home: &Path) -> PathBuf {
-    if let Ok(path) = std::env::var("CODEX_MANAGED_CONFIG_PATH") {
-        return PathBuf::from(path);
-    }
-
-    #[cfg(unix)]
-    {
-        let _ = codex_home;
-        PathBuf::from(CODEX_MANAGED_CONFIG_SYSTEM_PATH)
-    }
-
-    #[cfg(not(unix))]
-    {
-        codex_home.join("managed_config.toml")
-    }
-}
-
-fn apply_managed_layers(layers: LoadedConfigLayers) -> TomlValue {
-    let LoadedConfigLayers {
-        mut base,
-        managed_config,
-        managed_preferences,
-    } = layers;
-
-    for overlay in [managed_config, managed_preferences].into_iter().flatten() {
-        merge_toml_values(&mut base, &overlay);
-    }
-
-    base
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use tempfile::tempdir;
-
-    #[tokio::test]
-    async fn merges_managed_config_layer_on_top() {
-        let tmp = tempdir().expect("tempdir");
-        let managed_path = tmp.path().join("managed_config.toml");
-
-        std::fs::write(
-            tmp.path().join(CONFIG_TOML_FILE),
-            r#"foo = 1
-
-[nested]
-value = "base"
-"#,
-        )
-        .expect("write base");
-        std::fs::write(
-            &managed_path,
-            r#"foo = 2
-
-[nested]
-value = "managed_config"
-extra = true
-"#,
-        )
-        .expect("write managed config");
-
-        let overrides = LoaderOverrides {
-            managed_config_path: Some(managed_path),
-            #[cfg(target_os = "macos")]
-            managed_preferences_base64: None,
-        };
-
-        let loaded = load_config_as_toml_with_overrides(tmp.path(), overrides)
-            .await
-            .expect("load config");
-        let table = loaded.as_table().expect("top-level table expected");
-
-        assert_eq!(table.get("foo"), Some(&TomlValue::Integer(2)));
-        let nested = table
-            .get("nested")
-            .and_then(|v| v.as_table())
-            .expect("nested");
-        assert_eq!(
-            nested.get("value"),
-            Some(&TomlValue::String("managed_config".to_string()))
-        );
-        assert_eq!(nested.get("extra"), Some(&TomlValue::Boolean(true)));
-    }
-
-    #[tokio::test]
-    async fn returns_empty_when_all_layers_missing() {
-        let tmp = tempdir().expect("tempdir");
-        let managed_path = tmp.path().join("managed_config.toml");
-        let overrides = LoaderOverrides {
-            managed_config_path: Some(managed_path),
-            #[cfg(target_os = "macos")]
-            managed_preferences_base64: None,
-        };
-
-        let layers = load_config_layers_with_overrides(tmp.path(), overrides)
-            .await
-            .expect("load layers");
-        let base_table = layers.base.as_table().expect("base table expected");
-        assert!(
-            base_table.is_empty(),
-            "expected empty base layer when configs missing"
-        );
-        assert!(
-            layers.managed_config.is_none(),
-            "managed config layer should be absent when file missing"
-        );
-
-        #[cfg(not(target_os = "macos"))]
-        {
-            let loaded = load_config_as_toml(tmp.path()).await.expect("load config");
-            let table = loaded.as_table().expect("top-level table expected");
-            assert!(
-                table.is_empty(),
-                "expected empty table when configs missing"
-            );
-        }
-    }
-
-    #[cfg(target_os = "macos")]
-    #[tokio::test]
-    async fn managed_preferences_take_highest_precedence() {
-        use base64::Engine;
-
-        let managed_payload = r#"
-[nested]
-value = "managed"
-flag = false
-"#;
-        let encoded = base64::prelude::BASE64_STANDARD.encode(managed_payload.as_bytes());
-        let tmp = tempdir().expect("tempdir");
-        let managed_path = tmp.path().join("managed_config.toml");
-
-        std::fs::write(
-            tmp.path().join(CONFIG_TOML_FILE),
-            r#"[nested]
-value = "base"
-"#,
-        )
-        .expect("write base");
-        std::fs::write(
-            &managed_path,
-            r#"[nested]
-value = "managed_config"
-flag = true
-"#,
-        )
-        .expect("write managed config");
-
-        let overrides = LoaderOverrides {
-            managed_config_path: Some(managed_path),
-            managed_preferences_base64: Some(encoded),
-        };
-
-        let loaded = load_config_as_toml_with_overrides(tmp.path(), overrides)
-            .await
-            .expect("load config");
-        let nested = loaded
-            .get("nested")
-            .and_then(|v| v.as_table())
-            .expect("nested table");
-        assert_eq!(
-            nested.get("value"),
-            Some(&TomlValue::String("managed".to_string()))
-        );
-        assert_eq!(nested.get("flag"), Some(&TomlValue::Boolean(false)));
-    }
-}

codex-rs/core/src/config_loader/overrides.rs

@@ -0,0 +1,55 @@
+use toml::Value as TomlValue;
+
+pub(super) fn default_empty_table() -> TomlValue {
+    TomlValue::Table(Default::default())
+}
+
+pub(super) fn build_cli_overrides_layer(cli_overrides: &[(String, TomlValue)]) -> TomlValue {
+    let mut root = default_empty_table();
+    for (path, value) in cli_overrides {
+        apply_toml_override(&mut root, path, value.clone());
+    }
+    root
+}
+
+/// Apply a single dotted-path override onto a TOML value.
+fn apply_toml_override(root: &mut TomlValue, path: &str, value: TomlValue) {
+    use toml::value::Table;
+
+    let mut current = root;
+    let mut segments_iter = path.split('.').peekable();
+
+    while let Some(segment) = segments_iter.next() {
+        let is_last = segments_iter.peek().is_none();
+
+        if is_last {
+            match current {
+                TomlValue::Table(table) => {
+                    table.insert(segment.to_string(), value);
+                }
+                _ => {
+                    let mut table = Table::new();
+                    table.insert(segment.to_string(), value);
+                    *current = TomlValue::Table(table);
+                }
+            }
+            return;
+        }
+
+        match current {
+            TomlValue::Table(table) => {
+                current = table
+                    .entry(segment.to_string())
+                    .or_insert_with(|| TomlValue::Table(Table::new()));
+            }
+            _ => {
+                *current = TomlValue::Table(Table::new());
+                if let TomlValue::Table(tbl) = current {
+                    current = tbl
+                        .entry(segment.to_string())
+                        .or_insert_with(|| TomlValue::Table(Table::new()));
+                }
+            }
+        }
+    }
+}

codex-rs/core/src/config_loader/state.rs

@@ -0,0 +1,128 @@
+use super::fingerprint::record_origins;
+use super::fingerprint::version_for_toml;
+use super::merge::merge_toml_values;
+use codex_app_server_protocol::ConfigLayer;
+use codex_app_server_protocol::ConfigLayerMetadata;
+use codex_app_server_protocol::ConfigLayerName;
+use serde_json::Value as JsonValue;
+use std::collections::HashMap;
+use std::path::PathBuf;
+use toml::Value as TomlValue;
+
+#[derive(Debug, Default, Clone)]
+pub struct LoaderOverrides {
+    pub managed_config_path: Option<PathBuf>,
+    #[cfg(target_os = "macos")]
+    pub managed_preferences_base64: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ConfigLayerEntry {
+    pub name: ConfigLayerName,
+    pub source: PathBuf,
+    pub config: TomlValue,
+    pub version: String,
+}
+
+impl ConfigLayerEntry {
+    pub fn new(name: ConfigLayerName, source: PathBuf, config: TomlValue) -> Self {
+        let version = version_for_toml(&config);
+        Self {
+            name,
+            source,
+            config,
+            version,
+        }
+    }
+
+    pub fn metadata(&self) -> ConfigLayerMetadata {
+        ConfigLayerMetadata {
+            name: self.name.clone(),
+            source: self.source.display().to_string(),
+            version: self.version.clone(),
+        }
+    }
+
+    pub fn as_layer(&self) -> ConfigLayer {
+        ConfigLayer {
+            name: self.name.clone(),
+            source: self.source.display().to_string(),
+            version: self.version.clone(),
+            config: serde_json::to_value(&self.config).unwrap_or(JsonValue::Null),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct ConfigLayerStack {
+    pub user: ConfigLayerEntry,
+    pub session_flags: ConfigLayerEntry,
+    pub system: Option<ConfigLayerEntry>,
+    pub mdm: Option<ConfigLayerEntry>,
+}
+
+impl ConfigLayerStack {
+    pub fn with_user_config(&self, user_config: TomlValue) -> Self {
+        Self {
+            user: ConfigLayerEntry::new(
+                self.user.name.clone(),
+                self.user.source.clone(),
+                user_config,
+            ),
+            session_flags: self.session_flags.clone(),
+            system: self.system.clone(),
+            mdm: self.mdm.clone(),
+        }
+    }
+
+    pub fn effective_config(&self) -> TomlValue {
+        let mut merged = self.user.config.clone();
+        merge_toml_values(&mut merged, &self.session_flags.config);
+        if let Some(system) = &self.system {
+            merge_toml_values(&mut merged, &system.config);
+        }
+        if let Some(mdm) = &self.mdm {
+            merge_toml_values(&mut merged, &mdm.config);
+        }
+        merged
+    }
+
+    pub fn origins(&self) -> HashMap<String, ConfigLayerMetadata> {
+        let mut origins = HashMap::new();
+        let mut path = Vec::new();
+
+        record_origins(
+            &self.user.config,
+            &self.user.metadata(),
+            &mut path,
+            &mut origins,
+        );
+        record_origins(
+            &self.session_flags.config,
+            &self.session_flags.metadata(),
+            &mut path,
+            &mut origins,
+        );
+        if let Some(system) = &self.system {
+            record_origins(&system.config, &system.metadata(), &mut path, &mut origins);
+        }
+        if let Some(mdm) = &self.mdm {
+            record_origins(&mdm.config, &mdm.metadata(), &mut path, &mut origins);
+        }
+
+        origins
+    }
+
+    pub fn layers_high_to_low(&self) -> Vec<ConfigLayer> {
+        let mut layers = Vec::new();
+        if let Some(mdm) = &self.mdm {
+            layers.push(mdm.as_layer());
+        }
+        if let Some(system) = &self.system {
+            layers.push(system.as_layer());
+        }
+        layers.push(self.session_flags.as_layer());
+        layers.push(self.user.as_layer());
+        layers
+    }
+}

codex-rs/core/src/config_loader/tests.rs

@@ -0,0 +1,138 @@
+use super::LoaderOverrides;
+use super::load_config_layers_state;
+use crate::config::CONFIG_TOML_FILE;
+use tempfile::tempdir;
+use toml::Value as TomlValue;
+
+#[tokio::test]
+async fn merges_managed_config_layer_on_top() {
+    let tmp = tempdir().expect("tempdir");
+    let managed_path = tmp.path().join("managed_config.toml");
+
+    std::fs::write(
+        tmp.path().join(CONFIG_TOML_FILE),
+        r#"foo = 1
+
+[nested]
+value = "base"
+"#,
+    )
+    .expect("write base");
+    std::fs::write(
+        &managed_path,
+        r#"foo = 2
+
+[nested]
+value = "managed_config"
+extra = true
+"#,
+    )
+    .expect("write managed config");
+
+    let overrides = LoaderOverrides {
+        managed_config_path: Some(managed_path),
+        #[cfg(target_os = "macos")]
+        managed_preferences_base64: None,
+    };
+
+    let state = load_config_layers_state(tmp.path(), &[] as &[(String, TomlValue)], overrides)
+        .await
+        .expect("load config");
+    let loaded = state.effective_config();
+    let table = loaded.as_table().expect("top-level table expected");
+
+    assert_eq!(table.get("foo"), Some(&TomlValue::Integer(2)));
+    let nested = table
+        .get("nested")
+        .and_then(|v| v.as_table())
+        .expect("nested");
+    assert_eq!(
+        nested.get("value"),
+        Some(&TomlValue::String("managed_config".to_string()))
+    );
+    assert_eq!(nested.get("extra"), Some(&TomlValue::Boolean(true)));
+}
+
+#[tokio::test]
+async fn returns_empty_when_all_layers_missing() {
+    let tmp = tempdir().expect("tempdir");
+    let managed_path = tmp.path().join("managed_config.toml");
+    let overrides = LoaderOverrides {
+        managed_config_path: Some(managed_path),
+        #[cfg(target_os = "macos")]
+        managed_preferences_base64: None,
+    };
+
+    let layers = load_config_layers_state(tmp.path(), &[] as &[(String, TomlValue)], overrides)
+        .await
+        .expect("load layers");
+    let base_table = layers.user.config.as_table().expect("base table expected");
+    assert!(
+        base_table.is_empty(),
+        "expected empty base layer when configs missing"
+    );
+    assert!(
+        layers.system.is_none(),
+        "managed config layer should be absent when file missing"
+    );
+
+    #[cfg(not(target_os = "macos"))]
+    {
+        let effective = layers.effective_config();
+        let table = effective.as_table().expect("top-level table expected");
+        assert!(
+            table.is_empty(),
+            "expected empty table when configs missing"
+        );
+    }
+}
+
+#[cfg(target_os = "macos")]
+#[tokio::test]
+async fn managed_preferences_take_highest_precedence() {
+    use base64::Engine;
+
+    let managed_payload = r#"
+[nested]
+value = "managed"
+flag = false
+"#;
+    let encoded = base64::prelude::BASE64_STANDARD.encode(managed_payload.as_bytes());
+    let tmp = tempdir().expect("tempdir");
+    let managed_path = tmp.path().join("managed_config.toml");
+
+    std::fs::write(
+        tmp.path().join(CONFIG_TOML_FILE),
+        r#"[nested]
+value = "base"
+"#,
+    )
+    .expect("write base");
+    std::fs::write(
+        &managed_path,
+        r#"[nested]
+value = "managed_config"
+flag = true
+"#,
+    )
+    .expect("write managed config");
+
+    let overrides = LoaderOverrides {
+        managed_config_path: Some(managed_path),
+        managed_preferences_base64: Some(encoded),
+    };
+
+    let state = load_config_layers_state(tmp.path(), &[] as &[(String, TomlValue)], overrides)
+        .await
+        .expect("load config");
+    let loaded = state.effective_config();
+    let nested = loaded
+        .get("nested")
+        .and_then(|v| v.as_table())
+        .expect("nested table");
+    assert_eq!(
+        nested.get("value"),
+        Some(&TomlValue::String("managed".to_string()))
+    );
+    assert_eq!(nested.get("flag"), Some(&TomlValue::Boolean(false)));
+}