Overlap subagent spawn persistence and clean up cancelled children (#47348)

## Why

Forked subagent startup serializes history persistence and spawn-edge writes. Cancellation during startup can also leave a provisional child behind.

## What changed

- Defer copied-history durability so it can run alongside spawn-edge persistence, while still awaiting both before submitting the child's initial input.
- Commit agent and residency reservations and notify clients only after initial input is accepted.
- Guard provisional children so cancellation or startup failure removes and shuts them down, discards their stored state, and closes their spawn edge after any pending edge write finishes.

## Testing

Add coverage for cancellation at the child-history durability barrier, checking child termination, removal, and edge closure. Extend fork-context tests in legacy and paginated history modes to verify inherited context can be read from storage after spawn acknowledgment without flushing the live child first.

GitOrigin-RevId: e02dda57efc32b7237bb7af0ce5e5844922890c3
This commit is contained in:
Owen Lin
2026-09-22 19:39:18 +00:00
committed by copyberry
parent df30941072
commit 5121aeff13
10 changed files with 269 additions and 26 deletions
+1
View File
@@ -77,6 +77,7 @@ mod runtime;
mod sender_context;
mod service_tier;
mod spawn;
mod spawn_guard;
mod target;
mod user_authorization;
mod watch;
+37 -15
View File
@@ -1,4 +1,5 @@
use super::residency::is_v2_resident_session_source;
use super::spawn_guard::PendingSpawn;
use super::*;
use crate::agent::child_config::build_agent_resume_config;
use crate::agent::role::apply_role_to_config;
@@ -27,6 +28,7 @@ use codex_history::ResponseItemEnvelope;
use codex_prompts::ResolvedModelMessages;
use codex_protocol::intersect_effective_permission_profiles;
use codex_protocol::protocol::EnvironmentConfigState;
use codex_thread_store::PersistContext;
use codex_utils_path_uri::PathUri;
const AGENT_NAMES: &str = include_str!("../../../assets/agent/agent_names.txt");
@@ -732,10 +734,7 @@ impl LocalAgentControl {
(None, _, _) => Box::pin(state.spawn_new_thread(config.clone(), self.clone())).await?,
};
agent_metadata.agent_id = Some(new_thread.thread_id);
reservation.commit(agent_metadata.clone());
if let Some(residency_slot) = residency_slot {
residency_slot.commit(new_thread.thread_id);
}
let mut pending_spawn = PendingSpawn::new(Arc::clone(&state), new_thread.thread_id);
if let Some(SessionSource::SubAgent(
subagent_source @ SubAgentSource::ThreadSpawn {
@@ -770,17 +769,30 @@ impl LocalAgentControl {
);
}
// Notify a new thread has been created. This notification will be processed by clients
// to subscribe or drain this newly created thread.
// TODO(jif) add helper for drain
state.notify_thread_created(new_thread.thread_id);
self.persist_thread_spawn_edge_for_source(
new_thread.thread.as_ref(),
new_thread.thread_id,
notification_source.as_ref(),
)
.await;
let control = self.clone();
let child = Arc::clone(&new_thread.thread);
let child_thread_id = new_thread.thread_id;
let source = notification_source.clone();
pending_spawn.set_edge_write(tokio::spawn(async move {
control
.persist_thread_spawn_edge_for_source(
child.as_ref(),
child_thread_id,
source.as_ref(),
)
.await;
}));
if options.fork_mode.is_some() {
tokio::join!(
new_thread
.thread
.session
.ensure_rollout_materialized(PersistContext::Standard),
pending_spawn.wait_for_edge(),
);
} else {
pending_spawn.wait_for_edge().await;
}
let start_options = TurnStartOptions {
parent_turn_id: options.parent_turn_id,
@@ -805,6 +817,16 @@ impl LocalAgentControl {
.await?;
}
}
reservation.commit(agent_metadata.clone());
if let Some(residency_slot) = residency_slot {
residency_slot.commit(new_thread.thread_id);
}
pending_spawn.disarm();
// Notify a new thread has been created. This notification will be processed by clients
// to subscribe or drain this newly created thread.
// TODO(jif) add helper for drain
state.notify_thread_created(new_thread.thread_id);
if multi_agent_version != MultiAgentVersion::V2 {
let child_reference = agent_metadata
.agent_path
@@ -0,0 +1,75 @@
//! Owns a spawned child until its initial input is accepted.
use crate::thread_manager::ThreadManagerState;
use codex_agent_graph_store::ThreadSpawnEdgeStatus;
use codex_protocol::ThreadId;
use std::sync::Arc;
use tokio::task::JoinHandle;
use tracing::warn;
pub(super) struct PendingSpawn {
state: Arc<ThreadManagerState>,
child: Option<ThreadId>,
edge_write: Option<JoinHandle<()>>,
}
impl PendingSpawn {
pub(super) fn new(state: Arc<ThreadManagerState>, child: ThreadId) -> Self {
Self {
state,
child: Some(child),
edge_write: None,
}
}
pub(super) fn set_edge_write(&mut self, edge_write: JoinHandle<()>) {
self.edge_write = Some(edge_write);
}
pub(super) async fn wait_for_edge(&mut self) {
if let Some(edge_write) = self.edge_write.as_mut() {
assert!(
edge_write.await.is_ok(),
"spawn edge write task should complete"
);
}
self.edge_write = None;
}
pub(super) fn disarm(mut self) {
self.child = None;
}
}
impl Drop for PendingSpawn {
fn drop(&mut self) {
let Some(child) = self.child.take() else {
return;
};
let state = Arc::clone(&self.state);
let edge_write = self.edge_write.take();
drop(tokio::spawn(async move {
if let Some(thread) = state.remove_thread(&child).await {
if let Err(error) = thread.shutdown_and_wait().await {
warn!("failed to stop cancelled child spawn: {error}");
}
if let Some(live_thread) = thread.session.live_thread()
&& let Err(error) = live_thread.discard().await
{
warn!("failed to discard cancelled child spawn: {error}");
}
}
// A pending Open write must finish before cleanup writes Closed.
if let Some(edge_write) = edge_write {
let _ = edge_write.await;
}
if let Some(store) = state.agent_graph_store()
&& let Err(error) = store
.set_thread_spawn_edge_status(child, ThreadSpawnEdgeStatus::Closed)
.await
{
warn!("failed to close cancelled child spawn edge: {error}");
}
}));
}
}
+14 -5
View File
@@ -416,6 +416,8 @@ pub(crate) enum GitEnrichmentPolicy {
/// Controls which fork history belongs in the newly created thread's own rollout.
pub(crate) enum ForkPersistence {
Copied,
/// The spawn caller owns the durability barrier before acknowledging the child.
CopiedDeferred,
Referenced {
history_base: Option<HistoryPosition>,
inherited_item_count: usize,
@@ -1641,13 +1643,15 @@ impl Session {
rollout_items.drain(..*inherited_item_count);
rollout_items.insert(0, thread_settings_applied);
}
ForkPersistence::Copied if is_paginated_subagent => {
ForkPersistence::Copied | ForkPersistence::CopiedDeferred
if is_paginated_subagent =>
{
// Paginated subagents already persist inherited context when their live
// thread is created.
rollout_items.clear();
rollout_items.push(thread_settings_applied);
}
ForkPersistence::Copied => {
ForkPersistence::Copied | ForkPersistence::CopiedDeferred => {
// Keep the copied prefix and effective child settings in one append so a
// cold resume cannot observe inherited settings as the latest value.
rollout_items.push(thread_settings_applied);
@@ -1655,9 +1659,14 @@ impl Session {
}
self.persist_rollout_items(&rollout_items).await;
// Forked threads should remain file-backed immediately after startup.
self.ensure_rollout_materialized(PersistContext::Standard)
.await;
// Agent spawn owns its final durability barrier so it can overlap the edge write.
let persist_context = match self.fork_persistence {
ForkPersistence::CopiedDeferred => PersistContext::SubagentSpawn,
ForkPersistence::Copied | ForkPersistence::Referenced { .. } => {
PersistContext::Standard
}
};
self.ensure_rollout_materialized(persist_context).await;
// Flush after seeding history and any persisted rollout copy.
if !is_subagent {
+6 -3
View File
@@ -808,7 +808,7 @@ impl Session {
ForkPersistence::Referenced { history_base, .. } => {
history_base.map(|position| position.end_ordinal_exclusive)
}
ForkPersistence::Copied => match &initial_history {
ForkPersistence::Copied | ForkPersistence::CopiedDeferred => match &initial_history {
InitialHistory::Resumed(resumed) => {
// Both local and CCA thread stores place the resumed thread's
// canonical SessionMeta first. Never inspect inherited metadata:
@@ -1018,7 +1018,7 @@ impl Session {
multi_agent_version: initial_multi_agent_version,
history_mode: session_configuration.history_mode,
history_base: match &fork_persistence {
ForkPersistence::Copied => None,
ForkPersistence::Copied | ForkPersistence::CopiedDeferred => None,
ForkPersistence::Referenced { history_base, .. } => *history_base,
},
subagent_history_start_ordinal: None,
@@ -1037,7 +1037,10 @@ impl Session {
},
};
if is_paginated_subagent
&& matches!(&fork_persistence, ForkPersistence::Copied)
&& matches!(
&fork_persistence,
ForkPersistence::Copied | ForkPersistence::CopiedDeferred
)
&& let InitialHistory::Forked(items) = &initial_history
{
LiveThread::create_with_inherited_model_context(
+1
View File
@@ -2009,6 +2009,7 @@ impl ThreadManagerState {
};
let mut request =
ThreadSpawnRequest::new(options, Arc::clone(&self.auth_manager), agent_control);
request.fork_persistence = ForkPersistence::CopiedDeferred;
request.parent_thread_id = parent_thread_id;
request.forked_from_thread_id = forked_from_thread_id;
request.inherited_environments = inherited_environments;