test(tui): preserve normalized snapshot newlines

codex-rs/codex-mcp/src/connection_manager.rs

@@ -386,6 +386,50 @@ impl McpConnectionManager {
         }
     }
 
+    /// Returns an owned future that waits only for the requested MCP servers.
+    ///
+    /// Constructing this future clones the selected clients, allowing callers to
+    /// release any lock guarding the manager before awaiting startup.
+    pub fn wait_for_servers_ready(
+        &self,
+        server_names: &[String],
+    ) -> impl std::future::Future<Output = Vec<McpStartupFailure>> + Send + 'static + use<> {
+        let clients = server_names
+            .iter()
+            .map(|server_name| (server_name.clone(), self.clients.get(server_name).cloned()))
+            .collect::<Vec<_>>();
+        async move {
+            let mut failures = Vec::new();
+            for (server_name, client) in clients {
+                let Some(client) = client else {
+                    failures.push(McpStartupFailure {
+                        server: server_name.clone(),
+                        error: format!("MCP server `{server_name}` was not initialized"),
+                    });
+                    continue;
+                };
+                if let Err(error) = client.client().await {
+                    failures.push(McpStartupFailure {
+                        server: server_name,
+                        error: startup_outcome_error_message(error),
+                    });
+                }
+            }
+            failures
+        }
+    }
+
+    /// Returns an owned future that waits for every configured MCP server.
+    pub fn wait_for_all_servers_ready(
+        &self,
+    ) -> impl std::future::Future<Output = (Vec<String>, Vec<McpStartupFailure>)> + Send + 'static
+    {
+        let mut server_names = self.clients.keys().cloned().collect::<Vec<_>>();
+        server_names.sort();
+        let readiness = self.wait_for_servers_ready(&server_names);
+        async move { (server_names, readiness.await) }
+    }
+
     pub async fn required_startup_failures(
         &self,
         required_servers: &[String],
@@ -477,6 +521,36 @@ impl McpConnectionManager {
         server_infos
     }
 
+    /// Returns model-visible tools already available from startup cache or a ready client.
+    ///
+    /// Pending MCP servers without a cached snapshot are intentionally omitted so
+    /// ordinary model work does not wait on optional background initialization.
+    #[instrument(level = "trace", skip_all, fields(mcp_server_count = self.clients.len()))]
+    pub async fn list_ready_or_cached_tools(&self) -> Vec<ToolInfo> {
+        let mut tools = Vec::new();
+        for (server_name, managed_client) in &self.clients {
+            let has_cached_tool_info_snapshot = managed_client.cached_tool_info_snapshot.is_some();
+            let startup_complete = managed_client
+                .startup_complete
+                .load(std::sync::atomic::Ordering::Acquire);
+            trace!(
+                server_name = %server_name,
+                has_cached_tool_info_snapshot,
+                startup_complete,
+                "checking ready MCP server tools while building nonblocking tool list"
+            );
+            let Some(server_tools) = managed_client.listed_tools_if_ready_or_cached().await else {
+                continue;
+            };
+            tools.extend(
+                server_tools
+                    .into_iter()
+                    .map(|tool| self.with_server_metadata(tool)),
+            );
+        }
+        normalize_tools_for_model_with_prefix(tools, self.prefix_mcp_tool_names)
+    }
+
     /// Force-refresh codex apps tools by bypassing the in-process cache.
     ///
     /// On success, the refreshed tools replace the cache contents and the

codex-rs/codex-mcp/src/connection_manager_tests.rs

@@ -810,7 +810,7 @@ async fn list_all_tools_uses_cached_tool_info_snapshot_while_client_is_pending()
             client: pending_client,
             cached_tool_info_snapshot: Some(startup_tools),
             cached_server_info: None,
-            startup_complete: Arc::new(std::sync::atomic::AtomicBool::new(false)),
+            startup_complete: Arc::new(std::sync::atomic::AtomicBool::new(/*v*/ false)),
             tool_plugin_provenance: Arc::new(ToolPluginProvenance::default()),
             cancel_token: CancellationToken::new(),
         },
@@ -980,6 +980,39 @@ async fn list_all_tools_blocks_while_client_is_pending_without_cached_tool_info_
     assert!(timeout_result.is_err());
 }
 
