Move installation ID resolution out of core startup (#21182)

## Summary

- resolve or inject the installation ID before core startup and pass it
through `ThreadManager`, `CodexSpawnArgs`, and `Session` as a plain
`String`
- keep child sessions on the parent installation ID instead of
rediscovering it inside core
- propagate installation ID startup failures in `mcp-server` instead of
panicking

## Why

Core was still touching the filesystem on the session startup path to
discover `installation_id`. This moves that work to the outer host
boundary so core no longer depends on `codex_home` reads during session
construction.

---------

Co-authored-by: Codex <noreply@openai.com>

codex-rs/core/src/codex_delegate.rs

@@ -76,6 +76,7 @@ pub(crate) async fn run_codex_thread_interactive(
     let (tx_ops, rx_ops) = async_channel::bounded(SUBMISSION_CHANNEL_CAPACITY);
     let CodexSpawnOk { codex, .. } = Box::pin(Codex::spawn(CodexSpawnArgs {
         config,
+        installation_id: parent_session.installation_id.clone(),
         auth_manager,
         models_manager,
         environment_manager: Arc::clone(&parent_session.services.environment_manager),

codex-rs/core/src/prompt_debug.rs

@@ -13,6 +13,7 @@ use codex_protocol::user_input::UserInput;
 use tokio_util::sync::CancellationToken;
 
 use crate::config::Config;
+use crate::resolve_installation_id;
 use crate::session::session::Session;
 use crate::session::turn::build_prompt;
 use crate::session::turn::built_tools;
@@ -42,6 +43,7 @@ pub async fn build_prompt_input(
         .ok_or_else(|| std::io::Error::other("prompt debug requires state db"))?;
     let thread_store = thread_store_from_config(&config, state_db.clone());
     let agent_graph_store = agent_graph_store_from_state_db(state_db.clone());
+    let installation_id = resolve_installation_id(&config.codex_home).await?;
     let thread_manager = ThreadManager::new(
         &config,
         Arc::clone(&auth_manager),
@@ -51,6 +53,7 @@ pub async fn build_prompt_input(
         state_db,
         thread_store,
         agent_graph_store,
+        installation_id,
     );
     let thread = thread_manager.start_thread(config).await?;
 

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

@@ -32,7 +32,6 @@ use crate::context::PersonalitySpecInstructions;
 use crate::default_skill_metadata_budget;
 use crate::environment_selection::ResolvedTurnEnvironments;
 use crate::exec_policy::ExecPolicyManager;
-use crate::installation_id::resolve_installation_id;
 use crate::parse_turn_item;
 use crate::path_utils::normalize_for_native_workdir;
 use crate::realtime_conversation::RealtimeConversationManager;
@@ -384,6 +383,7 @@ pub struct CodexSpawnOk {
 
 pub(crate) struct CodexSpawnArgs {
     pub(crate) config: Config,
+    pub(crate) installation_id: String,
     pub(crate) auth_manager: Arc<AuthManager>,
     pub(crate) models_manager: SharedModelsManager,
     pub(crate) environment_manager: Arc<EnvironmentManager>,
@@ -447,6 +447,7 @@ impl Codex {
     async fn spawn_internal(args: CodexSpawnArgs) -> CodexResult<CodexSpawnOk> {
         let CodexSpawnArgs {
             mut config,
+            installation_id,
             auth_manager,
             models_manager,
             environment_manager,
@@ -630,6 +631,7 @@ impl Codex {
         let session = Session::new(
             session_configuration,
             config.clone(),
+            installation_id,
             auth_manager.clone(),
             models_manager.clone(),
             exec_policy,

codex-rs/core/src/session/session.rs

@@ -12,6 +12,7 @@ use tokio::sync::Semaphore;
 /// A session has at most 1 running task at a time, and can be interrupted by user input.
 pub(crate) struct Session {
     pub(crate) conversation_id: ThreadId,
+    pub(crate) installation_id: String,
     pub(super) tx_event: Sender<Event>,
     pub(super) agent_status: watch::Sender<AgentStatus>,
     pub(super) out_of_band_elicitation_paused: watch::Sender<bool>,
@@ -344,6 +345,7 @@ impl Session {
     pub(crate) async fn new(
         mut session_configuration: SessionConfiguration,
         config: Arc<Config>,
+        installation_id: String,
         auth_manager: Arc<AuthManager>,
         models_manager: SharedModelsManager,
         exec_policy: Arc<ExecPolicyManager>,
@@ -789,7 +791,6 @@ impl Session {
                 });
             }
 
-            let installation_id = resolve_installation_id(&config.codex_home).await?;
             let analytics_events_client = analytics_events_client.unwrap_or_else(|| {
                 AnalyticsEventsClient::new(
                     Arc::clone(&auth_manager),
@@ -849,7 +850,7 @@ impl Session {
                     Some(Arc::clone(&auth_manager)),
                     session_id,
                     thread_id,
-                    installation_id,
+                    installation_id.clone(),
                     session_configuration.provider.clone(),
                     session_configuration.session_source.clone(),
                     config.model_verbosity,
@@ -869,6 +870,7 @@ impl Session {
             let (mailbox, mailbox_rx) = Mailbox::new();
             let sess = Arc::new(Session {
                 conversation_id: thread_id,
+                installation_id,
                 tx_event: tx_event.clone(),
                 agent_status,
                 out_of_band_elicitation_paused,

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

@@ -3566,6 +3566,7 @@ async fn session_new_fails_when_zsh_fork_enabled_without_zsh_path() {
     let result = Session::new(
         session_configuration,
         Arc::clone(&config),
+        "11111111-1111-4111-8111-111111111111".to_string(),
         auth_manager,
         models_manager,
         Arc::new(ExecPolicyManager::default()),
@@ -3799,6 +3800,7 @@ pub(crate) async fn make_session_and_context() -> (Session, TurnContext) {
     let (mailbox, mailbox_rx) = crate::agent::Mailbox::new();
     let session = Session {
         conversation_id: thread_id,
+        installation_id: "11111111-1111-4111-8111-111111111111".to_string(),
         tx_event,
         agent_status: agent_status_tx,
         out_of_band_elicitation_paused: watch::channel(false).0,
@@ -3905,6 +3907,7 @@ async fn make_session_with_config_and_rx(
     let session = Session::new(
         session_configuration,
         Arc::clone(&config),
+        "11111111-1111-4111-8111-111111111111".to_string(),
         auth_manager,
         models_manager,
         Arc::new(ExecPolicyManager::default()),
@@ -4012,6 +4015,7 @@ async fn make_session_with_history_source_and_agent_control_and_rx(
     let session = Session::new(
         session_configuration,
         Arc::clone(&config),
+        "11111111-1111-4111-8111-111111111111".to_string(),
         auth_manager,
         models_manager,
         Arc::new(ExecPolicyManager::default()),
@@ -5482,6 +5486,7 @@ where
     let (mailbox, mailbox_rx) = crate::agent::Mailbox::new();
     let session = Arc::new(Session {
         conversation_id: thread_id,
+        installation_id: "11111111-1111-4111-8111-111111111111".to_string(),
         tx_event,
         agent_status: agent_status_tx,
         out_of_band_elicitation_paused: watch::channel(false).0,

codex-rs/core/src/session/tests/guardian_tests.rs

@@ -741,6 +741,7 @@ async fn guardian_subagent_does_not_inherit_parent_exec_policy_rules() {
 
     let CodexSpawnOk { codex, .. } = Codex::spawn(CodexSpawnArgs {
         config,
+        installation_id: "11111111-1111-4111-8111-111111111111".to_string(),
         auth_manager,
         models_manager,
         environment_manager: Arc::new(EnvironmentManager::default_for_tests()),

codex-rs/core/src/thread_manager.rs

@@ -7,6 +7,7 @@ use crate::environment_selection::default_thread_environment_selections;
 use crate::environment_selection::resolve_environment_selections;
 use crate::file_watcher::FileWatcher;
 use crate::mcp::McpManager;
+use crate::resolve_installation_id;
 use crate::rollout::RolloutRecorder;
 use crate::rollout::truncation;
 use crate::session::Codex;
@@ -253,6 +254,7 @@ pub(crate) struct ThreadManagerState {
     state_db: StateDbHandle,
     agent_graph_store: Arc<dyn AgentGraphStore>,
     session_source: SessionSource,
+    installation_id: String,
     analytics_events_client: Option<AnalyticsEventsClient>,
     // Captures submitted ops for testing purpose when test mode is enabled.
     ops_log: Option<SharedCapturedOps>,
@@ -316,6 +318,7 @@ impl ThreadManager {
         state_db: StateDbHandle,
         thread_store: Arc<dyn ThreadStore>,
         agent_graph_store: Arc<dyn AgentGraphStore>,
+        installation_id: String,
     ) -> Self {
         let codex_home = config.codex_home.clone();
         let restriction_product = session_source.restriction_product();
@@ -346,6 +349,7 @@ impl ThreadManager {
                 agent_graph_store,
                 auth_manager,
                 session_source,
+                installation_id,
                 analytics_events_client,
                 ops_log: should_use_test_thread_manager_behavior()
                     .then(|| Arc::new(std::sync::Mutex::new(Vec::new()))),
@@ -373,12 +377,21 @@ impl ThreadManager {
             OPENAI_PROVIDER_ID.to_string(),
         )
         .await;
+        let skills_codex_home = match AbsolutePathBuf::from_absolute_path_checked(&codex_home) {
+            Ok(codex_home) => codex_home,
+            Err(err) => panic!("test codex_home should be absolute: {err}"),
+        };
+        let installation_id = resolve_installation_id(&skills_codex_home)
+            .await
+            .unwrap_or_else(|err| panic!("resolve test installation id failed: {err}"));
         let mut manager = Self::with_models_provider_and_home_and_state_db_for_tests(
             auth,
             provider,
             codex_home.clone(),
             Arc::new(EnvironmentManager::default_for_tests()),
             state_db,
+            skills_codex_home,
+            installation_id,
         );
         manager._test_codex_home_guard = Some(TempCodexHomeGuard { path: codex_home });
         manager
@@ -398,12 +411,21 @@ impl ThreadManager {
             OPENAI_PROVIDER_ID.to_string(),
         )
         .await;
+        let skills_codex_home = match AbsolutePathBuf::from_absolute_path_checked(&codex_home) {
+            Ok(codex_home) => codex_home,
+            Err(err) => panic!("test codex_home should be absolute: {err}"),
+        };
+        let installation_id = resolve_installation_id(&skills_codex_home)
+            .await
+            .unwrap_or_else(|err| panic!("resolve test installation id failed: {err}"));
         Self::with_models_provider_and_home_and_state_db_for_tests(
             auth,
             provider,
             codex_home,
             environment_manager,
             state_db,
+            skills_codex_home,
+            installation_id,
         )
     }
 
@@ -413,13 +435,11 @@ impl ThreadManager {
         codex_home: PathBuf,
         environment_manager: Arc<EnvironmentManager>,
         state_db: StateDbHandle,
+        skills_codex_home: AbsolutePathBuf,
+        installation_id: String,
     ) -> Self {
         set_thread_manager_test_mode_for_tests(/*enabled*/ true);
         let auth_manager = AuthManager::from_auth_for_testing(auth);
-        let skills_codex_home = match AbsolutePathBuf::from_absolute_path_checked(&codex_home) {
-            Ok(codex_home) => codex_home,
-            Err(err) => panic!("test codex_home should be absolute: {err}"),
-        };
         let (thread_created_tx, _) = broadcast::channel(THREAD_CREATED_CHANNEL_CAPACITY);
         let restriction_product = SessionSource::Exec.restriction_product();
         let plugins_manager = Arc::new(PluginsManager::new_with_restriction_product(
@@ -459,6 +479,7 @@ impl ThreadManager {
                 agent_graph_store,
                 auth_manager,
                 session_source: SessionSource::Exec,
+                installation_id,
                 analytics_events_client: None,
                 ops_log: should_use_test_thread_manager_behavior()
                     .then(|| Arc::new(std::sync::Mutex::new(Vec::new()))),
@@ -1199,6 +1220,7 @@ impl ThreadManagerState {
             codex, thread_id, ..
         } = Codex::spawn(CodexSpawnArgs {
             config,
+            installation_id: self.installation_id.clone(),
             auth_manager,
             models_manager: Arc::clone(&self.models_manager),
             environment_manager: Arc::clone(&self.environment_manager),

codex-rs/core/src/thread_manager_tests.rs

@@ -1,5 +1,6 @@
 use super::*;
 use crate::config::test_config;
+use crate::installation_id::INSTALLATION_ID_FILENAME;
 use crate::rollout::RolloutRecorder;
 use crate::session::session::SessionSettingsUpdate;
 use crate::session::tests::make_session_and_context;
@@ -26,6 +27,8 @@ use std::time::Duration;
 use tempfile::tempdir;
 use wiremock::MockServer;
 
+const TEST_INSTALLATION_ID: &str = "11111111-1111-4111-8111-111111111111";
+
 fn user_msg(text: &str) -> ResponseItem {
     ResponseItem::Message {
         id: None,
@@ -415,6 +418,7 @@ async fn resume_and_fork_do_not_restore_thread_environments_from_rollout() {
         state_db,
         thread_store,
         agent_graph_store,
+        TEST_INSTALLATION_ID.to_string(),
     );
     let selected_cwd =
         AbsolutePathBuf::try_from(config.cwd.as_path().join("selected")).expect("absolute path");
@@ -509,6 +513,46 @@ async fn resume_and_fork_do_not_restore_thread_environments_from_rollout() {
     );
 }
 
+#[tokio::test]
+async fn explicit_installation_id_skips_codex_home_file() {
+    let temp_dir = tempdir().expect("tempdir");
+    let mut config = test_config().await;
+    config.codex_home = temp_dir.path().join("codex-home").abs();
+    config.cwd = config.codex_home.abs();
+    std::fs::create_dir_all(&config.codex_home).expect("create codex home");
+
+    let auth_manager =
+        AuthManager::from_auth_for_testing(CodexAuth::create_dummy_chatgpt_auth_for_testing());
+    let installation_id = uuid::Uuid::new_v4().to_string();
+    let (state_db, thread_store, agent_graph_store) = state_backed_stores(&config).await;
+    let manager = ThreadManager::new(
+        &config,
+        auth_manager,
+        SessionSource::Exec,
+        Arc::new(codex_exec_server::EnvironmentManager::default_for_tests()),
+        /*analytics_events_client*/ None,
+        state_db,
+        thread_store,
+        agent_graph_store,
+        installation_id.clone(),
+    );
+
+    let thread = manager
+        .start_thread(config.clone())
+        .await
+        .expect("start thread with explicit installation id");
+
+    assert!(!config.codex_home.join(INSTALLATION_ID_FILENAME).exists());
+    assert_eq!(thread.thread.codex.session.installation_id, installation_id);
+
+    thread
+        .thread
+        .shutdown_and_wait()
+        .await
+        .expect("shutdown thread");
+    let _ = manager.remove_thread(&thread.thread_id).await;
+}
+
 #[tokio::test]
 async fn resume_active_thread_from_rollout_returns_running_thread() {
     let temp_dir = tempdir().expect("tempdir");
@@ -529,6 +573,7 @@ async fn resume_active_thread_from_rollout_returns_running_thread() {
         state_db,
         thread_store,
         agent_graph_store,
+        TEST_INSTALLATION_ID.to_string(),
     );
 
     let source = manager
@@ -585,6 +630,7 @@ async fn resume_stopped_thread_from_rollout_spawns_new_thread() {
         state_db,
         thread_store,
         agent_graph_store,
+        TEST_INSTALLATION_ID.to_string(),
     );
 
     let source = manager
@@ -646,6 +692,7 @@ async fn resume_stopped_thread_from_rollout_preserves_thread_source() {
         state_db,
         thread_store,
         agent_graph_store,
+        TEST_INSTALLATION_ID.to_string(),
     );
 
     let source = manager
@@ -731,6 +778,7 @@ async fn new_uses_active_provider_for_model_refresh() {
         state_db,
         thread_store,
         agent_graph_store,
+        TEST_INSTALLATION_ID.to_string(),
     );
 
     let _ = manager.list_models(RefreshStrategy::Online).await;
@@ -945,6 +993,7 @@ async fn interrupted_fork_snapshot_does_not_synthesize_turn_id_for_legacy_histor
         state_db,
         thread_store,
         agent_graph_store,
+        TEST_INSTALLATION_ID.to_string(),
     );
 
     let source = manager
@@ -1051,6 +1100,7 @@ async fn interrupted_fork_snapshot_preserves_explicit_turn_id() {
         state_db,
         thread_store,
         agent_graph_store,
+        TEST_INSTALLATION_ID.to_string(),
     );
 
     let source = manager
@@ -1146,6 +1196,7 @@ async fn interrupted_fork_snapshot_uses_persisted_mid_turn_history_without_live_
         state_db,
         thread_store,
         agent_graph_store,
+        TEST_INSTALLATION_ID.to_string(),
     );
 
     let source = manager
@@ -1287,6 +1338,7 @@ async fn resumed_thread_keeps_paused_goal_paused() -> anyhow::Result<()> {
         state_db,
         thread_store,
         agent_graph_store,
+        TEST_INSTALLATION_ID.to_string(),
     );
 
     let source = manager

codex-rs/core/src/tools/handlers/multi_agents_tests.rs

@@ -3171,6 +3171,7 @@ async fn tool_handlers_cascade_close_and_resume_and_keep_explicitly_closed_subtr
         state_db.clone(),
         thread_store_from_config(&config, state_db.clone()),
         agent_graph_store_from_state_db(state_db.clone()),
+        "11111111-1111-4111-8111-111111111111".to_string(),
     );
 
     let parent = manager