@team-agent/installer 0.5.57 → 0.5.58

package/Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.57"
+version = "0.5.58"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent", "crates/win-conpty-phase0", "crates/conpty-trans
 
 [workspace.package]
 edition = "2021"
-version = "0.5.57"
+version = "0.5.58"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

package/crates/team-agent/src/cli/mod.rs

@@ -2484,6 +2484,7 @@ pub mod lifecycle_port {
                 "new_agent_id": report.new_agent_id.as_str(),
                 "session_id": report.session_id.as_ref().map(|session| session.as_str()),
                 "new_session_id": report.session_id.as_ref().map(|session| session.as_str()),
+                "backing_state": report.backing_state,
             })),
             Err(e) => Ok(error_value(e)),
         }

package/crates/team-agent/src/lifecycle/launch/fork_agent.rs

@@ -57,66 +57,13 @@ pub fn fork_agent_with_transport(
     let text = std::fs::read_to_string(&read_spec_path)
         .map_err(|e| LifecycleError::Compile(format!("{}: {e}", read_spec_path.display())))?;
     let spec = yaml::loads(&text).map_err(|e| LifecycleError::Compile(e.to_string()))?;
-    if find_spec_agent(&spec, as_agent_id).is_some() || leader_id_matches(&spec, as_agent_id) {
+    if fork_spec_agent(&spec, as_agent_id).is_some() || leader_id_matches(&spec, as_agent_id) {
         return Err(LifecycleError::RequirementUnmet(format!(
             "agent id already exists: {as_agent_id}"
         )));
     }
-    let source_agent = find_spec_agent(&spec, source_agent_id).ok_or_else(|| {
-        LifecycleError::RequirementUnmet(format!("unknown worker agent id: {source_agent_id}"))
-    })?;
-    // Fork requires the complete source tuple before treating session_id as
-    // resumable truth; a scalar-only row has no confirmed backing.
-    let source_agent_state = state
-        .get("agents")
-        .and_then(|v| v.get(source_agent_id.as_str()))
-        .ok_or_else(|| {
-            LifecycleError::Provider(format!(
-                "cannot fork {source_agent_id}: source agent row not in state"
-            ))
-        })?;
-    let tuple_field_ok = |field: &str| -> bool {
-        source_agent_state
-            .get(field)
-            .and_then(|v| v.as_str())
-            .is_some_and(|s| !s.is_empty())
-    };
-    let session_id_str = source_agent_state
-        .get("session_id")
-        .and_then(|v| v.as_str())
-        .filter(|s| !s.is_empty());
-    let rollout_path_str = source_agent_state
-        .get("rollout_path")
-        .and_then(|v| v.as_str())
-        .filter(|s| !s.is_empty());
-    if session_id_str.is_none()
-        || rollout_path_str.is_none()
-        || !tuple_field_ok("captured_at")
-        || !tuple_field_ok("captured_via")
-    {
-        return Err(LifecycleError::Provider(format!(
-            "cannot fork {source_agent_id}: source session backing is missing or incomplete \
-             (session_id+rollout_path+captured_at+captured_via required)"
-        )));
-    }
-    let Some(source_backing_raw) = rollout_path_str else {
-        return Err(LifecycleError::Provider(format!(
-            "cannot fork {source_agent_id}: source session backing is missing"
-        )));
-    };
-    let source_backing = Path::new(source_backing_raw);
-    if !source_backing.is_file() {
-        return Err(LifecycleError::Provider(format!(
-            "cannot fork {source_agent_id}: source session backing is not readable: {}",
-            source_backing.display()
-        )));
-    }
-    let Some(source_session_id) = session_id_str else {
-        return Err(LifecycleError::Provider(format!(
-            "cannot fork {source_agent_id}: source session id is missing"
-        )));
-    };
-    let session_id = crate::provider::SessionId::new(source_session_id.to_string());
+    // Source existence authority: state.get("agents"), matching clone-agent.
+    let (session_id, source_backing) = fork_source_tuple(&state, source_agent_id)?;
     let session_name = state
         .get("session_name")
         .and_then(|v| v.as_str())
@@ -158,7 +105,7 @@ pub fn fork_agent_with_transport(
     crate::model::spec::validate_spec(&new_spec, &validate_ws)
         .map_err(|e| LifecycleError::Compile(e.to_string()))?;
     write_spec_atomic(&spec_path, &new_spec)?;
-    let new_agent = find_spec_agent(&new_spec, as_agent_id).ok_or_else(|| {
+    let new_agent = fork_spec_agent(&new_spec, as_agent_id).ok_or_else(|| {
         LifecycleError::RequirementUnmet(format!("unknown worker agent id: {as_agent_id}"))
     })?;
     let provider = new_agent
@@ -296,13 +243,21 @@ pub fn fork_agent_with_transport(
         plan.provider_projects_root = source_backing.parent().map(Path::to_path_buf);
     }
     let window = WindowName::new(as_agent_id.as_str());
+    let mut claude_fork = prepare_claude_fork_backing(
+        provider,
+        &plan,
+        &source_backing,
+        &session_id,
+    )
+    .map_err(|error| {
+        let _ = std::fs::write(&spec_path, text.as_bytes());
+        cleanup_fork_mcp_artifacts(&workspace, as_agent_id, &mcp_config_path, &profile_launch);
+        error
+    })?;
+    // The framework-created Claude snapshot is only fork input, not provider
+    // proof. Observe changes made after materialization so a spawn-only
+    // provider cannot turn the copied source backing into a Verified result.
     let backing_before = crate::provider::session::ContextBackingSnapshot::capture(provider, &plan);
-    let mut claude_fork = prepare_claude_fork_backing(provider, &plan, source_backing, &session_id)
-        .map_err(|error| {
-            let _ = std::fs::write(&spec_path, text.as_bytes());
-            cleanup_fork_mcp_artifacts(&workspace, as_agent_id, &mcp_config_path, &profile_launch);
-            error
-        })?;
     let mut env =
         inherited_env_with_team_overrides(&workspace, as_agent_id.as_str(), Some(&fork_team));
     apply_profile_launch_env(&mut env, &profile_launch);
@@ -401,7 +356,7 @@ pub fn fork_agent_with_transport(
     })?;
     let convergence_deadline =
         crate::provider::session::context_fork_convergence_deadline(provider);
-    let context_proof = match crate::provider::session::verify_context_fork(
+    let context_outcome = crate::provider::session::observe_context_fork(
         provider,
         &session_id,
         &plan,
@@ -411,9 +366,40 @@ pub fn fork_agent_with_transport(
         &workspace,
         &spawned_at,
         convergence_deadline,
-    ) {
-        Ok(proof) => proof,
-        Err(error) => {
+    );
+    let context_proof = match context_outcome {
+        crate::provider::session::ContextForkOutcome::Verified(proof) => Some(proof),
+        crate::provider::session::ContextForkOutcome::Pending(pending) => {
+            if let Err(error) = finalize_pending_fork_state(ForkPendingFinalizeInput {
+                workspace: &workspace,
+                team_key: &fork_team,
+                source_agent_id,
+                agent_id: as_agent_id,
+                spec_agent: new_agent,
+                safety: &safety,
+                plan: &plan,
+                profile_launch: &profile_launch,
+                spawn: &spawn,
+                profile_dir: &profile_dir,
+                dynamic_role_file: materialized_role.path(),
+                pending: &pending,
+                spawn_epoch,
+            }) {
+                rollback_fork_after_spawn(
+                    &workspace,
+                    transport,
+                    &session_name,
+                    &window,
+                    &mcp_config_path,
+                    as_agent_id,
+                    &profile_launch,
+                    &fork_team,
+                );
+                return Err(error);
+            }
+            None
+        }
+        crate::provider::session::ContextForkOutcome::Rejected(error) => {
             rollback_fork_after_spawn(
                 &workspace,
                 transport,
@@ -427,33 +413,35 @@ pub fn fork_agent_with_transport(
             return Err(LifecycleError::Provider(error.to_string()));
         }
     };
-    if let Err(error) = finalize_fork_state(ForkFinalizeInput {
-        workspace: &workspace,
-        team_key: &fork_team,
-        source_agent_id,
-        agent_id: as_agent_id,
-        spec_agent: new_agent,
-        safety: &safety,
-        plan: &plan,
-        profile_launch: &profile_launch,
-        spawn: &spawn,
-        profile_dir: &profile_dir,
-        dynamic_role_file: materialized_role.path(),
-        context_proof: &context_proof,
-        spawned_at: &spawned_at,
-        spawn_epoch,
-    }) {
-        rollback_fork_after_spawn(
-            &workspace,
-            transport,
-            &session_name,
-            &window,
-            &mcp_config_path,
-            as_agent_id,
-            &profile_launch,
-            &fork_team,
-        );
-        return Err(error);
+    if let Some(context_proof) = context_proof.as_ref() {
+        if let Err(error) = finalize_fork_state(ForkFinalizeInput {
+            workspace: &workspace,
+            team_key: &fork_team,
+            source_agent_id,
+            agent_id: as_agent_id,
+            spec_agent: new_agent,
+            safety: &safety,
+            plan: &plan,
+            profile_launch: &profile_launch,
+            spawn: &spawn,
+            profile_dir: &profile_dir,
+            dynamic_role_file: materialized_role.path(),
+            context_proof: &context_proof,
+            spawned_at: &spawned_at,
+            spawn_epoch,
+        }) {
+            rollback_fork_after_spawn(
+                &workspace,
+                transport,
+                &session_name,
+                &window,
+                &mcp_config_path,
+                as_agent_id,
+                &profile_launch,
+                &fork_team,
+            );
+            return Err(error);
+        }
     }
     if let Err(error) =
         verify_fork_registration(&workspace, &fork_team, as_agent_id, &spawn, &window)
@@ -487,6 +475,11 @@ pub fn fork_agent_with_transport(
     if let Some(materialized) = copilot_fork.as_mut() {
         materialized.keep();
     }
+    let backing_state = if context_proof.is_some() {
+        ForkBackingState::Verified
+    } else {
+        ForkBackingState::PendingContextFork
+    };
     Ok(ForkAgentReport {
         source_agent_id: source_agent_id.clone(),
         new_agent_id: as_agent_id.clone(),
@@ -495,6 +488,7 @@ pub fn fork_agent_with_transport(
             state_file: crate::state::persist::runtime_state_path(&workspace),
             coordinator_started,
         },
-        session_id: Some(context_proof.new_session_id),
+        session_id: context_proof.map(|proof| proof.new_session_id),
+        backing_state,
     })
 }

package/crates/team-agent/src/lifecycle/launch/fork_finalize.rs

@@ -172,6 +172,110 @@ pub(super) fn finalize_fork_state(input: ForkFinalizeInput<'_>) -> Result<(), Li
         .map_err(|error| LifecycleError::StatePersist(error.to_string()))
 }
 
+pub(super) struct ForkPendingFinalizeInput<'a> {
+    pub workspace: &'a Path,
+    pub team_key: &'a str,
+    pub source_agent_id: &'a AgentId,
+    pub agent_id: &'a AgentId,
+    pub spec_agent: &'a Value,
+    pub safety: &'a DangerousApproval,
+    pub plan: &'a crate::provider::CommandPlan,
+    pub profile_launch: &'a crate::provider::ProviderProfileLaunch,
+    pub spawn: &'a crate::transport::SpawnResult,
+    pub profile_dir: &'a Path,
+    pub dynamic_role_file: &'a Path,
+    pub pending: &'a crate::provider::session::PendingContextFork,
+    pub spawn_epoch: u64,
+}
+
+pub(super) fn finalize_pending_fork_state(
+    input: ForkPendingFinalizeInput<'_>,
+) -> Result<(), LifecycleError> {
+    let _lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
+        workspace: input.workspace,
+        operation: "fork-agent-pending",
+        team: Some(input.team_key),
+        agent_id: Some(input.agent_id),
+    })?;
+    let mut next_state = crate::state::selector::resolve_active_team(
+        input.workspace,
+        Some(input.team_key),
+        crate::state::selector::SelectorMode::RequireSpec,
+    )
+    .map_err(|error| LifecycleError::TeamSelect(error.to_string()))?
+    .state;
+    upsert_pending_forked_agent_state(
+        &mut next_state,
+        input.source_agent_id,
+        input.agent_id,
+        input.spec_agent,
+        input.safety,
+        input.plan,
+        input.profile_launch,
+        input.spawn,
+        Some(input.profile_dir),
+        input.dynamic_role_file,
+        input.pending,
+        input.spawn_epoch,
+    )?;
+    maybe_fail_fork_after_spawn("save_runtime_state")?;
+    crate::state::repository::StateRepository::new(input.workspace)
+        .save(
+            crate::state::repository::StateWriteIntent::ForkAgent {
+                team_key: input.team_key,
+                agent_id: input.agent_id.as_str(),
+            },
+            &next_state,
+        )
+        .map_err(|error| LifecycleError::StatePersist(error.to_string()))
+}
+
+pub(crate) fn finalize_pending_fork_capture(
+    agent: &mut serde_json::Map<String, serde_json::Value>,
+    captured: &crate::provider::CapturedSession,
+) -> bool {
+    let Some(session_id) = captured.session_id.as_ref() else {
+        return false;
+    };
+    let Some(rollout_path) = captured.rollout_path.as_ref() else {
+        return false;
+    };
+    if agent
+        .get("fork_source_session_id")
+        .and_then(serde_json::Value::as_str)
+        == Some(session_id.as_str())
+    {
+        return false;
+    }
+    agent.insert(
+        "session_id".to_string(),
+        serde_json::json!(session_id.as_str()),
+    );
+    agent.insert(
+        "rollout_path".to_string(),
+        serde_json::json!(rollout_path.as_path().to_string_lossy()),
+    );
+    agent.insert(
+        "captured_at".to_string(),
+        serde_json::json!(chrono::Utc::now().to_rfc3339()),
+    );
+    agent.insert(
+        "captured_via".to_string(),
+        serde_json::to_value(captured.captured_via).unwrap_or(serde_json::Value::Null),
+    );
+    agent.insert(
+        "attribution_confidence".to_string(),
+        serde_json::to_value(captured.attribution_confidence).unwrap_or(serde_json::Value::Null),
+    );
+    agent.remove("_pending_session_id");
+    agent.remove("attribution_ambiguous");
+    agent.remove("fork_source_session_id");
+    agent.remove("pending_target_agent");
+    agent.remove("pending_grace_secs");
+    agent.insert("capture_state".to_string(), serde_json::json!("captured"));
+    true
+}
+
 pub(super) fn verify_fork_registration(
     workspace: &Path,
     team_key: &str,

package/crates/team-agent/src/lifecycle/launch/fork_pending.rs

@@ -0,0 +1,109 @@
+use super::*;
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn upsert_pending_forked_agent_state(
+    state: &mut serde_json::Value,
+    source_agent_id: &AgentId,
+    as_agent_id: &AgentId,
+    spec_agent: &Value,
+    safety: &DangerousApproval,
+    plan: &crate::provider::CommandPlan,
+    profile_launch: &crate::provider::ProviderProfileLaunch,
+    spawn: &crate::transport::SpawnResult,
+    profile_dir: Option<&Path>,
+    dynamic_role_file: &Path,
+    pending: &crate::provider::session::PendingContextFork,
+    spawn_epoch: u64,
+) -> Result<(), LifecycleError> {
+    let root = state.as_object_mut().ok_or_else(|| {
+        LifecycleError::StatePersist("runtime state root is not an object".to_string())
+    })?;
+    let agents = root
+        .entry("agents".to_string())
+        .or_insert_with(|| serde_json::json!({}))
+        .as_object_mut()
+        .ok_or_else(|| {
+            LifecycleError::StatePersist("runtime state agents is not an object".to_string())
+        })?;
+    let mut entry = serde_json::Map::new();
+    entry.insert("status".to_string(), serde_json::json!("running"));
+    entry.insert(
+        "capture_state".to_string(),
+        serde_json::json!("pending_context_fork"),
+    );
+    entry.insert(
+        "agent_id".to_string(),
+        serde_json::json!(as_agent_id.as_str()),
+    );
+    entry.insert(
+        "window".to_string(),
+        serde_json::json!(as_agent_id.as_str()),
+    );
+    entry.insert(
+        "forked_from".to_string(),
+        serde_json::json!(source_agent_id.as_str()),
+    );
+    entry.insert(
+        "fork_source_session_id".to_string(),
+        serde_json::json!(pending.source_session_id.as_str()),
+    );
+    entry.insert(
+        "pending_target_agent".to_string(),
+        serde_json::json!(pending.target_agent),
+    );
+    entry.insert(
+        "dynamic_role_file".to_string(),
+        serde_json::json!(dynamic_role_file.to_string_lossy().to_string()),
+    );
+    entry.insert(
+        "role_source_ownership".to_string(),
+        serde_json::json!("managed"),
+    );
+    entry.insert(
+        "spawn_cwd".to_string(),
+        serde_json::json!(pending
+            .scanner_context
+            .spawn_cwd
+            .to_string_lossy()
+            .to_string()),
+    );
+    entry.insert(
+        "pane_id".to_string(),
+        serde_json::json!(spawn.pane_id.as_str()),
+    );
+    entry.insert(
+        "spawned_at".to_string(),
+        serde_json::json!(pending.spawned_at),
+    );
+    entry.insert("spawn_epoch".to_string(), serde_json::json!(spawn_epoch));
+    if let Some(pid) = spawn.child_pid {
+        entry.insert("pane_pid".to_string(), serde_json::json!(pid));
+    }
+    for key in [
+        "provider",
+        "auth_mode",
+        "model",
+        "profile",
+        "role",
+        "effort",
+    ] {
+        if let Some(value) = spec_agent.get(key) {
+            entry.insert(key.to_string(), yaml_value_to_json(value));
+        }
+    }
+    if spec_agent.get("profile").is_some() {
+        if let Some(profile_dir) = profile_dir {
+            entry.insert(
+                "_profile_dir".to_string(),
+                serde_json::json!(profile_dir.to_string_lossy().to_string()),
+            );
+        }
+    }
+    persist_command_plan_state(&mut entry, plan, profile_launch);
+    persist_effective_approval_policy(&mut entry, safety);
+    agents.insert(
+        as_agent_id.as_str().to_string(),
+        serde_json::Value::Object(entry),
+    );
+    Ok(())
+}

package/crates/team-agent/src/lifecycle/launch/fork_state.rs

@@ -14,6 +14,10 @@ use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest}
 
 use super::*;
 
+#[path = "fork_pending.rs"]
+mod fork_pending;
+pub(super) use fork_pending::upsert_pending_forked_agent_state;
+
 pub(super) fn reserve_forked_agent_state(
     state: &mut serde_json::Value,
     source_agent_id: &AgentId,
@@ -134,6 +138,51 @@ pub(super) fn find_spec_agent<'a>(spec: &'a Value, agent_id: &AgentId) -> Option
     })
 }
 
+pub(super) fn fork_spec_agent<'a>(spec: &'a Value, agent_id: &AgentId) -> Option<&'a Value> {
+    find_spec_agent(spec, agent_id)
+}
+
+pub(super) fn fork_source_tuple(
+    state: &serde_json::Value,
+    source_agent_id: &AgentId,
+) -> Result<(crate::provider::SessionId, PathBuf), LifecycleError> {
+    let source = state
+        .get("agents")
+        .and_then(|agents| agents.get(source_agent_id.as_str()))
+        .ok_or_else(|| {
+            LifecycleError::Provider(format!("unknown worker agent id: {source_agent_id}"))
+        })?;
+    let field = |name: &str| {
+        source
+            .get(name)
+            .and_then(serde_json::Value::as_str)
+            .filter(|value| !value.is_empty())
+    };
+    let (Some(session_id), Some(backing)) = (field("session_id"), field("rollout_path")) else {
+        return Err(LifecycleError::Provider(format!(
+            "cannot fork {source_agent_id}: source session backing is missing or incomplete \
+             (session_id+rollout_path+captured_at+captured_via required)"
+        )));
+    };
+    if field("captured_at").is_none() || field("captured_via").is_none() {
+        return Err(LifecycleError::Provider(format!(
+            "cannot fork {source_agent_id}: source session backing is missing or incomplete \
+             (session_id+rollout_path+captured_at+captured_via required)"
+        )));
+    }
+    let backing = PathBuf::from(backing);
+    if !backing.is_file() {
+        return Err(LifecycleError::Provider(format!(
+            "cannot fork {source_agent_id}: source session backing is not readable: {}",
+            backing.display()
+        )));
+    }
+    Ok((
+        crate::provider::SessionId::new(session_id.to_string()),
+        backing,
+    ))
+}
+
 pub(super) fn append_forked_agent(
     spec: &Value,
     source_agent: &Value,

package/crates/team-agent/src/lifecycle/launch.rs

@@ -295,6 +295,7 @@ mod fork_state;
 pub(super) use fork_state::*;
 
 mod fork_finalize;
+pub(crate) use fork_finalize::finalize_pending_fork_capture;
 pub(super) use fork_finalize::*;
 
 mod role_source;

package/crates/team-agent/src/lifecycle/types.rs

@@ -664,6 +664,14 @@ pub struct ForkAgentReport {
     pub new_agent_id: AgentId,
     pub env: AgentActionEnvelope,
     pub session_id: Option<SessionId>,
+    pub backing_state: ForkBackingState,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ForkBackingState {
+    Verified,
+    PendingContextFork,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]

package/crates/team-agent/src/mcp_server/lifecycle_tools/agent_ops.rs

@@ -130,6 +130,7 @@ pub(crate) fn fork_agent(
             "state_file": report.env.state_file.to_string_lossy().to_string(),
             "coordinator_started": report.env.coordinator_started,
             "session_id": report.session_id.as_ref().map(|session| session.as_str()),
+            "backing_state": report.backing_state,
         })),
     })
 }