+#[tokio::test]
+async fn list_ready_or_cached_tools_skips_pending_client_without_cached_tool_info_snapshot() {
+    let pending_client = futures::future::pending::<Result<ManagedClient, StartupOutcomeError>>()
+        .boxed()
+        .shared();
+    let approval_policy = Constrained::allow_any(AskForApproval::OnFailure);
+    let permission_profile = Constrained::allow_any(PermissionProfile::default());
+    let mut manager = McpConnectionManager::new_uninitialized(
+        &approval_policy,
+        &permission_profile,
+        /*prefix_mcp_tool_names*/ true,
+    );
+    manager.clients.insert(
+        "optional".to_string(),
+        AsyncManagedClient {
+            client: pending_client,
+            cached_tool_info_snapshot: None,
+            cached_server_info: None,
+            startup_complete: Arc::new(std::sync::atomic::AtomicBool::new(/*v*/ false)),
+            tool_plugin_provenance: Arc::new(ToolPluginProvenance::default()),
+            cancel_token: CancellationToken::new(),
+        },
+    );
+
+    let tools = tokio::time::timeout(
+        Duration::from_millis(10),
+        manager.list_ready_or_cached_tools(),
+    )
+    .await
+    .expect("pending optional client should not block ready tool listing");
+    assert!(tools.is_empty());
+}
+
 #[tokio::test]
 async fn list_all_tools_does_not_block_when_cached_tool_info_snapshot_is_empty() {
     let pending_client = futures::future::pending::<Result<ManagedClient, StartupOutcomeError>>()

codex-rs/codex-mcp/src/rmcp_client.rs

@@ -255,58 +255,57 @@ impl AsyncManagedClient {
         None
     }
 
-    pub(crate) async fn listed_tools(&self) -> Option<Vec<ToolInfo>> {
-        let annotate_tools = |tools: Vec<ToolInfo>| {
-            let mut tools = tools;
-            for tool in &mut tools {
-                if tool.server_name == CODEX_APPS_MCP_SERVER_NAME {
-                    tool.tool = tool_with_model_visible_input_schema(&tool.tool);
-                }
-
-                let plugin_names = match tool.connector_id.as_deref() {
-                    Some(connector_id) => self
-                        .tool_plugin_provenance
-                        .plugin_display_names_for_connector_id(connector_id),
-                    None => self
-                        .tool_plugin_provenance
-                        .plugin_display_names_for_mcp_server_name(tool.server_name.as_str()),
-                };
-                tool.plugin_display_names = plugin_names.to_vec();
-
-                if plugin_names.is_empty() {
-                    continue;
-                }
-
-                let plugin_source_note = if plugin_names.len() == 1 {
-                    format!("This tool is part of plugin `{}`.", plugin_names[0])
-                } else {
-                    format!(
-                        "This tool is part of plugins {}.",
-                        plugin_names
-                            .iter()
-                            .map(|plugin_name| format!("`{plugin_name}`"))
-                            .collect::<Vec<_>>()
-                            .join(", ")
-                    )
-                };
-                let description = tool
-                    .tool
-                    .description
-                    .as_deref()
-                    .map(str::trim)
-                    .unwrap_or("");
-                let annotated_description = if description.is_empty() {
-                    plugin_source_note
-                } else if matches!(description.chars().last(), Some('.' | '!' | '?')) {
-                    format!("{description} {plugin_source_note}")
-                } else {
-                    format!("{description}. {plugin_source_note}")
-                };
-                tool.tool.description = Some(Cow::Owned(annotated_description));
+    fn annotate_tools(&self, mut tools: Vec<ToolInfo>) -> Vec<ToolInfo> {
+        for tool in &mut tools {
+            if tool.server_name == CODEX_APPS_MCP_SERVER_NAME {
+                tool.tool = tool_with_model_visible_input_schema(&tool.tool);
             }
-            tools
-        };
 
+            let plugin_names = match tool.connector_id.as_deref() {
+                Some(connector_id) => self
+                    .tool_plugin_provenance
+                    .plugin_display_names_for_connector_id(connector_id),
+                None => self
+                    .tool_plugin_provenance
+                    .plugin_display_names_for_mcp_server_name(tool.server_name.as_str()),
+            };
+            tool.plugin_display_names = plugin_names.to_vec();
+
+            if plugin_names.is_empty() {
+                continue;
+            }
+
+            let plugin_source_note = if plugin_names.len() == 1 {
+                format!("This tool is part of plugin `{}`.", plugin_names[0])
+            } else {
+                format!(
+                    "This tool is part of plugins {}.",
+                    plugin_names
+                        .iter()
+                        .map(|plugin_name| format!("`{plugin_name}`"))
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            };
+            let description = tool
+                .tool
+                .description
+                .as_deref()
+                .map(str::trim)
+                .unwrap_or("");
+            let annotated_description = if description.is_empty() {
+                plugin_source_note
+            } else if matches!(description.chars().last(), Some('.' | '!' | '?')) {
+                format!("{description} {plugin_source_note}")
+            } else {
+                format!("{description}. {plugin_source_note}")
+            };
+            tool.tool.description = Some(Cow::Owned(annotated_description));
+        }
+        tools
+    }
+
+    pub(crate) async fn listed_tools(&self) -> Option<Vec<ToolInfo>> {
         // Keep cache payloads raw; plugin provenance is resolved per-session at read time.
         let tools = if let Some(startup_tools) = self.cached_tool_info_snapshot_while_initializing()
         {
@@ -317,7 +316,17 @@ impl AsyncManagedClient {
                 Err(_) => self.cached_tool_info_snapshot.clone(),
             }
         };
-        tools.map(annotate_tools)
+        tools.map(|tools| self.annotate_tools(tools))
+    }
+
+    pub(crate) async fn listed_tools_if_ready_or_cached(&self) -> Option<Vec<ToolInfo>> {
+        if let Some(startup_tools) = self.cached_tool_info_snapshot_while_initializing() {
+            return Some(self.annotate_tools(startup_tools));
+        }
+        if !self.startup_complete.load(Ordering::Acquire) {
+            return None;
+        }
+        self.listed_tools().await
     }
 }
 

codex-rs/config/src/types.rs

@@ -662,6 +662,11 @@ pub struct Tui {
     #[serde(default = "default_true")]
     pub show_tooltips: bool,
 
+    /// Show background MCP server startup status and optional failure diagnostics in the TUI.
+    /// Defaults to `false`.
+    #[serde(default)]
+    pub show_mcp_startup_status: bool,
+
     /// Start the composer in Vim mode (`Normal`) by default.
     /// Defaults to `false`.
     #[serde(default)]

codex-rs/core/config.schema.json

@@ -2955,6 +2955,11 @@
           "default": null,
           "description": "Preferred layout for resume/fork session picker results."
         },
+        "show_mcp_startup_status": {
+          "default": false,
+          "description": "Show background MCP server startup status and optional failure diagnostics in the TUI. Defaults to `false`.",
+          "type": "boolean"
+        },
         "show_tooltips": {
           "default": true,
           "description": "Show startup tooltips in the TUI welcome screen. Defaults to `true`.",

codex-rs/core/src/codex_thread.rs

@@ -23,6 +23,7 @@ use codex_protocol::openai_models::ReasoningEffort;
 use codex_protocol::protocol::AdditionalContextEntry;
 use codex_protocol::protocol::AskForApproval;
 use codex_protocol::protocol::Event;
+use codex_protocol::protocol::McpStartupFailure;
 use codex_protocol::protocol::Op;
 use codex_protocol::protocol::SandboxPolicy;
 use codex_protocol::protocol::SessionConfiguredEvent;
@@ -142,6 +143,21 @@ impl CodexThread {
         self.codex.shutdown_and_wait().await
     }
 
+    #[doc(hidden)]
+    pub async fn wait_for_mcp_startup(&self) -> (Vec<String>, Vec<McpStartupFailure>) {
+        let readiness = {
+            let manager = self
+                .codex
+                .session
+                .services
+                .mcp_connection_manager
+                .read()
+                .await;
+            manager.wait_for_all_servers_ready()
+        };
+        readiness.await
+    }
+
     /// Wait until the underlying session loop has terminated.
     pub async fn wait_until_terminated(&self) {
         self.codex.session_loop_termination.clone().await;

codex-rs/core/src/config/config_tests.rs

@@ -561,6 +561,7 @@ fn config_toml_deserializes_model_availability_nux() {
             notification_settings: TuiNotificationSettings::default(),
             animations: true,
             show_tooltips: true,
+            show_mcp_startup_status: false,
             vim_mode_default: false,
             raw_output_mode: false,
             alternate_screen: AltScreenMode::default(),
@@ -3209,6 +3210,7 @@ fn tui_config_missing_notifications_field_defaults_to_enabled() {
             notification_settings: TuiNotificationSettings::default(),
             animations: true,
             show_tooltips: true,
+            show_mcp_startup_status: false,
             vim_mode_default: false,
             raw_output_mode: false,
             alternate_screen: AltScreenMode::Auto,

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

@@ -672,6 +672,9 @@ pub struct Config {
     /// Show startup tooltips in the TUI welcome screen.
     pub show_tooltips: bool,
 
+    /// Show background MCP server startup status and optional failure diagnostics in the TUI.
+    pub tui_show_mcp_startup_status: bool,
+
     /// Persisted startup availability NUX state for model tooltips.
     pub model_availability_nux: ModelAvailabilityNuxConfig,
 
@@ -3498,6 +3501,11 @@ impl Config {
                 .unwrap_or_default(),
             animations: cfg.tui.as_ref().map(|t| t.animations).unwrap_or(true),
             show_tooltips: cfg.tui.as_ref().map(|t| t.show_tooltips).unwrap_or(true),
+            tui_show_mcp_startup_status: cfg
+                .tui
+                .as_ref()
+                .map(|t| t.show_mcp_startup_status)
+                .unwrap_or(false),
             model_availability_nux: cfg
                 .tui
                 .as_ref()

codex-rs/core/src/connectors.rs

@@ -101,7 +101,9 @@ pub(crate) async fn list_accessible_and_enabled_connectors_from_manager(
     config: &Config,
 ) -> Vec<AppInfo> {
     with_app_enabled_state(
-        accessible_connectors_from_mcp_tools(&mcp_connection_manager.list_all_tools().await),
+        accessible_connectors_from_mcp_tools(
+            &mcp_connection_manager.list_ready_or_cached_tools().await,
+        ),
         config,
     )
     .into_iter()

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

@@ -72,6 +72,7 @@ use codex_async_utils::OrCancelExt;
 use codex_features::Feature;
 use codex_git_utils::get_git_repo_root;
 use codex_git_utils::get_git_repo_root_with_fs;
+use codex_mcp::CODEX_APPS_MCP_SERVER_NAME;
 use codex_protocol::config_types::AutoCompactTokenLimitScope;
 use codex_protocol::config_types::ModeKind;
 use codex_protocol::config_types::ServiceTier;
@@ -446,7 +447,7 @@ async fn run_hooks_and_record_inputs(
 
 #[expect(
     clippy::await_holding_invalid_type,
-    reason = "MCP tool listing borrows the read guard across cancellation-aware await"
+    reason = "ready-or-cached tool inspection never awaits unresolved MCP startup"
 )]
 async fn build_skills_and_plugins(
     sess: &Arc<Session>,
@@ -477,6 +478,40 @@ async fn build_skills_and_plugins(
     // enabled plugins, then converted into turn-scoped guidance below.
     let mentioned_plugins =
         collect_explicit_plugin_mentions(&user_input, loaded_plugins.capability_summaries());
+    let explicitly_mentioned_apps = collect_explicit_app_ids(&user_input);
+    let mut explicitly_requested_mcp_servers = mentioned_plugins
+        .iter()
+        .flat_map(|plugin| plugin.mcp_server_names.iter().cloned())
+        .collect::<HashSet<_>>();
+    if turn_context.apps_enabled() && !explicitly_mentioned_apps.is_empty() {
+        explicitly_requested_mcp_servers.insert(CODEX_APPS_MCP_SERVER_NAME.to_string());
+    }
+    if !explicitly_requested_mcp_servers.is_empty() {
+        let mut explicitly_requested_mcp_servers = explicitly_requested_mcp_servers
+            .into_iter()
+            .collect::<Vec<_>>();
+        explicitly_requested_mcp_servers.sort();
+        let readiness = {
+            let mcp_connection_manager = sess.services.mcp_connection_manager.read().await;
+            mcp_connection_manager.wait_for_servers_ready(&explicitly_requested_mcp_servers)
+        };
+        let failures = match readiness.or_cancel(cancellation_token).await {
+            Ok(failures) => failures,
+            Err(_) => return None,
+        };
+        for failure in failures {
+            sess.send_event(
+                turn_context,
+                EventMsg::Warning(WarningEvent {
+                    message: format!(
+                        "MCP dependency `{}` requested for this turn is unavailable: {}",
+                        failure.server, failure.error
+                    ),
+                }),
+            )
+            .await;
+        }
+    }
     let mcp_tools = if turn_context.apps_enabled() || !mentioned_plugins.is_empty() {
         // Plugin mentions need raw MCP/app inventory even when app tools
         // are normally hidden so we can describe the plugin's currently
@@ -486,7 +521,7 @@ async fn build_skills_and_plugins(
             .mcp_connection_manager
             .read()
             .await
-            .list_all_tools()
+            .list_ready_or_cached_tools()
             .or_cancel(cancellation_token)
             .await
         {
@@ -556,7 +591,7 @@ async fn build_skills_and_plugins(
     );
     let plugin_items =
         build_plugin_injections(&mentioned_plugins, &mcp_tools, &available_connectors);
-    let mut explicitly_enabled_connectors = collect_explicit_app_ids(&user_input);
+    let mut explicitly_enabled_connectors = explicitly_mentioned_apps;
     explicitly_enabled_connectors.extend(skill_connector_ids);
     let connector_names_by_id = available_connectors
         .iter()
@@ -1015,7 +1050,7 @@ async fn run_sampling_request(
 
 #[expect(
     clippy::await_holding_invalid_type,
-    reason = "tool router construction reads through the session-owned manager guard"
+    reason = "ready-or-cached tool inspection never awaits unresolved MCP startup"
 )]
 #[instrument(level = "trace",
     skip_all,
@@ -1038,7 +1073,7 @@ pub(crate) async fn built_tools(
         .await;
     let has_mcp_servers = mcp_connection_manager.has_servers();
     let all_mcp_tools = mcp_connection_manager
-        .list_all_tools()
+        .list_ready_or_cached_tools()
         .or_cancel(cancellation_token)
         .await?;
     drop(mcp_connection_manager);

codex-rs/core/tests/common/lib.rs

@@ -250,34 +250,17 @@ where
 
 /// Waits for a configured MCP server to finish startup and requires it to be ready.
 pub async fn wait_for_mcp_server(codex: &CodexThread, server_name: &str) -> anyhow::Result<()> {
-    use codex_protocol::protocol::EventMsg;
-
-    // Wait for the startup summary regardless of outcome, then interpret the
-    // requested server's ready, failed, or cancelled entry below.
-    let summary = loop {
-        let event = codex
-            .next_event()
-            .await
-            .expect("stream ended unexpectedly while waiting for MCP startup");
-        if let EventMsg::McpStartupComplete(summary) = event.msg {
-            break summary;
-        }
-    };
-    if let Some(failure) = summary
-        .failed
+    let (server_names, failures) = codex.wait_for_mcp_startup().await;
+    if !server_names.iter().any(|name| name == server_name) {
+        anyhow::bail!("MCP server {server_name} was not initialized");
+    }
+    if let Some(failure) = failures
         .iter()
         .find(|failure| failure.server == server_name)
     {
         let error = &failure.error;
         anyhow::bail!("MCP server {server_name} failed to start: {error}");
     }
-    if summary.cancelled.iter().any(|server| server == server_name) {
-        anyhow::bail!("MCP server {server_name} startup was cancelled");
-    }
-    assert!(
-        summary.ready.iter().any(|server| server == server_name),
-        "expected MCP server {server_name} to be ready; startup summary: {summary:?}"
-    );
     Ok(())
 }
 

codex-rs/core/tests/suite/client.rs

@@ -67,6 +67,7 @@ use core_test_support::skip_if_no_network;
 use core_test_support::test_codex::TestCodex;
 use core_test_support::test_codex::test_codex;
 use core_test_support::wait_for_event;
+use core_test_support::wait_for_mcp_server;
 use dunce::canonicalize as normalize_path;
 use futures::StreamExt;
 use pretty_assertions::assert_eq;
@@ -1273,6 +1274,9 @@ async fn includes_apps_guidance_as_developer_message_for_chatgpt_auth() {
         .await
         .expect("create new conversation")
         .codex;
+    wait_for_mcp_server(&codex, "codex_apps")
+        .await
+        .expect("wait for apps MCP startup");
 
     codex
         .submit(Op::UserInput {

codex-rs/core/tests/suite/openai_file_mcp.rs

@@ -23,6 +23,7 @@ use core_test_support::responses::ev_response_created;
 use core_test_support::responses::mount_sse_sequence;
 use core_test_support::responses::sse;
 use core_test_support::responses::start_mock_server;
+use core_test_support::wait_for_mcp_server;
 use pretty_assertions::assert_eq;
 use serde_json::Value;
 use serde_json::json;
@@ -155,6 +156,7 @@ async fn codex_apps_file_params_upload_local_paths_before_mcp_tool_call() -> Res
             trust_discovered_hooks(config);
         });
     let test = builder.build(&server).await?;
+    wait_for_mcp_server(&test.codex, "codex_apps").await?;
     tokio::fs::write(test.cwd.path().join("report.txt"), b"hello world").await?;
 
     test.submit_turn_with_approval_and_permission_profile(

codex-rs/core/tests/suite/plugins.rs

@@ -177,6 +177,7 @@ async fn capability_sections_render_in_developer_message_in_order() -> Result<()
         apps_server.chatgpt_base_url,
     )
     .await?;
+    wait_for_mcp_server(&codex, "codex_apps").await?;
 
     codex
         .submit(Op::UserInput {
@@ -257,6 +258,7 @@ async fn explicit_plugin_mentions_inject_plugin_guidance() -> Result<()> {
         build_apps_enabled_plugin_test_codex(&server, codex_home, apps_server.chatgpt_base_url)
             .await?;
     wait_for_mcp_server(&codex, "sample").await?;
+    wait_for_mcp_server(&codex, "codex_apps").await?;
 
     codex
         .submit(Op::UserInput {

codex-rs/core/tests/suite/search_tool.rs

@@ -253,6 +253,7 @@ async fn app_only_tools_are_not_visible_or_runnable_by_direct_model_calls() -> R
 
     let mut builder = apps_enabled_builder(apps_server.chatgpt_base_url.clone());
     let test = builder.build(&server).await?;
+    wait_for_mcp_server(&test.codex, "codex_apps").await?;
     test.submit_turn_with_approval_and_permission_profile(
         "Try to call the app-only calendar tool.",
         AskForApproval::Never,
@@ -358,6 +359,7 @@ async fn search_tool_adds_discovery_instructions_to_tool_description() -> Result
 
     let mut builder = configured_builder(apps_server.chatgpt_base_url.clone());
     let test = builder.build(&server).await?;
+    wait_for_mcp_server(&test.codex, "codex_apps").await?;
 
     test.submit_turn_with_approval_and_permission_profile(
         "list tools",
@@ -522,6 +524,7 @@ async fn tool_search_returns_deferred_tools_without_follow_up_tool_injection() -
 
     let mut builder = configured_builder(apps_server.chatgpt_base_url.clone());
     let test = builder.build(&server).await?;
+    wait_for_mcp_server(&test.codex, "codex_apps").await?;
     test.codex
         .submit(Op::UserInput {
             environments: None,
@@ -1457,6 +1460,7 @@ async fn tool_search_matches_mcp_tools_by_distinct_name_description_and_schema_t
 
     let mut builder = configured_builder(apps_server.chatgpt_base_url.clone());
     let test = builder.build(&server).await?;
+    wait_for_mcp_server(&test.codex, "codex_apps").await?;
 
     test.submit_turn_with_approval_and_permission_profile(
         "Search for calendar tooling.",

codex-rs/thread-manager-sample/src/main.rs

@@ -205,6 +205,7 @@ fn new_config(model: Option<String>, arg0_paths: Arg0DispatchPaths) -> anyhow::R
         tui_terminal_title: None,
         tui_theme: None,
         tui_raw_output_mode: false,
+        tui_show_mcp_startup_status: false,
         tui_pet: None,
         tui_pet_anchor: TuiPetAnchor::Composer,
         terminal_resize_reflow: TerminalResizeReflowConfig::default(),

codex-rs/tui/src/app.rs

@@ -1211,6 +1211,10 @@ See the Codex keymap documentation for supported actions and examples."
         app_server: &mut AppServerSession,
         event: TuiEvent,
     ) -> Result<AppRunControl> {
+        if self.should_defer_draw_for_session_header_commit(&event) {
+            return Ok(AppRunControl::Continue);
+        }
+
         let terminal_resize_reflow_enabled = self.terminal_resize_reflow_enabled();
         if terminal_resize_reflow_enabled && matches!(event, TuiEvent::Draw | TuiEvent::Resize) {
             self.handle_draw_pre_render(tui)?;
@@ -1287,6 +1291,11 @@ See the Codex keymap documentation for supported actions and examples."
         Ok(AppRunControl::Continue)
     }
 
+    fn should_defer_draw_for_session_header_commit(&self, event: &TuiEvent) -> bool {
+        self.chat_widget.is_session_header_commit_pending()
+            && matches!(event, TuiEvent::Draw | TuiEvent::Resize)
+    }
+
     pub(super) fn show_shutdown_feedback(&mut self, tui: &mut tui::Tui) -> Result<()> {
         self.disable_ambient_pet_before_shutdown(tui)?;
         self.chat_widget.show_shutdown_in_progress();

codex-rs/tui/src/app/event_dispatch.rs

@@ -197,6 +197,8 @@ impl App {
                 self.begin_thread_switch_history_replay_buffer();
             }
             AppEvent::InsertHistoryCell(cell) => {
+                self.chat_widget
+                    .complete_session_header_commit_if_pending(cell.as_ref());
                 let cell: Arc<dyn HistoryCell> = cell.into();
                 if let Some(Overlay::Transcript(t)) = &mut self.overlay {
                     t.insert_cell(cell.clone());

codex-rs/tui/src/app/tests/startup.rs

@@ -135,6 +135,78 @@ fn startup_waiting_gate_not_applied_for_resume_or_fork_session_selection() {
     );
 }
 
+fn install_startup_placeholder_widget(app: &mut App) {
+    let config = app.config.clone();
+    let model = crate::legacy_core::test_support::get_model_offline(config.model.as_deref());
+    app.chat_widget = ChatWidget::new_with_app_event(ChatWidgetInit {
+        config,
+        frame_requester: crate::tui::FrameRequester::test_dummy(),
+        app_event_tx: app.app_event_tx.clone(),
+        workspace_command_runner: None,
+        initial_user_message: None,
+        enhanced_keys_supported: false,
+        has_chatgpt_account: false,
+        model_catalog: app.model_catalog.clone(),
+        feedback: codex_feedback::CodexFeedback::new(),
+        is_first_run: false,
+        status_account_display: None,
+        runtime_model_provider_base_url: None,
+        initial_plan_type: None,
+        model: Some(model),
+        startup_tooltip_override: None,
+        status_line_invalid_items_warned: app.status_line_invalid_items_warned.clone(),
+        terminal_title_invalid_items_warned: app.terminal_title_invalid_items_warned.clone(),
+        session_telemetry: app.session_telemetry.clone(),
+    });
+}
+
+#[tokio::test]
+async fn startup_header_commit_defers_draw_until_session_info_is_committed() {
+    let (mut app, mut app_event_rx, _op_rx) = make_test_app_with_channels().await;
+    install_startup_placeholder_widget(&mut app);
+
+    app.chat_widget.handle_thread_session(test_thread_session(
+        ThreadId::new(),
+        test_path_buf("/tmp/project"),
+    ));
+
+    assert!(app.chat_widget.is_session_header_commit_pending());
+    assert!(app.should_defer_draw_for_session_header_commit(&crate::tui::TuiEvent::Draw));
+    assert!(app.should_defer_draw_for_session_header_commit(&crate::tui::TuiEvent::Resize));
+
+    let header = loop {
+        match app_event_rx.try_recv() {
+            Ok(AppEvent::InsertHistoryCell(cell))
+                if cell.as_any().is::<crate::history_cell::SessionInfoCell>() =>
+            {
+                break cell;
+            }
+            Ok(_) => continue,
+            other => panic!("expected queued configured header, got {other:?}"),
+        }
+    };
+    app.chat_widget
+        .complete_session_header_commit_if_pending(header.as_ref());
+
+    assert!(!app.chat_widget.is_session_header_commit_pending());
+    assert!(!app.should_defer_draw_for_session_header_commit(&crate::tui::TuiEvent::Draw));
+}
+
+#[tokio::test]
+async fn quiet_session_configuration_does_not_defer_draw_for_header_commit() {
+    let (mut app, _app_event_rx, _op_rx) = make_test_app_with_channels().await;
+    install_startup_placeholder_widget(&mut app);
+
+    app.chat_widget
+        .handle_thread_session_quiet(test_thread_session(
+            ThreadId::new(),
+            test_path_buf("/tmp/project"),
+        ));
+
+    assert!(!app.chat_widget.is_session_header_commit_pending());
+    assert!(!app.should_defer_draw_for_session_header_commit(&crate::tui::TuiEvent::Draw));
+}
+
 #[tokio::test]
 async fn startup_thread_started_submits_queued_startup_input() {
     let (mut app, _app_event_rx, mut op_rx) = make_test_app_with_channels().await;

codex-rs/tui/src/chatwidget.rs

@@ -636,9 +636,9 @@ pub(crate) struct ChatWidget {
     show_welcome_banner: bool,
     // One-shot tooltip override for the primary startup session.
     startup_tooltip_override: Option<String>,
-    // When resuming an existing session (selected via resume picker), avoid an
-    // immediate redraw on SessionConfigured to prevent a gratuitous UI flicker.
-    suppress_session_configured_redraw: bool,
+    // A replacement for the provisional session header has been queued for terminal history.
+    // Until it is committed, drawing would expose a transient composer-only frame.
+    session_header_commit_pending: bool,
     // During snapshot restore, defer startup prompt submission until replayed
     // history has been rendered so resumed/forked prompts keep chronological
     // order.
@@ -1485,6 +1485,9 @@ impl ChatWidget {
             false
         };
 
+        if merged_header {
+            self.session_header_commit_pending = true;
+        }
         self.flush_active_cell();
 
         if !merged_header && let Some(cell) = session_info_cell {
@@ -1492,6 +1495,17 @@ impl ChatWidget {
         }
     }
 
+    pub(crate) fn is_session_header_commit_pending(&self) -> bool {
+        self.session_header_commit_pending
+    }
+
+    pub(crate) fn complete_session_header_commit_if_pending(&mut self, cell: &dyn HistoryCell) {
+        if self.session_header_commit_pending && cell.as_any().is::<history_cell::SessionInfoCell>()
+        {
+            self.session_header_commit_pending = false;
+        }
+    }
+
     pub(crate) fn add_info_message(&mut self, message: String, hint: Option<String>) {
         self.add_to_history(history_cell::new_info_event(message, hint));
         self.request_redraw();
@@ -1836,6 +1850,7 @@ impl ChatWidget {
     }
 
     pub(crate) fn sync_plugin_mentions_config(&mut self, config: &Config) {
+        self.sync_mcp_startup_status_config(config.tui_show_mcp_startup_status);
         self.config.features = config.features.clone();
         self.config.config_layer_stack = config.config_layer_stack.clone();
         self.config.realtime = config.realtime.clone();

codex-rs/tui/src/chatwidget/constructor.rs

@@ -186,7 +186,7 @@ impl ChatWidget {
             queued_message_edit_hint_binding,
             show_welcome_banner: is_first_run,
             startup_tooltip_override,
-            suppress_session_configured_redraw: false,
+            session_header_commit_pending: false,
             suppress_initial_user_message_submit: false,
             pending_notification: None,
             quit_shortcut_expires_at: None,

codex-rs/tui/src/chatwidget/mcp_startup.rs

@@ -1,8 +1,8 @@
 //! MCP startup state and status handling for the chat widget.
 //!
 //! The app server reports MCP server startup as per-server status updates. This
-//! module keeps the TUI's buffered startup round state coherent and translates
-//! those updates into status headers, warnings, and queued-input release points.
+//! module keeps optional diagnostic presentation state coherent when background
+//! startup status display is explicitly enabled.
 
 use std::collections::BTreeSet;
 
@@ -176,6 +176,9 @@ impl ChatWidget {
     }
 
     pub(super) fn finish_mcp_startup(&mut self, failed: Vec<String>, cancelled: Vec<String>) {
+        if !self.config.tui_show_mcp_startup_status {
+            return;
+        }
         if !cancelled.is_empty() {
             self.on_warning(format!(
                 "MCP startup interrupted. The following servers were not initialized: {}",
@@ -205,6 +208,9 @@ impl ChatWidget {
     }
 
     pub(crate) fn finish_mcp_startup_after_lag(&mut self) {
+        if !self.config.tui_show_mcp_startup_status {
+            return;
+        }
         if self.mcp_startup_ignore_updates_until_next_start {
             if self.mcp_startup_pending_next_round.is_empty() {
                 self.mcp_startup_pending_next_round_saw_starting = false;
@@ -257,6 +263,9 @@ impl ChatWidget {
         &mut self,
         notification: McpServerStatusUpdatedNotification,
     ) {
+        if !self.config.tui_show_mcp_startup_status {
+            return;
+        }
         let status = match notification.status {
             McpServerStartupState::Starting => McpStartupStatus::Starting,
             McpServerStartupState::Ready => McpStartupStatus::Ready,
@@ -273,4 +282,24 @@ impl ChatWidget {
             /*complete_when_settled*/ true,
         );
     }
+
+    pub(crate) fn sync_mcp_startup_status_config(&mut self, show_status: bool) {
+        let was_visible = self.config.tui_show_mcp_startup_status;
+        self.config.tui_show_mcp_startup_status = show_status;
+        if was_visible && !show_status {
+            let mcp_startup_owned_status = self.status_header_is_mcp_startup_owned();
+            self.mcp_startup_status = None;
+            self.mcp_startup_expected_servers = None;
+            self.mcp_startup_ignore_updates_until_next_start = false;
+            self.mcp_startup_allow_terminal_only_next_round = false;
+            self.mcp_startup_pending_next_round.clear();
+            self.mcp_startup_pending_next_round_saw_starting = false;
+            self.update_task_running_state();
+            if mcp_startup_owned_status {
+                self.restore_reasoning_status_header();
+            }
+            self.maybe_send_next_queued_input();
+            self.request_redraw();
+        }
+    }
 }

codex-rs/tui/src/chatwidget/session_flow.rs

@@ -141,7 +141,10 @@ impl ChatWidget {
         {
             self.emit_forked_thread_event(forked_from_id, fork_parent_title);
         }
-        if !self.suppress_session_configured_redraw {
+        // Normal display queues session info into terminal history, which schedules the frame
+        // that commits the header and repaints the composer atomically. Redrawing before that
+        // history insert is processed can briefly show the composer without its header.
+        if display != SessionConfiguredDisplay::Normal {
             self.request_redraw();
         }
     }

codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__mcp_startup_status_is_hidden_by_default.snap

@@ -0,0 +1,9 @@
+---
+source: tui/src/chatwidget/tests/mcp_startup.rs
+expression: normalized_backend_snapshot(terminal.backend())
+---
+"                                                                                "
+"                                                                                "
+"› Ask Codex to do anything                                                      "
+"                                                                                "
+"  gpt-5.5 default · /tmp/project                                                "

codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__startup_header_handoff_visible_states.snap

@@ -0,0 +1,28 @@
+---
+source: tui/src/chatwidget/tests/status_and_layout.rs
+expression: "format!(\"provisional live frame:\\n{placeholder}\\n\\ncommitted history:\\n{committed_header}\")"
+---
+provisional live frame:
+"                                                                                "
+"╭───────────────────────────────────────╮                                       "
+"│ >_ OpenAI Codex (v0.0.0)              │                                       "
+"│                                       │                                       "
+"│ model:     loading   /model to change │                                       "
+"│ directory: /tmp/project               │                                       "
+"╰───────────────────────────────────────╯                                       "
+"                                                                                "
+"                                                                                "
+"› Explain this codebase                                                         "
+"                                                                                "
+"  gpt-5.5 default · /tmp/project                                                "
+
+
+committed history:
+╭────────────────────────────────────────────────╮
+│ >_ OpenAI Codex (v0.0.0)                       │
+│                                                │
+│ model:     configured-model   /model to change │
+│ directory: /tmp/project                        │
+╰────────────────────────────────────────────────╯
+
+  Tip: This is a test announcement

codex-rs/tui/src/chatwidget/status_surfaces.rs

@@ -781,8 +781,8 @@ impl ChatWidget {
 
     /// Computes the compact runtime status label used by word-based status items.
     ///
-    /// Startup takes precedence over normal task states, and idle state renders
-    /// as `Ready` regardless of the last active status bucket.
+    /// Visible diagnostic startup takes precedence over normal task states, and
+    /// idle state renders as `Ready` regardless of the last active status bucket.
     pub(super) fn run_state_status_text(&self) -> String {
         if self.mcp_startup_status.is_some() {
             return "Starting".to_string();

codex-rs/tui/src/chatwidget/tests/helpers.rs

@@ -63,6 +63,30 @@ pub(super) fn normalize_snapshot_paths(text: impl Into<String>) -> String {
     }
 }
 
+/// Normalizes platform-specific test paths without collapsing box alignment.
+pub(super) fn normalize_box_snapshot_paths(text: &str) -> String {
+    let mut normalized = text
+        .lines()
+        .map(|rendered| {
+            let normalized = normalize_snapshot_paths(rendered);
+            let padding = rendered
+                .chars()
+                .count()
+                .saturating_sub(normalized.chars().count());
+            if let Some((content, suffix)) = normalized.rsplit_once('│') {
+                format!("{content}{}│{suffix}", " ".repeat(padding))
+            } else {
+                normalized
+            }
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+    if text.ends_with('\n') {
+        normalized.push('\n');
+    }
+    normalized
+}
+
 pub(super) fn normalized_backend_snapshot<T: std::fmt::Display>(value: &T) -> String {
     let platform_test_cwd = test_path_display("/tmp/project");
     let rendered = format!("{value}");
@@ -71,7 +95,7 @@ pub(super) fn normalized_backend_snapshot<T: std::fmt::Display>(value: &T) -> St
         return rendered;
     }
 
-    rendered
+    let mut normalized = rendered
         .lines()
         .map(|line| {
             if let Some(content) = line
@@ -79,14 +103,18 @@ pub(super) fn normalized_backend_snapshot<T: std::fmt::Display>(value: &T) -> St
                 .and_then(|line| line.strip_suffix('"'))
             {
                 let width = content.chars().count();
-                let normalized = normalize_snapshot_paths(content);
+                let normalized = normalize_box_snapshot_paths(content);
                 format!("\"{normalized:width$}\"")
             } else {
                 normalize_snapshot_paths(line)
             }
         })
         .collect::<Vec<_>>()
-        .join("\n")
+        .join("\n");
+    if rendered.ends_with('\n') {
+        normalized.push('\n');
+    }
+    normalized
 }
 
 pub(super) fn invalid_value(

codex-rs/tui/src/chatwidget/tests/mcp_startup.rs

@@ -2,6 +2,7 @@ use super::*;
 use pretty_assertions::assert_eq;
 
 fn notify_mcp_status(chat: &mut ChatWidget, name: &str, status: McpServerStartupState) {
+    chat.config.tui_show_mcp_startup_status = true;
     chat.handle_server_notification(
         ServerNotification::McpServerStatusUpdated(McpServerStatusUpdatedNotification {
             name: name.to_string(),
@@ -13,6 +14,7 @@ fn notify_mcp_status(chat: &mut ChatWidget, name: &str, status: McpServerStartup
 }
 
 fn notify_mcp_status_error(chat: &mut ChatWidget, name: &str, error: &str) {
+    chat.config.tui_show_mcp_startup_status = true;
     chat.handle_server_notification(
         ServerNotification::McpServerStatusUpdated(McpServerStatusUpdatedNotification {
             name: name.to_string(),
@@ -23,6 +25,47 @@ fn notify_mcp_status_error(chat: &mut ChatWidget, name: &str, error: &str) {
     );
 }
 
+#[tokio::test]
+async fn mcp_startup_status_is_hidden_by_default_snapshot() {
+    let (mut chat, mut rx, _op_rx) = make_chatwidget_manual(/*model_override*/ None).await;
+    chat.show_welcome_banner = false;
+    chat.set_mcp_startup_expected_servers(["alpha".to_string()]);
+
+    chat.handle_server_notification(
+        ServerNotification::McpServerStatusUpdated(McpServerStatusUpdatedNotification {
+            name: "alpha".to_string(),
+            status: McpServerStartupState::Starting,
+            error: None,
+        }),
+        /*replay_kind*/ None,
+    );
+    chat.handle_server_notification(
+        ServerNotification::McpServerStatusUpdated(McpServerStatusUpdatedNotification {
+            name: "alpha".to_string(),
+            status: McpServerStartupState::Failed,
+            error: Some("MCP client for `alpha` failed to start: handshake failed".to_string()),
+        }),
+        /*replay_kind*/ None,
+    );
+
+    assert!(chat.mcp_startup_status.is_none());
+    assert!(!chat.bottom_pane.is_task_running());
+    assert!(drain_insert_history(&mut rx).is_empty());
+
+    let height = chat.desired_height(/*width*/ 80);
+    let mut terminal = ratatui::Terminal::new(ratatui::backend::TestBackend::new(
+        /*width*/ 80, height,
+    ))
+    .expect("create terminal");
+    terminal
+        .draw(|f| chat.render(f.area(), f.buffer_mut()))
+        .expect("draw chat widget");
+    assert_chatwidget_snapshot!(
+        "mcp_startup_status_is_hidden_by_default",
+        normalized_backend_snapshot(terminal.backend())
+    );
+}
+
 #[tokio::test]
 async fn mcp_startup_header_booting_snapshot() {
     let (mut chat, _rx, _op_rx) = make_chatwidget_manual(/*model_override*/ None).await;

codex-rs/tui/src/chatwidget/tests/status_and_layout.rs

@@ -1579,6 +1579,89 @@ async fn ui_snapshots_small_heights_task_running() {
     }
 }
 
+#[tokio::test]
+async fn startup_header_handoff_visible_states_snapshot() {
+    let (tx_raw, mut rx) = unbounded_channel::<AppEvent>();
+    let tx = AppEventSender::new(tx_raw);
+    let cfg = test_config().await;
+    let resolved_model = crate::legacy_core::test_support::get_model_offline(cfg.model.as_deref());
+    let init = ChatWidgetInit {
+        config: cfg.clone(),
+        frame_requester: FrameRequester::test_dummy(),
+        app_event_tx: tx,
+        workspace_command_runner: None,
+        initial_user_message: None,
+        enhanced_keys_supported: false,
+        has_chatgpt_account: false,
+        model_catalog: test_model_catalog(&cfg),
+        feedback: codex_feedback::CodexFeedback::new(),
+        is_first_run: false,
+        status_account_display: None,
+        runtime_model_provider_base_url: None,
+        initial_plan_type: None,
+        model: Some(resolved_model.clone()),
+        startup_tooltip_override: Some("This is a test announcement".to_string()),
+        status_line_invalid_items_warned: Arc::new(AtomicBool::new(false)),
+        terminal_title_invalid_items_warned: Arc::new(AtomicBool::new(false)),
+        session_telemetry: test_session_telemetry(&cfg, resolved_model.as_str()),
+    };
+    let mut chat = ChatWidget::new_with_app_event(init);
+    chat.normal_placeholder_text = "Explain this codebase".to_string();
+    chat.bottom_pane
+        .set_placeholder_text(chat.normal_placeholder_text.clone());
+    let width = 80;
+    let height = chat.desired_height(width);
+    let mut terminal =
+        ratatui::Terminal::new(TestBackend::new(width, height)).expect("create terminal");
+    terminal
+        .draw(|f| chat.render(f.area(), f.buffer_mut()))
+        .expect("draw placeholder header");
+    let placeholder = normalized_backend_snapshot(terminal.backend());
+
+    let rollout_file = NamedTempFile::new().expect("rollout file");
+    chat.handle_thread_session(crate::session_state::ThreadSessionState {
+        thread_id: ThreadId::new(),
+        forked_from_id: None,
+        fork_parent_title: None,
+        thread_name: None,
+        model: "configured-model".to_string(),
+        model_provider_id: "test-provider".to_string(),
+        service_tier: None,
+        approval_policy: AskForApproval::Never,
+        approvals_reviewer: ApprovalsReviewer::User,
+        permission_profile: PermissionProfile::read_only(),
+        active_permission_profile: None,
+        cwd: test_path_buf("/tmp/project").abs(),
+        runtime_workspace_roots: Vec::new(),
+        instruction_source_paths: Vec::new(),
+        reasoning_effort: None,
+        collaboration_mode: None,
+        personality: None,
+        message_history: None,
+        network_proxy: None,
+        rollout_path: Some(rollout_file.path().to_path_buf()),
+    });
+
+    assert!(chat.is_session_header_commit_pending());
+    let committed_header = loop {
+        match rx.try_recv() {
+            Ok(AppEvent::InsertHistoryCell(cell))
+                if cell.as_any().is::<history_cell::SessionInfoCell>() =>
+            {
+                let rendered = lines_to_single_string(&cell.display_lines(width));
+                break normalize_box_snapshot_paths(&rendered);
+            }
+            Ok(_) => continue,
+            other => panic!("expected queued configured header, got {other:?}"),
+        }
+    };
+
+    assert_chatwidget_snapshot!(
+        "startup_header_handoff_visible_states",
+        format!("provisional live frame:\n{placeholder}\n\ncommitted history:\n{committed_header}")
+    );
+}
+
 #[tokio::test]
 #[serial]
 async fn ambient_pet_stays_hidden_until_a_pet_is_selected() {

codex-rs/tui/src/chatwidget/turn_runtime.rs

@@ -8,8 +8,8 @@ use super::*;
 impl ChatWidget {
     /// Synchronize the bottom-pane "task running" indicator with the current lifecycles.
     ///
-    /// The bottom pane only has one running flag, but this module treats it as a derived state of
-    /// both the agent turn lifecycle and MCP startup lifecycle.
+    /// The bottom pane only has one running flag, but MCP startup enters this
+    /// visible lifecycle only when its diagnostic presentation is enabled.
     pub(super) fn update_task_running_state(&mut self) {
         self.bottom_pane.set_task_running(
             self.turn_lifecycle.agent_turn_running || self.mcp_startup_status.is_some(),