Lightweight coding agent that runs in your terminal
Rust
Preserve agent state when unloading idle multi-agent v2 children (#52034)
jifd2a6dac20b3b
diff --git a/codex-rs/app-server/src/request_processors/thread_lifecycle.rs b/codex-rs/app-server/src/request_processors/thread_lifecycle.rsindex 34fff277d4..1c7535455a 100644--- a/codex-rs/app-server/src/request_processors/thread_lifecycle.rs+++ b/codex-rs/app-server/src/request_processors/thread_lifecycle.rs@@ -1,8 +1,11 @@use super::*;use crate::extensions::send_thread_warning;use codex_app_server_protocol::ThreadQueueChangedNotification;+use codex_core::ThreadEvictionOutcome;use codex_extension_api::ThreadIdleCause;use codex_protocol::config_types::MultiAgentMode;+use codex_protocol::protocol::MultiAgentVersion;+use codex_protocol::protocol::SessionSource;#[derive(Clone)]pub(super) struct ListenerTaskContext {@@ -93,6 +96,7 @@ impl UnloadingState {if let Some(target) = unloading_target&& target <= Instant::now(){+ tokio::task::yield_now().await;return true;}let unloading_sleep = async {@@ -222,6 +226,10 @@ pub(super) fn log_listener_attach_result(}}+#[expect(+ clippy::await_holding_invalid_type,+ reason = "listener removal must be serialized against new subscriptions"+)]pub(super) async fn ensure_listener_task_running(listener_task_context: ListenerTaskContext,conversation_id: ThreadId,@@ -251,6 +259,8 @@ pub(super) async fn ensure_listener_task_running().await;let config_snapshot = conversation.config_snapshot().await;+ let is_v2_child = conversation.multi_agent_version() == Some(MultiAgentVersion::V2)+ && matches!(config_snapshot.session_source, SessionSource::SubAgent(_));let thread_settings_baseline = thread_settings_from_config_snapshot(&config_snapshot);let (mut listener_command_rx, listener_generation) = {let mut thread_state = thread_state.lock().await;@@ -392,6 +402,60 @@ pub(super) async fn ensure_listener_task_running(}pending_thread_unloads.insert(conversation_id);}+ if is_v2_child {+ let eviction = thread_manager.try_evict_v2_thread(Arc::clone(&conversation));+ tokio::pin!(eviction);+ let result = match tokio::time::timeout(+ Duration::from_secs(/*secs*/ 10), &mut eviction,+ ).await {+ Ok(result) => result,+ Err(_) => {+ warn!(event.name = "codex.app_server.thread_shutdown_slow", "thread {conversation_id} shutdown is taking longer than expected; continuing to wait");+ eviction.await+ }+ };+ let outcome = match result {+ Ok(ThreadEvictionOutcome::Busy) => {+ pending_thread_unloads.lock().await.remove(&conversation_id);+ unloading_state.note_thread_activity_observed();+ continue;+ }+ Ok(outcome @ (ThreadEvictionOutcome::Evicted | ThreadEvictionOutcome::NotCurrent)) => outcome,+ Err(err) => {+ warn!("failed to evict thread {conversation_id}: {err}");+ pending_thread_unloads.lock().await.remove(&conversation_id);+ unloading_state.note_thread_activity_observed();+ continue;+ }+ };+ {+ let mut pending = pending_thread_unloads.lock().await;+ if !thread_state_manager.remove_unsubscribed_listener(+ conversation_id, &thread_state, listener_generation,+ ).await {+ pending.remove(&conversation_id);+ break;+ }+ }+ // Release the status receiver before removing its watch entry.+ drop(unloading_state);+ outgoing_for_task+ .cancel_requests_for_thread(conversation_id, /*error*/ None)+ .await;+ // A runtime removed by someone else may already have a replacement.+ if outcome == ThreadEvictionOutcome::Evicted {+ thread_watch_manager+ .remove_thread(&conversation_id.to_string())+ .await;+ outgoing_for_task+ .send_server_notification(ServerNotification::ThreadClosed(+ ThreadClosedNotification { thread_id: conversation_id.to_string() },+ ))+ .await;+ }+ pending_thread_unloads.lock().await.remove(&conversation_id);+ return;+ }unload_thread_without_subscribers(thread_manager.clone(),outgoing_for_task.clone(),diff --git a/codex-rs/app-server/src/thread_state.rs b/codex-rs/app-server/src/thread_state.rsindex a19c41b19f..7ef7e0f20e 100644--- a/codex-rs/app-server/src/thread_state.rs+++ b/codex-rs/app-server/src/thread_state.rs@@ -501,6 +501,32 @@ impl ThreadStateManager {}}+ /// Removes an unsubscribed listener's entry without clearing a replacement's state.+ #[expect(+ clippy::await_holding_invalid_type,+ reason = "the listener generation must stay fixed while removing its map entry"+ )]+ pub(crate) async fn remove_unsubscribed_listener(+ &self,+ thread_id: ThreadId,+ expected: &Arc<Mutex<ThreadState>>,+ generation: u64,+ ) -> bool {+ let mut thread_state = expected.lock().await;+ let mut state = self.state.lock().await;+ if thread_state.listener_generation != generation+ || !state.threads.get(&thread_id).is_some_and(|entry| {+ Arc::ptr_eq(&entry.state, expected) && entry.connection_ids.is_empty()+ })+ {+ return false;+ }+ state.threads.remove(&thread_id);+ self.unregister_listener_command_tx(thread_id);+ thread_state.clear_listener();+ true+ }+pub(crate) async fn clear_all_listeners(&self) {let thread_states = {let state = self.state.lock().await;diff --git a/codex-rs/app-server/tests/suite/v2/thread_unsubscribe.rs b/codex-rs/app-server/tests/suite/v2/thread_unsubscribe.rsindex cddbccb317..289859b26a 100644--- a/codex-rs/app-server/tests/suite/v2/thread_unsubscribe.rs+++ b/codex-rs/app-server/tests/suite/v2/thread_unsubscribe.rs@@ -2,6 +2,7 @@ use anyhow::Result;use app_test_support::MockResponsesConfig;use app_test_support::TestAppServer;use app_test_support::create_mock_responses_server_repeating_assistant;+use app_test_support::write_models_cache;use codex_app_server_protocol::ClientRequest;use codex_app_server_protocol::DynamicToolCallOutputContentItem;use codex_app_server_protocol::DynamicToolCallParams;@@ -28,6 +29,7 @@ use codex_app_server_protocol::ThreadUnsubscribeStatus;use codex_app_server_protocol::TurnStartParams;use codex_app_server_protocol::TurnStartResponse;use codex_app_server_protocol::UserInput as V2UserInput;+use codex_features::Feature;use core_test_support::responses;use core_test_support::streaming_sse::StreamingSseChunk;use core_test_support::streaming_sse::start_streaming_sse_server;@@ -522,3 +524,188 @@ async fn wait_for_dynamic_tool_started(}}}++#[tokio::test]+async fn v2_child_idle_eviction_preserves_mail_and_followup_context() -> Result<()> {+ let server = responses::start_mock_server().await;+ let codex_home = TempDir::new()?;+ MockResponsesConfig::new(&server.uri())+ .with_model("gpt-5.5")+ .enable_feature(Feature::MultiAgentV2)+ .with_root_config("thread_unload_delay_secs = 0")+ .write(codex_home.path())?;+ write_models_cache(codex_home.path()).await?;+ let mut mcp = TestAppServer::builder()+ .with_codex_home(codex_home.path())+ .build_initialized()+ .await?;+ let parent = mcp.start_thread(ThreadStartParams::default()).await?.thread;+ let mut child_id = None;++ for (tool, args) in [+ (+ "spawn_agent",+ json!({+ "task_name": "worker", "fork_turns": "none", "message": "Initial child task"+ }),+ ),+ (+ "send_message",+ json!({"target": "worker", "message": "Unread note for later"}),+ ),+ (+ "followup_task",+ json!({"target": "worker", "message": "Continue the child task"}),+ ),+ ] {+ let call_id = format!("idle-eviction-{tool}");+ let _call = responses::mount_sse_once_match(+ &server,+ wiremock::matchers::header("thread-id", parent.id.clone()),+ responses::sse(vec![+ responses::ev_function_call_with_namespace(+ &call_id,+ "collaboration",+ tool,+ &args.to_string(),+ ),+ responses::ev_completed("parent-call"),+ ]),+ )+ .await;+ let _parent_done = responses::mount_sse_once_match(+ &server,+ move |request: &wiremock::Request| {+ String::from_utf8_lossy(&request.body).contains(&call_id)+ },+ responses::sse(vec![responses::ev_completed("parent-done")]),+ )+ .await;+ if tool != "send_message" {+ let parent_id = parent.id.clone();+ let _child = responses::mount_sse_once_match(+ &server,+ move |request: &wiremock::Request| {+ request+ .headers+ .get("thread-id")+ .is_some_and(|id| id != parent_id.as_str())+ },+ responses::sse(vec![+ responses::ev_assistant_message(+ "child-result",+ "Remember the initial child result",+ ),+ responses::ev_completed("child-done"),+ ]),+ )+ .await;+ }+ timeout(+ DEFAULT_READ_TIMEOUT,+ mcp.start_turn_and_wait_for_completion(TurnStartParams {+ thread_id: parent.id.clone(),+ input: vec![V2UserInput::Text {+ text: format!("Run {tool}"),+ text_elements: Vec::new(),+ }],+ ..Default::default()+ }),+ )+ .await??;++ if tool != "send_message" {+ let completed = timeout(+ DEFAULT_READ_TIMEOUT,+ mcp.read_stream_until_matching_notification(+ "child turn completed",+ |notification| {+ notification.method == "turn/completed"+ && notification+ .params+ .as_ref()+ .is_some_and(|params| params["threadId"] != parent.id)+ },+ ),+ )+ .await??;+ let params = completed.params.expect("child completion params");+ let completed_child = params["threadId"].as_str().expect("child ID").to_string();+ if let Some(child_id) = &child_id {+ assert_eq!(&completed_child, child_id);+ } else {+ child_id = Some(completed_child);+ }+ } else {+ // Mail is queued while subscribed. Unsubscribe lets the actual child listener+ // evict it; the parent stays loaded so the follow-up uses the same agent tree.+ let child_id = child_id.clone().expect("spawned child");+ let unsubscribed: ThreadUnsubscribeResponse = mcp+ .request(|request_id| ClientRequest::ThreadUnsubscribe {+ request_id,+ params: ThreadUnsubscribeParams {+ thread_id: child_id.clone(),+ },+ })+ .await?;+ assert_eq!(unsubscribed.status, ThreadUnsubscribeStatus::Unsubscribed);+ let closed: ThreadClosedNotification =+ timeout(DEFAULT_READ_TIMEOUT, mcp.read_notification("thread/closed")).await??;+ assert_eq!(+ closed,+ ThreadClosedNotification {+ thread_id: child_id.clone()+ }+ );+ let loaded: ThreadLoadedListResponse = mcp+ .request(|request_id| ClientRequest::ThreadLoadedList {+ request_id,+ params: ThreadLoadedListParams::default(),+ })+ .await?;+ assert_eq!(loaded.data, vec![parent.id.clone()]);+ assert_eq!(+ responses::received_responses_requests(&server)+ .await+ .iter()+ .filter(+ |request| request.header("thread-id").as_deref() == Some(child_id.as_str())+ )+ .count(),+ 1,+ "queue-only mail must not start another child turn",+ );+ }+ }+ let child_id = child_id.expect("spawned child");+ let requests = responses::received_responses_requests(&server).await;+ let child_requests: Vec<_> = requests+ .iter()+ .filter(|request| request.header("thread-id").as_deref() == Some(child_id.as_str()))+ .collect();+ assert_eq!(child_requests.len(), 2);+ assert_eq!(+ child_requests[1]+ .inputs_of_type("message")+ .into_iter()+ .filter(|item| item["role"] == "assistant")+ .collect::<Vec<_>>(),+ vec![json!({+ "type": "message", "role": "assistant",+ "content": [{"type": "output_text", "text": "Remember the initial child result"}],+ })],+ );+ for message in ["Unread note for later", "Continue the child task"] {+ assert_eq!(+ child_requests[1]+ .inputs_of_type("agent_message")+ .iter()+ .filter(|item| item.to_string().contains(message))+ .count(),+ 1,+ "resumed child must receive {message} exactly once",+ );+ }+ mcp.shutdown_gracefully().await?;+ Ok(())+}diff --git a/codex-rs/core/src/agent/control.rs b/codex-rs/core/src/agent/control.rsindex a8d57e19ce..895cd26802 100644--- a/codex-rs/core/src/agent/control.rs+++ b/codex-rs/core/src/agent/control.rs@@ -73,6 +73,7 @@ mod interrupt;mod legacy;mod mailbox;mod residency;+pub use residency::ThreadEvictionOutcome;mod resume;mod root_handoff;mod runtime;diff --git a/codex-rs/core/src/agent/control/api.rs b/codex-rs/core/src/agent/control/api.rsindex ef0a699486..4087cde92b 100644--- a/codex-rs/core/src/agent/control/api.rs+++ b/codex-rs/core/src/agent/control/api.rs@@ -110,10 +110,12 @@ impl AgentControl for LocalAgentControl {let (metadata, submission_id) = match input {AgentInput::UserInput(input) => {let receiver = self.get_agent_metadata(target);- if receiver.is_some() {+ let _residency_pin = if receiver.is_some() {self.ensure_v2_agent_loaded(resume_config, target, /*parent*/ None)- .await?;- }+ .await?+ } else {+ None+ };let submission_id = self.send_input(target, input, start_options).await?;(receiver.unwrap_or_default(), submission_id)}@@ -140,13 +142,15 @@ impl AgentControl for LocalAgentControl {// locally evicted recipients can retain mail without reloading.// Loaded recipients go straight to delivery, which rejects sends// racing an in-progress eviction when it acquires the residency pin.- if mode == MessageDeliveryMode::TriggerTurn+ let _residency_pin = if mode == MessageDeliveryMode::TriggerTurn|| (self.runtime.upgrade()?.get_thread(target).await.is_err()&& self.runtime.registry.evicted_environments(target).is_none()){self.ensure_v2_agent_loaded(resume_config, target, /*parent*/ None)- .await?;- }+ .await?+ } else {+ None+ };let communication = message.into_communication(author, receiver_path, mode);let kind = match mode {MessageDeliveryMode::QueueOnly => {@@ -191,6 +195,7 @@ impl AgentControl for LocalAgentControl {let config = parent.session.get_config().await.as_ref().clone();self.ensure_v2_agent_loaded(config, child, Some(parent)).await+ .map(drop)})}diff --git a/codex-rs/core/src/agent/control/residency.rs b/codex-rs/core/src/agent/control/residency.rsindex dd53eb6f2c..4755c221f8 100644--- a/codex-rs/core/src/agent/control/residency.rs+++ b/codex-rs/core/src/agent/control/residency.rs@@ -1,3 +1,5 @@+//! Accounts for resident MAv2 children and unloads exact idle runtimes while preserving their state.+use super::LocalAgentControl;use super::LocalAgentRuntime;use super::runtime::AgentTreeMembership;@@ -18,6 +20,87 @@ use std::sync::Arc;use std::sync::Mutex;use tracing::warn;+/// The result of trying to unload one exact MAv2 child runtime.+#[derive(Debug, PartialEq, Eq)]+pub enum ThreadEvictionOutcome {+ /// Work or another teardown owns the runtime; retry later.+ Busy,+ /// This operation stopped and removed the runtime.+ Evicted,+ /// The runtime was removed or replaced; leave its replacement alone.+ NotCurrent,+}++impl ThreadManagerState {+ pub(crate) async fn try_evict_v2_thread(+ self: &Arc<Self>,+ thread: Arc<CodexThread>,+ membership: &AgentTreeMembership,+ ) -> CodexResult<ThreadEvictionOutcome> {+ let Ok(residency_guard) = Arc::clone(&thread.residency_gate).try_write_owned() else {+ return Ok(ThreadEvictionOutcome::Busy);+ };+ let thread_id = thread.session.thread_id;+ if !self+ .get_thread(thread_id)+ .await+ .is_ok_and(|registered| Arc::ptr_eq(®istered, &thread))+ {+ return Ok(ThreadEvictionOutcome::NotCurrent);+ }+ if !is_resident_candidate(&thread) || !is_unloadable(&thread).await {+ return Ok(ThreadEvictionOutcome::Busy);+ }+ let manager = Arc::clone(self);+ let teardown = membership+ .clone()+ .into_teardown_guard("resident_eviction", Some(thread_id));+ // Once shutdown is submitted, cancellation cannot release delivery or capacity early.+ tokio::spawn(async move {+ let _residency_guard = residency_guard;+ thread.ensure_rollout_materialized().await;+ if let Err(err) = thread.shutdown_and_wait().await {+ teardown.record_shutdown_failure("stop_resident", CodexErrKind::from(&err).into());+ teardown.complete();+ return Err(err);+ }+ // Dispatch has stopped and the residency guard excludes senders. A tree+ // shutdown deliberately discards its mailbox instead of retaining it.+ let mail = thread+ .session+ .input_queue+ .drain_mailbox()+ .await+ .into_iter()+ .map(|mail| mail.communication)+ .collect();+ let runtime = &thread.session.services.local_agent_runtime;+ let _ = runtime.mailboxes.enqueue(thread_id, /*id*/ None, mail);+ let environments = thread.environment_selections().await;+ let mut threads = manager.threads.write().await;+ if threads+ .get(&thread_id)+ .is_some_and(|registered| !Arc::ptr_eq(registered, &thread))+ {+ teardown.complete();+ return Ok(ThreadEvictionOutcome::NotCurrent);+ }+ runtime+ .registry+ .save_evicted_environments(thread_id, environments);+ let removed = threads.remove(&thread_id).is_some();+ runtime.residency.remove(thread_id);+ teardown.complete();+ Ok(if removed {+ ThreadEvictionOutcome::Evicted+ } else {+ ThreadEvictionOutcome::NotCurrent+ })+ })+ .await?+ }+}+#[derive(Default)]pub(super) struct V2Residency {state: Mutex<V2ResidencyState>,@@ -65,16 +148,6 @@ impl LocalAgentControl {.await}- pub(super) async fn touch_loaded_v2_residency(- &self,- state: &Arc<ThreadManagerState>,- thread_id: ThreadId,- ) {- if let Ok(thread) = state.get_thread(thread_id).await {- let _ = self.runtime.pin_v2_residency(state, &thread).await;- }- }-pub(super) fn forget_v2_residency(&self, thread_id: ThreadId) {self.runtime.residency.remove(thread_id);}@@ -168,80 +241,22 @@ impl V2Residency {}}};- let Ok(residency_guard) =- Arc::clone(&candidate_thread.residency_gate).try_write_owned()- else {+ // Capacity eviction keeps its existing policy of retaining unstarted workers.+ if matches!(+ candidate_thread.agent_status().await,+ AgentStatus::PendingInit+ ) {continue;- };- if !manager- .get_thread(candidate_thread_id)+ }+ match manager+ .try_evict_v2_thread(candidate_thread, membership).await- .is_ok_and(|registered| Arc::ptr_eq(®istered, &candidate_thread))- || !is_unloadable(candidate_thread.as_ref()).await{- continue;- }- // Once shutdown is submitted, cancellation cannot revoke it. The eviction task- // must keep delivery excluded and capacity reserved through registry removal.- let manager = Arc::clone(manager);- let residency = Arc::clone(self);- let teardown = membership- .clone()- .into_teardown_guard("resident_eviction", Some(candidate_thread_id));- let eviction = tokio::spawn(async move {- let _residency_guard = residency_guard;- candidate_thread.ensure_rollout_materialized().await;- if let Err(err) = candidate_thread.shutdown_and_wait().await {- teardown- .record_shutdown_failure("stop_resident", CodexErrKind::from(&err).into());- warn!(- "failed to shut down v2 resident thread before unloading {candidate_thread_id}: {err}"- );- teardown.complete();- return false;- }- // The submission loop has stopped and the residency guard excludes senders.- // Preserve unread queue-only mail before dropping the session that held it.- let mail = candidate_thread- .session- .input_queue- .drain_mailbox()- .await- .into_iter()- .map(|mail| mail.communication)- .collect();- // A concurrent tree shutdown deliberately discards its unread mail.- let _ = candidate_thread- .session- .services- .local_agent_runtime- .mailboxes- .enqueue(candidate_thread_id, /*id*/ None, mail);- let environments = candidate_thread.environment_selections().await;- let mut threads = manager.threads.write().await;- if threads- .get(&candidate_thread_id)- .is_some_and(|registered| !Arc::ptr_eq(registered, &candidate_thread))- {- teardown.complete();- return false;+ Ok(ThreadEvictionOutcome::Evicted | ThreadEvictionOutcome::NotCurrent) => {+ return true;}- candidate_thread- .session- .services- .local_agent_runtime- .registry- .save_evicted_environments(candidate_thread_id, environments);- // Keep publication excluded until both entries have been removed.- threads.remove(&candidate_thread_id);- residency.remove(candidate_thread_id);- teardown.complete();- true- });- match eviction.await {- Ok(true) => return true,- Ok(false) => {}- Err(err) => warn!("v2 resident eviction task failed: {err}"),+ Ok(ThreadEvictionOutcome::Busy) => {}+ Err(err) => warn!("v2 resident eviction failed: {err}"),}}false@@ -298,7 +313,10 @@ pub(super) fn is_v2_resident_session_source(session_source: &SessionSource) -> basync fn is_unloadable(thread: &CodexThread) -> bool {matches!(thread.agent_status().await,- AgentStatus::Completed(_) | AgentStatus::Errored(_) | AgentStatus::Interrupted+ AgentStatus::PendingInit+ | AgentStatus::Completed(_)+ | AgentStatus::Errored(_)+ | AgentStatus::Interrupted) && thread.session.active_turn.lock().await.is_none()&& !thread.session.has_outstanding_durable_sleep()&& !threaddiff --git a/codex-rs/core/src/agent/control/spawn.rs b/codex-rs/core/src/agent/control/spawn.rsindex 20e28a8bfe..c370b49211 100644--- a/codex-rs/core/src/agent/control/spawn.rs+++ b/codex-rs/core/src/agent/control/spawn.rs@@ -320,12 +320,13 @@ impl LocalAgentControl {}/// A provided parent enables owner-validated reloads; `None` preserves sender-driven reloads.+ /// Keep the returned residency pin until the caller has submitted its input.pub(crate) async fn ensure_v2_agent_loaded(&self,mut config: Config,thread_id: ThreadId,parent: Option<Arc<CodexThread>>,- ) -> CodexResult<()> {+ ) -> CodexResult<Option<tokio::sync::OwnedRwLockReadGuard<()>>> {let membership = self.runtime.admit_start()?;let state = self.runtime.upgrade()?;let owner_thread_id = parent.as_ref().map(|parent| parent.session.thread_id);@@ -347,9 +348,10 @@ impl LocalAgentControl {)));}}- if owner_thread_id.is_none() && state.get_thread(thread_id).await.is_ok() {- self.touch_loaded_v2_residency(&state, thread_id).await;- return Ok(());+ if owner_thread_id.is_none()+ && let Ok(thread) = state.get_thread(thread_id).await+ {+ return self.runtime.pin_v2_residency(&state, &thread).await;}if self.runtime@@ -402,8 +404,7 @@ impl LocalAgentControl {}if let Ok(thread) = state.get_thread(thread_id).await {self.validate_loaded_v2_child(&thread, parent_thread_id)?;- self.touch_loaded_v2_residency(&state, thread_id).await;- return Ok(());+ return self.runtime.pin_v2_residency(&state, &thread).await;}}let parent = if let Some(parent) = parent {@@ -633,28 +634,37 @@ impl LocalAgentControl {if let Some(parent_thread_id) = owner_thread_id {self.validate_loaded_v2_child(&reloaded_thread.thread, parent_thread_id)?;}- self.runtime.registry.clear_evicted_environments(thread_id);- residency_slot.commit(reloaded_thread.thread_id);- // Register before listeners can forward events from the resumed thread.- if let Some((client_metadata, source)) = subagent_analytics {- let thread_config = reloaded_thread.thread.config_snapshot().await;- emit_subagent_session_started(- &reloaded_thread- .thread- .session- .services- .analytics_events_client,- client_metadata,- reloaded_thread.thread.session.session_id(),- reloaded_thread.thread_id,- thread_config.parent_thread_id,- thread_config,- source,- /*resumed_created_at*/ Some(stored_thread.created_at),- );- }- state.notify_thread_created(reloaded_thread.thread_id);- Ok(())+ let runtime = self.runtime.clone();+ // Finish registration even if the sender is cancelled while acquiring its pin.+ tokio::spawn(async move {+ let _membership = membership;+ let residency_pin = runtime+ .pin_v2_residency(&state, &reloaded_thread.thread)+ .await?;+ runtime.registry.clear_evicted_environments(thread_id);+ residency_slot.commit(reloaded_thread.thread_id);+ // Register before listeners can forward events from the resumed thread.+ if let Some((client_metadata, source)) = subagent_analytics {+ let thread_config = reloaded_thread.thread.config_snapshot().await;+ emit_subagent_session_started(+ &reloaded_thread+ .thread+ .session+ .services+ .analytics_events_client,+ client_metadata,+ reloaded_thread.thread.session.session_id(),+ reloaded_thread.thread_id,+ thread_config.parent_thread_id,+ thread_config,+ source,+ /*resumed_created_at*/ Some(stored_thread.created_at),+ );+ }+ state.notify_thread_created(reloaded_thread.thread_id);+ Ok(residency_pin)+ })+ .await?}Err(err) => {if let Ok(thread) = state.get_thread(thread_id).await {@@ -663,8 +673,7 @@ impl LocalAgentControl {}self.runtime.registry.clear_evicted_environments(thread_id);drop(residency_slot);- self.touch_loaded_v2_residency(&state, thread_id).await;- return Ok(());+ return self.runtime.pin_v2_residency(&state, &thread).await;}Err(err)}diff --git a/codex-rs/core/src/agent/control_tests.rs b/codex-rs/core/src/agent/control_tests.rsindex 801d4d9f4b..902f86dc39 100644--- a/codex-rs/core/src/agent/control_tests.rs+++ b/codex-rs/core/src/agent/control_tests.rs@@ -1168,7 +1168,7 @@ async fn check_v2_agent_reload(route: V2ReloadRoute) {.expect("ollama provider should be configured");let mut parent_turn = parent_thread.session.new_default_turn().await;- match route {+ let residency_pin = match route {V2ReloadRoute::Sender => control.ensure_v2_agent_loaded(sender_config, spawned_agent.thread_id, /*parent*/ None).await@@ -1208,13 +1208,24 @@ async fn check_v2_agent_reload(route: V2ReloadRoute) {.expect("known child should reload through its parent");parent_turn = parent_thread.session.new_default_turn().await;assert!(harness.manager.get_thread(parent_thread_id).await.is_err());+ None}- }+ };let reloaded_child = harness.manager.get_thread(spawned_agent.thread_id).await.expect("reloaded child thread should exist");+ if matches!(route, V2ReloadRoute::Sender) {+ assert_eq!(+ harness+ .manager+ .try_evict_v2_thread(Arc::clone(&reloaded_child))+ .await+ .expect("attempt eviction before input submission"),+ crate::ThreadEvictionOutcome::Busy,+ );+ }let reloaded_instructions = reloaded_child.session.inherited_instructions().await;assert_eq!((reloaded_instructions.user, reloaded_instructions.thread),@@ -1279,6 +1290,7 @@ async fn check_v2_agent_reload(route: V2ReloadRoute) {).await.expect("send_inter_agent_communication should succeed after reload");+ drop(residency_pin);let expected = (spawned_agent.thread_id,Op::InterAgentCommunication {diff --git a/codex-rs/core/src/lib.rs b/codex-rs/core/src/lib.rsindex a2b44e3f1f..56f64aeeb6 100644--- a/codex-rs/core/src/lib.rs+++ b/codex-rs/core/src/lib.rs@@ -147,6 +147,7 @@ pub use codex_prompts as review_prompts;mod thread_manager;pub(crate) mod web_search;pub(crate) mod windows_sandbox_read_grants;+pub use agent::control::ThreadEvictionOutcome;pub use thread_manager::AgentTreeShutdown;pub use thread_manager::AgentTreeShutdownFailure;pub use thread_manager::AgentTreeShutdownFailureReason;diff --git a/codex-rs/core/src/thread_manager/shutdown.rs b/codex-rs/core/src/thread_manager/shutdown.rsindex 11f89bf39a..cfa4af1ca6 100644--- a/codex-rs/core/src/thread_manager/shutdown.rs+++ b/codex-rs/core/src/thread_manager/shutdown.rs@@ -1,8 +1,9 @@-//! Fences and signals one local agent tree, then exposes its teardown result.+//! Unloads locally controlled idle MAv2 children and exposes tracked agent-tree teardown.use super::ThreadManager;use crate::agent::control::AgentTreeShutdownState;use codex_protocol::ThreadId;+use codex_protocol::error::CodexErr;use codex_protocol::error::Result as CodexResult;use codex_thread_store::ThreadStoreError;use std::fmt;@@ -126,6 +127,26 @@ impl AgentTreeShutdown {}impl ThreadManager {+ /// Unloads this exact idle MAv2 child using the manager's local controller backend,+ /// preserving mail and environments for reloading. Host controllers own their eviction+ /// and recovery; managers configured with a host controller factory are rejected.+ /// Dropping the future after shutdown starts does not cancel cleanup.+ pub async fn try_evict_v2_thread(+ &self,+ thread: Arc<crate::CodexThread>,+ ) -> CodexResult<crate::ThreadEvictionOutcome> {+ // Backend selection is fixed before the manager is shared or starts any threads.+ if self.state.agent_control_factory.is_some() {+ return Err(CodexErr::InvalidRequest(+ "idle eviction requires the local agent controller".to_owned(),+ ));+ }+ let Ok(membership) = thread.session.services.local_agent_runtime.admit_start() else {+ return Ok(crate::ThreadEvictionOutcome::Busy);+ };+ self.state.try_evict_v2_thread(thread, &membership).await+ }+/// Requests shutdown of a loaded thread and every session sharing its local runtime.////// Returns after fencing new starts and signalling admitted sessions. Callers can wait on thediff --git a/codex-rs/core/src/tools/handlers/multi_agents/send_input.rs b/codex-rs/core/src/tools/handlers/multi_agents/send_input.rsindex 3d2942f119..9998a17367 100644--- a/codex-rs/core/src/tools/handlers/multi_agents/send_input.rs+++ b/codex-rs/core/src/tools/handlers/multi_agents/send_input.rs@@ -54,14 +54,16 @@ impl Handler {.local_agent_runtime.control(session.session_id());let receiver_agent = local_agent_control.get_agent_metadata(receiver_thread_id);- if receiver_agent.is_some() {+ let residency_pin = if receiver_agent.is_some() {let resume_config = build_agent_resume_config(turn.as_ref()).map_err(FunctionCallError::RespondToModel)?;local_agent_control.ensure_v2_agent_loaded(resume_config, receiver_thread_id, /*parent*/ None).await- .map_err(|err| collab_agent_error(receiver_thread_id, err))?;- }+ .map_err(|err| collab_agent_error(receiver_thread_id, err))?+ } else {+ None+ };let receiver_agent = receiver_agent.unwrap_or_default();if args.interrupt {session@@ -106,6 +108,7 @@ impl Handler {).await.map_err(|err| collab_agent_error(receiver_thread_id, err));+ drop(residency_pin);let status = local_agent_control.get_status(receiver_thread_id).await;session.emit_turn_item_completed(diff --git a/codex-rs/core/tests/suite/agent_control_tests.rs b/codex-rs/core/tests/suite/agent_control_tests.rsindex 41162eaea0..165165c7bf 100644--- a/codex-rs/core/tests/suite/agent_control_tests.rs+++ b/codex-rs/core/tests/suite/agent_control_tests.rs@@ -278,6 +278,28 @@ async fn host_threads_preserve_lineage_settings_and_resume_routing() -> anyhow::(controller.identity(), Some(root_id)));assert_eq!(controller.service_tier(), Some("priority".to_string()));+ let unread_mail = vec![codex_protocol::protocol::InterAgentCommunication::new(+ AgentPath::root(),+ AgentPath::root().join("worker").expect("valid child path"),+ Vec::new(),+ "Retain this in the host mailbox".into(),+ /*trigger_turn*/ false,+ )];+ *controller.mail.lock().expect("mail lock") = unread_mail.clone();+ let error = test+ .thread_manager+ .try_evict_v2_thread(Arc::clone(&child.thread))+ .await+ .expect_err("local eviction must reject a host-controlled child");+ assert!(matches!(+ error.details(),+ CodexErrorDetails::InvalidRequest(_)+ ));+ assert!(Arc::ptr_eq(+ &test.thread_manager.get_thread(child.thread_id).await?,+ &child.thread,+ ));+ assert_eq!(controller.take_mailbox(child.thread_id), unread_mail);child.thread.ensure_rollout_materialized().await;child.thread.flush_rollout().await?;let saved = test