package/crates/team-agent/src/provider/session/capture.rs

@@ -469,13 +469,25 @@ fn classify_pending_capture_state(
     const TRIGGER_GRACE_SECS: i64 = 15;
     let past_spawn_grace = elapsed_since_spawn >= SPAWN_GRACE_SECS;
     let past_trigger_grace = has_trigger && elapsed_since_trigger >= TRIGGER_GRACE_SECS;
+    let fork_pending_expired = agent_obj.get("capture_state").and_then(Value::as_str)
+        == Some("pending_context_fork")
+        && crate::provider::session::transition_pending_context_fork(
+            has_trigger,
+            past_spawn_grace && past_trigger_grace,
+        )
+        .is_some();
     // transcript_missing requires BOTH: a trigger occurred AND we've
     // waited past the spawn grace (so we're not blamed for slow startup).
     // candidate_count == 0 is the "no backing" signal; non-zero
     // candidates that didn't satisfy assignment go through the ambiguous
     // path above and don't reach here.
-    if has_trigger && past_spawn_grace && past_trigger_grace && candidate_count == 0 {
+    if (fork_pending_expired || has_trigger && past_spawn_grace && past_trigger_grace)
+        && candidate_count == 0
+    {
         "transcript_missing"
+    } else if agent_obj.get("capture_state").and_then(Value::as_str) == Some("pending_context_fork")
+    {
+        "pending_context_fork"
     } else {
         "pending_first_turn"
     }
@@ -1143,6 +1155,9 @@ fn apply_captured_session(
     agent_obj: &mut serde_json::Map<String, Value>,
     captured: &CapturedSession,
 ) -> bool {
+    if agent_obj.get("capture_state").and_then(Value::as_str) == Some("pending_context_fork") {
+        return crate::lifecycle::finalize_pending_fork_capture(agent_obj, captured);
+    }
     let Some(session_id) = captured.session_id.as_ref() else {
         return false;
     };
@@ -1984,6 +1999,27 @@ mod u1_tests {
         );
     }
 
+    #[test]
+    fn pending_context_fork_keeps_typed_state_until_trigger_grace_expires() {
+        let old = (chrono::Utc::now() - chrono::Duration::seconds(60)).to_rfc3339();
+        let mut agent = serde_json::Map::new();
+        agent.insert("spawned_at".to_string(), serde_json::json!(old));
+        agent.insert(
+            "capture_state".to_string(),
+            serde_json::json!("pending_context_fork"),
+        );
+        assert_eq!(
+            super::classify_pending_capture_state(&agent, 0),
+            "pending_context_fork"
+        );
+        let trigger = (chrono::Utc::now() - chrono::Duration::seconds(20)).to_rfc3339();
+        agent.insert("first_send_at".to_string(), serde_json::json!(trigger));
+        assert_eq!(
+            super::classify_pending_capture_state(&agent, 0),
+            "transcript_missing"
+        );
+    }
+
     #[test]
     fn canonical_pending_capture_preserves_legacy_missing_boundary() {
         let agent = serde_json::json!({

package/crates/team-agent/src/provider/session/context_fork/claude.rs

@@ -0,0 +1,85 @@
+use super::*;
+
+pub(super) fn verify_claude_fork(
+    provider: Provider,
+    source_session_id: &SessionId,
+    plan: &CommandPlan,
+    before: &ContextBackingSnapshot,
+    expected_backing_path: Option<&Path>,
+    spawn_cwd: &Path,
+    deadline: Duration,
+) -> Result<ContextForkProof, ContextForkTermination> {
+    let expected = plan.expected_session_id.as_ref().ok_or_else(|| {
+        ProviderError::CaptureFailed(
+            "context_fork_unverified: Claude plan has no expected session id".to_string(),
+        )
+    })?;
+    let path = expected_backing_path.ok_or_else(|| {
+        ProviderError::CaptureFailed(
+            "context_fork_unverified: Claude plan has no exact snapshot backing".to_string(),
+        )
+    })?;
+    let expected_name = format!("{}.jsonl", expected.as_str());
+    if path.file_name().and_then(|name| name.to_str()) != Some(expected_name.as_str()) {
+        return Err(ProviderError::CaptureFailed(format!(
+            "context_fork_unverified: Claude snapshot backing does not match expected session {}",
+            expected.as_str()
+        ))
+        .into());
+    }
+    let started = std::time::Instant::now();
+    loop {
+        if let Some(stamp) = file_stamp(path) {
+            let changed = before.files.get(path).is_none_or(|old| *old != stamp);
+            let observed_matches =
+                session_id_from_jsonl(path).is_none_or(|observed| observed == expected.as_str());
+            if changed && readable_jsonl(path) && observed_matches && expected != source_session_id
+            {
+                return Ok(ContextForkProof {
+                    provider,
+                    source_session_id: source_session_id.clone(),
+                    new_session_id: expected.clone(),
+                    backing_path: path.to_path_buf(),
+                    captured_via: "context_fork_verified".to_string(),
+                    attribution_confidence: "high".to_string(),
+                    managed_backing_root: None,
+                });
+            }
+        }
+        if let Some(provider_path) = std::env::var_os("HOME")
+            .map(PathBuf::from)
+            .and_then(|home| {
+                crate::provider::session_scan::claude::projects_dir_for_cwd(&home, spawn_cwd)
+            })
+            .map(|root| root.join(&expected_name))
+        {
+            let observed_matches = session_id_from_jsonl(&provider_path)
+                .is_some_and(|observed| observed == expected.as_str());
+            let changed = file_stamp(&provider_path)
+                .is_some_and(|stamp| before.files.get(&provider_path) != Some(&stamp));
+            if changed
+                && readable_jsonl(&provider_path)
+                && observed_matches
+                && expected != source_session_id
+            {
+                return Ok(ContextForkProof {
+                    provider,
+                    source_session_id: source_session_id.clone(),
+                    new_session_id: expected.clone(),
+                    backing_path: provider_path,
+                    captured_via: "context_fork_verified".to_string(),
+                    attribution_confidence: "high".to_string(),
+                    managed_backing_root: None,
+                });
+            }
+        }
+        if started.elapsed() >= deadline {
+            break;
+        }
+        std::thread::sleep(Duration::from_millis(50));
+    }
+    Err(ContextForkTermination::Timeout {
+        provider,
+        deadline_ms: deadline.as_millis(),
+    })
+}

package/crates/team-agent/src/provider/session/context_fork/codex.rs

@@ -0,0 +1,65 @@
+use super::*;
+
+pub(super) fn verify_codex_fork(
+    source_session_id: &SessionId,
+    plan: &CommandPlan,
+    before: &ContextBackingSnapshot,
+    agent_id: &str,
+    spawn_cwd: &Path,
+    spawned_at: &str,
+    deadline: Duration,
+) -> Result<ContextForkProof, ContextForkTermination> {
+    let context = crate::provider::session_scan::CaptureSessionContext {
+        agent_id: agent_id.to_string(),
+        spawn_cwd: spawn_cwd.to_path_buf(),
+        pane_id: None,
+        pane_pid: None,
+        spawned_at: Some(spawned_at.to_string()),
+        expected_session_id: plan.expected_session_id.clone(),
+        provider_projects_root: plan.provider_projects_root.clone(),
+    };
+    let excluded = outcome::source_exclusions(before, source_session_id);
+    let started = std::time::Instant::now();
+    loop {
+        let current = jsonl_files(&before.root);
+        for candidate in
+            crate::provider::session_scan::scan_session_candidates_once(Provider::Codex, &context)?
+        {
+            let Some(path) = candidate.captured.rollout_path.as_ref() else {
+                continue;
+            };
+            let Some(stamp) = current.get(path.as_path()) else {
+                continue;
+            };
+            let snapshot_changed = before.files.get(path.as_path()) != Some(stamp);
+            if !snapshot_changed {
+                continue;
+            }
+            let Some(new_session_id) = candidate.captured.session_id else {
+                continue;
+            };
+            if excluded.contains(new_session_id.as_str())
+                || excluded.contains(&path.as_path().to_string_lossy().to_string())
+            {
+                continue;
+            }
+            return Ok(ContextForkProof {
+                provider: Provider::Codex,
+                source_session_id: source_session_id.clone(),
+                new_session_id,
+                backing_path: path.as_path().to_path_buf(),
+                captured_via: "context_fork_verified".to_string(),
+                attribution_confidence: "high".to_string(),
+                managed_backing_root: None,
+            });
+        }
+        if started.elapsed() >= deadline {
+            break;
+        }
+        std::thread::sleep(Duration::from_millis(50));
+    }
+    Err(ContextForkTermination::Timeout {
+        provider: Provider::Codex,
+        deadline_ms: deadline.as_millis(),
+    })
+}

package/crates/team-agent/src/provider/session/context_fork/outcome.rs

@@ -0,0 +1,138 @@
+use super::*;
+use std::collections::BTreeSet;
+
+pub(super) fn source_exclusions(
+    before: &ContextBackingSnapshot,
+    source_session_id: &SessionId,
+) -> BTreeSet<String> {
+    let mut excluded = BTreeSet::from([source_session_id.as_str().to_string()]);
+    for path in before.files.keys() {
+        if session_id_from_jsonl(path).as_deref() == Some(source_session_id.as_str()) {
+            excluded.insert(path.to_string_lossy().to_string());
+        }
+    }
+    excluded
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct PendingContextFork {
+    pub source_session_id: SessionId,
+    pub target_agent: String,
+    pub spawned_at: String,
+    pub scanner_context: crate::provider::session_scan::CaptureSessionContext,
+}
+
+#[derive(Debug)]
+pub(crate) enum ContextForkOutcome {
+    Verified(ContextForkProof),
+    Pending(PendingContextFork),
+    Rejected(ProviderError),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum ContextForkPendingFailure {
+    TranscriptMissing,
+}
+
+pub(crate) fn transition_pending_context_fork(
+    triggered: bool,
+    grace_expired: bool,
+) -> Option<ContextForkPendingFailure> {
+    (triggered && grace_expired).then_some(ContextForkPendingFailure::TranscriptMissing)
+}
+
+pub(crate) fn observe_context_fork(
+    provider: Provider,
+    source_session_id: &SessionId,
+    plan: &CommandPlan,
+    before: &ContextBackingSnapshot,
+    expected_backing_path: Option<&Path>,
+    agent_id: &str,
+    spawn_cwd: &Path,
+    spawned_at: &str,
+    deadline: Duration,
+) -> ContextForkOutcome {
+    match verify_context_fork(
+        provider,
+        source_session_id,
+        plan,
+        before,
+        expected_backing_path,
+        agent_id,
+        spawn_cwd,
+        spawned_at,
+        deadline,
+    ) {
+        Ok(proof) => ContextForkOutcome::Verified(proof),
+        Err(ContextForkTermination::Timeout { .. }) => {
+            ContextForkOutcome::Pending(PendingContextFork {
+                source_session_id: source_session_id.clone(),
+                target_agent: agent_id.to_string(),
+                spawned_at: spawned_at.to_string(),
+                scanner_context: crate::provider::session_scan::CaptureSessionContext {
+                    agent_id: agent_id.to_string(),
+                    spawn_cwd: spawn_cwd.to_path_buf(),
+                    pane_id: None,
+                    pane_pid: None,
+                    spawned_at: Some(spawned_at.to_string()),
+                    expected_session_id: plan.expected_session_id.clone(),
+                    provider_projects_root: plan.provider_projects_root.clone(),
+                },
+            })
+        }
+        Err(ContextForkTermination::Rejected(error)) => ContextForkOutcome::Rejected(error),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn convergence_deadlines_are_provider_specific() {
+        assert_eq!(
+            context_fork_convergence_deadline(Provider::Claude),
+            Duration::from_secs(45)
+        );
+        assert_eq!(
+            context_fork_convergence_deadline(Provider::Codex),
+            Duration::from_secs(10)
+        );
+        assert_eq!(
+            context_fork_convergence_deadline(Provider::Copilot),
+            Duration::from_secs(5)
+        );
+    }
+
+    #[test]
+    fn codex_without_new_backing_is_typed_pending() {
+        let root =
+            std::env::temp_dir().join(format!("ta-codex-fork-pending-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&root);
+        std::fs::create_dir_all(&root).unwrap();
+        let plan = CommandPlan {
+            argv: Vec::new(),
+            expected_session_id: None,
+            provider_projects_root: Some(root.clone()),
+            managed_mcp_config: false,
+        };
+        let before = ContextBackingSnapshot::capture(Provider::Codex, &plan);
+        let outcome = observe_context_fork(
+            Provider::Codex,
+            &SessionId::new("source-session"),
+            &plan,
+            &before,
+            None,
+            "fork",
+            &root,
+            "2026-07-24T00:00:00Z",
+            Duration::ZERO,
+        );
+        let ContextForkOutcome::Pending(pending) = outcome else {
+            panic!("missing backing must remain a typed pending fork")
+        };
+        assert_eq!(pending.source_session_id.as_str(), "source-session");
+        assert_eq!(pending.target_agent, "fork");
+        let _ = std::fs::remove_dir_all(&root);
+    }
+}

package/crates/team-agent/src/provider/session/context_fork.rs

@@ -5,7 +5,28 @@ use std::time::{Duration, SystemTime};
 use crate::model::enums::Provider;
 use crate::provider::{CommandPlan, ProviderError, SessionId};
 
+#[derive(Debug, thiserror::Error)]
+pub(crate) enum ContextForkTermination {
+    #[error(
+        "context_fork_unverified: {provider:?} produced no readable NEW session backing within {deadline_ms}ms"
+    )]
+    Timeout {
+        provider: Provider,
+        deadline_ms: u128,
+    },
+    #[error(transparent)]
+    Rejected(#[from] ProviderError),
+}
+
+mod claude;
+mod codex;
+mod outcome;
+pub(crate) use outcome::{
+    observe_context_fork, transition_pending_context_fork, ContextForkOutcome, PendingContextFork,
+};
+
 pub(crate) fn context_fork_convergence_deadline(provider: Provider) -> Duration {
+    // Expiration is consumed by ContextForkOutcome::Pending(PendingContextFork).
     match provider {
         Provider::Claude | Provider::ClaudeCode => Duration::from_secs(45),
         Provider::Codex => Duration::from_secs(10),
@@ -54,12 +75,12 @@ pub(crate) fn verify_context_fork(
     spawn_cwd: &Path,
     spawned_at: &str,
     deadline: Duration,
-) -> Result<ContextForkProof, ProviderError> {
+) -> Result<ContextForkProof, ContextForkTermination> {
     if provider == Provider::Copilot {
-        return verify_copilot_fork(source_session_id, plan);
+        return verify_copilot_fork(source_session_id, plan).map_err(Into::into);
     }
     if provider == Provider::Codex {
-        return verify_codex_fork(
+        return codex::verify_codex_fork(
             source_session_id,
             plan,
             before,
@@ -70,132 +91,20 @@ pub(crate) fn verify_context_fork(
         );
     }
     if matches!(provider, Provider::Claude | Provider::ClaudeCode) {
-        return verify_claude_fork(
+        return claude::verify_claude_fork(
             provider,
             source_session_id,
             plan,
             before,
             expected_backing_path,
+            spawn_cwd,
             deadline,
         );
     }
     Err(ProviderError::CaptureFailed(format!(
         "context_fork_unverified: {provider:?} has no verifiable fork backing"
-    )))
-}
-fn verify_claude_fork(
-    provider: Provider,
-    source_session_id: &SessionId,
-    plan: &CommandPlan,
-    before: &ContextBackingSnapshot,
-    expected_backing_path: Option<&Path>,
-    deadline: Duration,
-) -> Result<ContextForkProof, ProviderError> {
-    let expected = plan.expected_session_id.as_ref().ok_or_else(|| {
-        ProviderError::CaptureFailed(
-            "context_fork_unverified: Claude plan has no expected session id".to_string(),
-        )
-    })?;
-    let path = expected_backing_path.ok_or_else(|| {
-        ProviderError::CaptureFailed(
-            "context_fork_unverified: Claude plan has no exact snapshot backing".to_string(),
-        )
-    })?;
-    let expected_name = format!("{}.jsonl", expected.as_str());
-    if path.file_name().and_then(|name| name.to_str()) != Some(expected_name.as_str()) {
-        return Err(ProviderError::CaptureFailed(format!(
-            "context_fork_unverified: Claude snapshot backing does not match expected session {}",
-            expected.as_str()
-        )));
-    }
-    let started = std::time::Instant::now();
-    loop {
-        if let Some(stamp) = file_stamp(path) {
-            let changed = before.files.get(path).is_none_or(|old| *old != stamp);
-            let observed_matches =
-                session_id_from_jsonl(path).is_none_or(|observed| observed == expected.as_str());
-            if changed && readable_jsonl(path) && observed_matches && expected != source_session_id
-            {
-                return Ok(ContextForkProof {
-                    provider,
-                    source_session_id: source_session_id.clone(),
-                    new_session_id: expected.clone(),
-                    backing_path: path.to_path_buf(),
-                    captured_via: "context_fork_verified".to_string(),
-                    attribution_confidence: "high".to_string(),
-                    managed_backing_root: None,
-                });
-            }
-        }
-        if started.elapsed() >= deadline {
-            break;
-        }
-        std::thread::sleep(Duration::from_millis(50));
-    }
-    Err(ProviderError::CaptureFailed(format!(
-        "context_fork_unverified: {provider:?} produced no readable NEW session backing within {}ms",
-        deadline.as_millis()
-    )))
-}
-
-fn verify_codex_fork(
-    source_session_id: &SessionId,
-    plan: &CommandPlan,
-    before: &ContextBackingSnapshot,
-    agent_id: &str,
-    spawn_cwd: &Path,
-    spawned_at: &str,
-    deadline: Duration,
-) -> Result<ContextForkProof, ProviderError> {
-    let context = crate::provider::session_scan::CaptureSessionContext {
-        agent_id: agent_id.to_string(),
-        spawn_cwd: spawn_cwd.to_path_buf(),
-        pane_id: None,
-        pane_pid: None,
-        spawned_at: Some(spawned_at.to_string()),
-        expected_session_id: plan.expected_session_id.clone(),
-        provider_projects_root: plan.provider_projects_root.clone(),
-    };
-    let started = std::time::Instant::now();
-    loop {
-        let current = jsonl_files(&before.root);
-        for candidate in
-            crate::provider::session_scan::scan_session_candidates_once(Provider::Codex, &context)?
-        {
-            let Some(path) = candidate.captured.rollout_path.as_ref() else {
-                continue;
-            };
-            let Some(stamp) = current.get(path.as_path()) else {
-                continue;
-            };
-            if before.files.get(path.as_path()) == Some(stamp) {
-                continue;
-            }
-            let Some(new_session_id) = candidate.captured.session_id else {
-                continue;
-            };
-            if new_session_id == *source_session_id {
-                continue;
-            }
-            return Ok(ContextForkProof {
-                provider: Provider::Codex,
-                source_session_id: source_session_id.clone(),
-                new_session_id,
-                backing_path: path.as_path().to_path_buf(),
-                captured_via: "context_fork_verified".to_string(),
-                attribution_confidence: "high".to_string(),
-                managed_backing_root: None,
-            });
-        }
-        if started.elapsed() >= deadline {
-            break;
-        }
-        std::thread::sleep(Duration::from_millis(50));
-    }
-    Err(ProviderError::CaptureFailed(format!(
-        "context_fork_unverified: Codex produced no readable NEW session backing within {}ms",
-        deadline.as_millis()
-    )))
+    ))
+    .into())
 }
 
 fn verify_copilot_fork(
@@ -242,6 +151,8 @@ fn verify_copilot_fork(
             "context_fork_unverified: copilot NEW session is absent from session-store".to_string(),
         ));
     }
+    // Copilot's isolated database row is its synchronous fork proof; the
+    // pre-spawn materialization baseline is never accepted by transcript scan.
     Ok(ContextForkProof {
         provider: Provider::Copilot,
         source_session_id: source_session_id.clone(),
@@ -335,22 +246,6 @@ mod tests {
     use super::*;
     use std::io::Write;
 
-    #[test]
-    fn context_fork_deadlines_are_provider_specific() {
-        assert_eq!(
-            context_fork_convergence_deadline(Provider::Claude),
-            Duration::from_secs(45)
-        );
-        assert_eq!(
-            context_fork_convergence_deadline(Provider::Codex),
-            Duration::from_secs(10)
-        );
-        assert_eq!(
-            context_fork_convergence_deadline(Provider::Copilot),
-            Duration::from_secs(5)
-        );
-    }
-
     #[test]
     fn codex_fork_proof_ignores_changed_stale_and_foreign_rollouts() {
         let root =

package/crates/team-agent/src/provider/session/mod.rs

@@ -10,7 +10,8 @@ pub mod resume;
 
 pub use context_fork::ContextForkProof;
 pub(crate) use context_fork::{
-    context_fork_convergence_deadline, verify_context_fork, ContextBackingSnapshot,
+    context_fork_convergence_deadline, observe_context_fork, transition_pending_context_fork,
+    ContextBackingSnapshot, ContextForkOutcome, PendingContextFork,
 };
 
 pub use resume::{

package/crates/team-agent/src/provider/session_scan/claude.rs

@@ -5,7 +5,7 @@ use crate::provider::Provider;
 
 use super::{CaptureSessionContext, CapturedSessionCandidate};
 
-pub(super) fn projects_dir_for_cwd(home: &Path, spawn_cwd: &Path) -> Option<PathBuf> {
+pub(crate) fn projects_dir_for_cwd(home: &Path, spawn_cwd: &Path) -> Option<PathBuf> {
     let canonical = std::fs::canonicalize(spawn_cwd).unwrap_or_else(|_| spawn_cwd.to_path_buf());
     let encoded = encode_projects_dir(&canonical.to_string_lossy());
     if encoded.is_empty() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.57",
+  "version": "0.5.58",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,9 +20,9 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "optionalDependencies": {
-    "@team-agent/cli-darwin-arm64": "0.5.57",
-    "@team-agent/cli-darwin-x64": "0.5.57",
-    "@team-agent/cli-linux-x64": "0.5.57"
+    "@team-agent/cli-darwin-arm64": "0.5.58",
+    "@team-agent/cli-darwin-x64": "0.5.58",
+    "@team-agent/cli-linux-x64": "0.5.58"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",