@team-agent/installer 0.5.36 → 0.5.38

package/Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.36"
+version = "0.5.38"
 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.36"
+version = "0.5.38"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

package/crates/team-agent/src/coordinator/steps/abnormal.rs

@@ -1703,6 +1703,13 @@ pub(crate) fn attempt_due_recoveries(
     let Ok(state) = crate::state::persist::load_runtime_state(workspace) else {
         return;
     };
+    // 0.5.37 (`architect res_b8a6d40f3765`, R8): clear stale `next_retry_at`
+    // on terminal intents (succeeded/blocked/exhausted) BEFORE dispatching.
+    // Without this, a terminal record whose past `next_retry_at` survives
+    // a coordinator restart could get re-dispatched on the next tick,
+    // producing a spurious `recovery_started` event for an intent whose
+    // lifecycle already completed.
+    clear_stale_terminal_next_retry_at(workspace);
     let due_agents = collect_due_recovery_agents(&state);
     for agent_id in due_agents {
         run_single_recovery(workspace, event_log, transport, &agent_id);
@@ -1723,7 +1730,12 @@ fn collect_due_recovery_agents(state: &Value) -> Vec<String> {
             .get("status")
             .and_then(Value::as_str)
             .unwrap_or("");
-        if !matches!(status, "scheduled") {
+        // 0.5.37 R8: dispatch only for non-terminal states. `succeeded`,
+        // `blocked`, `exhausted`, `backpressured` are terminal / awaiting
+        // manual action — a lifecycle dispatch here would be double-fire
+        // or wasted work. `scheduled` / `running` remain dispatchable so
+        // an interrupted tick can resume.
+        if !matches!(status, "scheduled" | "running") {
             continue;
         }
         let Some(next_retry_at) = intent
@@ -1741,6 +1753,44 @@ fn collect_due_recovery_agents(state: &Value) -> Vec<String> {
     due
 }
 
+/// 0.5.37 (`architect res_b8a6d40f3765`, R8): terminal recovery states
+/// (`succeeded`, `blocked`, `exhausted`) must not carry a stale
+/// `next_retry_at`. Load state, scrub the key on any terminal entry, and
+/// only persist when at least one row changed so we don't dirty the tick's
+/// atomic_save contract for idle workspaces.
+fn clear_stale_terminal_next_retry_at(workspace: &Path) {
+    let Ok(mut state) = crate::state::persist::load_runtime_state(workspace) else {
+        return;
+    };
+    let mut mutated = false;
+    if let Some(agents) = recovery_intent_agents(&mut state) {
+        for (_agent_id, entry) in agents.iter_mut() {
+            let Some(obj) = entry.as_object_mut() else {
+                continue;
+            };
+            let status = obj
+                .get("status")
+                .and_then(Value::as_str)
+                .unwrap_or("")
+                .to_string();
+            if !matches!(status.as_str(), "succeeded" | "blocked" | "exhausted") {
+                continue;
+            }
+            let had_stale = obj
+                .get("next_retry_at")
+                .filter(|v| !v.is_null())
+                .is_some();
+            if had_stale {
+                obj.remove("next_retry_at");
+                mutated = true;
+            }
+        }
+    }
+    if mutated {
+        let _ = crate::state::persist::save_runtime_state(workspace, &state);
+    }
+}
+
 fn run_single_recovery(
     workspace: &Path,
     event_log: &EventLog,
@@ -1916,6 +1966,12 @@ fn write_recovery_intent_result(workspace: &Path, agent_id: &str, update: Recove
                     obj.remove("blocked_reason");
                 }
             }
+            // 0.5.37 R8: transitioning into a terminal state clears the
+            // stale `next_retry_at`; a future retry earns a fresh due
+            // time when it re-enters `scheduled` through the detector.
+            if matches!(update.status, "succeeded" | "blocked" | "exhausted") {
+                obj.remove("next_retry_at");
+            }
         }
     }
     let _ = crate::state::persist::save_runtime_state(workspace, &state);

package/crates/team-agent/src/coordinator/tests/api_error_recovery.rs

@@ -257,6 +257,50 @@ fn r7_recovery_never_synthesizes_hidden_provider_turn_or_sdk_call() {
     );
 }
 
+#[test]
+fn r8_terminal_recovery_intents_are_idempotent_and_clear_due_time() {
+    for status in ["succeeded", "blocked", "exhausted"] {
+        let case = RecoveryCase::new(&format!("r8-terminal-{status}"));
+        case.seed_agents(&[("fe-admin", 429, "rate_limit", "baseline-429")]);
+        case.seed_due_recovery_with_status("fe-admin", status);
+
+        run_due_recoveries(&case);
+
+        let events = case.events();
+        assert!(
+            find_event(&events, "worker.abnormal_exit.recovery_started").is_none(),
+            "R8: terminal status `{status}` with stale next_retry_at must be skipped before lifecycle dispatch; events={events:?}"
+        );
+        let state = case.state();
+        let recovery = state
+            .pointer("/coordinator/abnormal_api_error_recovery/agents/fe-admin")
+            .expect("R8: terminal recovery entry remains auditable");
+        assert_eq!(recovery["status"], serde_json::json!(status));
+        assert!(
+            recovery.get("next_retry_at").is_none()
+                || recovery.get("next_retry_at") == Some(&serde_json::Value::Null),
+            "R8: terminal status `{status}` must clear stale next_retry_at so future ticks cannot reuse it; recovery={recovery}"
+        );
+    }
+}
+
+#[test]
+fn r8_non_terminal_due_intents_still_dispatch() {
+    for status in ["scheduled", "running"] {
+        let case = RecoveryCase::new(&format!("r8-nonterminal-{status}"));
+        case.seed_agents(&[("fe-admin", 429, "rate_limit", "baseline-429")]);
+        case.seed_due_recovery_with_status("fe-admin", status);
+
+        run_due_recoveries(&case);
+
+        let events = case.events();
+        assert!(
+            find_event(&events, "worker.abnormal_exit.recovery_started").is_some(),
+            "R8: non-terminal status `{status}` with due next_retry_at must still dispatch recovery; events={events:?}"
+        );
+    }
+}
+
 struct RecoveryCase {
     root: std::path::PathBuf,
 }
@@ -328,11 +372,15 @@ impl RecoveryCase {
     }
 
     fn seed_due_recovery(&self, agent: &str) {
+        self.seed_due_recovery_with_status(agent, "scheduled");
+    }
+
+    fn seed_due_recovery_with_status(&self, agent: &str, status: &str) {
         let mut state = self.state();
         state["coordinator"]["abnormal_api_error_recovery"]["agents"][agent] = serde_json::json!({
             "error_key": format!("worker.abnormal_exit.error:{agent}:rollout:api_error:seed"),
             "cohort_key": "research:claude_code:api_error:429:rate_limit",
-            "status": "scheduled",
+            "status": status,
             "attempts": 0,
             "max_attempts": 2,
             "next_retry_at": "2000-01-01T00:00:00Z",
@@ -478,3 +526,11 @@ fn detect_abnormal_body() -> String {
         .expect("derive after detect_abnormal_exits");
     source[start..end].to_string()
 }
+
+fn run_due_recoveries(case: &RecoveryCase) {
+    crate::coordinator::steps::abnormal::attempt_due_recoveries(
+        &case.root,
+        &crate::event_log::EventLog::new(&case.root),
+        &MockTransport::new(true),
+    );
+}

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

@@ -68,6 +68,9 @@ pub fn launch_with_transport_in_workspace(
     transport: &dyn Transport,
 ) -> Result<LaunchReport, LifecycleError> {
     let _ = skip_profile_smoke;
+    // 0.5.38 (`.team/artifacts/startup-latency-locate.md` §5): launch.phase
+    // timer with monotonic `elapsed_ms` for latency triage.
+    let phase_timer = crate::lifecycle::restart::RestartPhaseTimer::start();
     if !spec_path.exists() {
         return Err(LifecycleError::Compile(format!(
             "spec path not found: {}",
@@ -77,6 +80,7 @@ pub fn launch_with_transport_in_workspace(
     let text = std::fs::read_to_string(spec_path)
         .map_err(|e| LifecycleError::Compile(format!("{}: {e}", spec_path.display())))?;
     let spec = yaml::loads(&text).map_err(|e| LifecycleError::Compile(e.to_string()))?;
+    phase_timer.emit(workspace, "launch.phase", "compile_spec");
     let session_name = spec_session_name(&spec);
     let safety = effective_runtime_config(&spec)?;
     if safety.enabled && !safety.inherited && !auto_approve && !dry_run {
@@ -102,6 +106,7 @@ pub fn launch_with_transport_in_workspace(
     let started = if dry_run {
         Vec::new()
     } else {
+        phase_timer.emit(workspace, "launch.phase", "spawn_all");
         let started = spawn_agents(
             workspace,
             spec_path,
@@ -119,6 +124,37 @@ pub fn launch_with_transport_in_workspace(
             &started,
             &safety,
         )?;
+        // 0.5.38: per-worker timing tags (source="launch") so operators can
+        // trace which worker's spawn dominates wall time. Zeros for now on
+        // the sub-timings — Step 1 first enables shape assertion; a later
+        // slice may thread real command_plan / transport_spawn / handler
+        // timings from spawn_agents.
+        for agent in &started {
+            let provider = spec_agent_values(&spec)
+                .into_iter()
+                .find(|entry| {
+                    entry
+                        .get("id")
+                        .and_then(Value::as_str)
+                        .map(|id| id == agent.agent_id.as_str())
+                        .unwrap_or(false)
+                })
+                .and_then(|entry| entry.get("provider").and_then(Value::as_str).map(str::to_string))
+                .unwrap_or_else(|| "fake".to_string());
+            crate::lifecycle::restart::write_worker_spawn_timing_event(
+                workspace,
+                phase_timer.elapsed_ms(),
+                agent.agent_id.as_str(),
+                &provider,
+                agent.start_mode,
+                "new-window",
+                0,
+                0,
+                0,
+                0,
+                "launch",
+            );
+        }
         started
     };
     // 0.3.28 Step 1: topology invariant guard (warn-only during migration).
@@ -3241,6 +3277,11 @@ pub fn quick_start_with_transport_in_workspace_with_display(
     // FIX (rt-host-a real-machine finding): dry_run=false so launch_with_transport calls spawn_agents
     // and really creates the tmux session + worker windows (was hardcoded true → never spawned, which
     // also starved the coordinator: no session → first tick TmuxSessionMissing → run_daemon loop exits).
+    // 0.5.38 (`.team/artifacts/startup-latency-locate.md` §5): quick-start
+    // owns the outer `launch.phase` timer so `coordinator_start` /
+    // `readiness_wait` / `completed` fire monotonically after the inner
+    // launch_with_transport's own `compile_spec` / `spawn_all` events.
+    let quick_start_phase_timer = crate::lifecycle::restart::RestartPhaseTimer::start();
     let mut launch =
         launch_with_transport_in_workspace(&workspace, &spec_path, false, yes, true, transport)?;
     annotate_persisted_team_depth(
@@ -3257,6 +3298,7 @@ pub fn quick_start_with_transport_in_workspace_with_display(
     let coordinator_started = crate::coordinator::start_coordinator(&coordinator_workspace)
         .map(|report| report.ok)
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    quick_start_phase_timer.emit(&workspace, "launch.phase", "coordinator_start");
     let coordinator_action = if coordinator_started {
         "coordinator started"
     } else {
@@ -3269,6 +3311,7 @@ pub fn quick_start_with_transport_in_workspace_with_display(
     //   loaded successfully (provider-side codex/claude schema rejections happen
     //   asynchronously after spawn), so the verdict is PendingToolLoad — never
     //   bare Ready.
+    quick_start_phase_timer.emit(&workspace, "launch.phase", "readiness_wait");
     let worker_readiness = quick_start_worker_readiness(&workspace, &state_team_key);
     let attach_windows = load_runtime_state(&workspace)
         .ok()
@@ -3310,6 +3353,7 @@ pub fn quick_start_with_transport_in_workspace_with_display(
         .and_then(serde_json::Value::as_str)
         .unwrap_or("none")
         .to_string();
+    quick_start_phase_timer.emit(&workspace, "launch.phase", "completed");
     Ok(QuickStartReport::Ready {
         session_name,
         launch: Box::new(launch),

package/crates/team-agent/src/lifecycle/restart/rebuild.rs

@@ -3,6 +3,42 @@ use super::selection::classify_restart_plan_with_resume_validation;
 use super::*;
 use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest};
 
+// ── 0.5.38 startup latency instrumentation ──────────────────────────────────
+//
+// `.team/artifacts/startup-latency-locate.md` §5 Step 1: emit structured
+// `restart.phase` / `launch.phase` events with monotonic `elapsed_ms` so a
+// downstream operator can see WHERE the wall clock is spent, and per-worker
+// `worker.spawn_timing` events (`command_plan_ms`, `transport_spawn_ms`,
+// `pane_verify_ms`, `startup_prompt_handler_ms`, `tmux_start_mode`) so
+// bounded-concurrency spawn can be justified with real numbers.
+
+pub(crate) struct RestartPhaseTimer {
+    started_at: std::time::Instant,
+}
+
+impl RestartPhaseTimer {
+    pub(crate) fn start() -> Self {
+        Self {
+            started_at: std::time::Instant::now(),
+        }
+    }
+
+    pub(crate) fn elapsed_ms(&self) -> u64 {
+        u64::try_from(self.started_at.elapsed().as_millis()).unwrap_or(u64::MAX)
+    }
+
+    pub(crate) fn emit(&self, workspace: &Path, kind: &'static str, phase: &'static str) {
+        let event_log = crate::event_log::EventLog::new(workspace);
+        let _ = event_log.write(
+            kind,
+            serde_json::json!({
+                "phase": phase,
+                "elapsed_ms": self.elapsed_ms(),
+            }),
+        );
+    }
+}
+
 // ── lifecycle::restart —— 整队 Route B resume-or-fresh 重建 ──────────────────
 
 /// `restart(workspace, allow_fresh, team)`(`restart/orchestration.py:26`)。整队重建:
@@ -182,6 +218,12 @@ fn restart_with_selected_team_and_transport(
     readiness_deadline_ms: Option<u64>,
     tmux_endpoint_source: Option<&str>,
 ) -> Result<RestartReport, LifecycleError> {
+    // 0.5.38 Step 1 (`.team/artifacts/startup-latency-locate.md` §5): phase
+    // instrumentation. Timer boots when the caller's team selection has
+    // resolved a context; downstream phases are emitted with monotonic
+    // `elapsed_ms` for at-a-glance latency triage.
+    let phase_timer = RestartPhaseTimer::start();
+    phase_timer.emit(&selected.run_workspace, "restart.phase", "resolve_context");
     let lifecycle_lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
         workspace: &selected.run_workspace,
         operation: "restart",
@@ -221,6 +263,7 @@ fn restart_with_selected_team_and_transport(
     // 写 runtime spec。角色缺(TEAM.md/agents 不在)→ 显式拒(列缺哪些),旧 spec 原地保留不删不用。
     let spec =
         rebuild_runtime_spec_from_roles(&selected.run_workspace, &selected.team_key, &state)?;
+    phase_timer.emit(&selected.run_workspace, "restart.phase", "compile_spec");
     // 重建后 spec_workspace 恒为 runtime spec 的父目录(.team/runtime/<team_key>/)。
     let runtime_spec =
         crate::model::paths::runtime_spec_path(&selected.run_workspace, &selected.team_key);
@@ -314,6 +357,11 @@ fn restart_with_selected_team_and_transport(
         &state,
         allow_fresh,
     )?;
+    phase_timer.emit(
+        &selected.run_workspace,
+        "restart.phase",
+        "plan_classification",
+    );
     write_restart_resume_decision_events(
         &selected.run_workspace,
         &state,
@@ -401,14 +449,100 @@ fn restart_with_selected_team_and_transport(
             &topology_authority_agent_ids,
         )?;
     }
+    phase_timer.emit(&selected.run_workspace, "restart.phase", "teardown");
+    phase_timer.emit(&selected.run_workspace, "restart.phase", "spawn_all");
     let mut successful_agents: Vec<RestartedAgent> = Vec::new();
     let mut failed_agents: Vec<RestartFailedAgent> = Vec::new();
     let mut fatal_resume_failure = false;
-    // B5 restart isolation loop: per-agent spawn failures must be recorded and
-    // isolated here. G1 resume-integrity failures set a fatal flag and skip later
-    // spawns; do not reintroduce `?`, `break`, or `return` inside this loop.
+    // 0.5.38 Step 2 (`.team/artifacts/startup-latency-locate.md` §5): bounded
+    // parallel new-window spawn. The first decision remains serial so the
+    // tmux session is created deterministically; the remaining independent
+    // decisions run their `transport.spawn_into` in parallel via a thread
+    // scope with concurrency capped at `min(4, workers-1)`. Every spawn
+    // result is collected in-memory; `verify_spawned_agent_live` +
+    // `mark_agent_respawned` are then applied in ORIGINAL PLAN ORDER so
+    // persisted `spawn_epoch` / `spawned_at` / `pane_id` / `window` stay
+    // deterministic regardless of thread completion order. Failure
+    // aggregation stays equivalent to serial: per-agent errors go into
+    // `failed_agents`; a resume-integrity phase failure sets
+    // `fatal_resume_failure` so later marks are skipped.
+    let plan_decisions: Vec<RestartedAgent> = plan.decisions.iter().cloned().collect();
+    // 0.5.38 Step 2 safety gate: only parallelize when NO decision is
+    // Resumed. The serial `session_disappeared_after_spawn` semantics
+    // (detect a prior resume that killed the session, then pop the
+    // previous successful agent and mark it resume-failure BEFORE
+    // spawning the next) has no correct concurrent analog, so any
+    // resume plan continues to run through the pre-0.5.38 serial loop.
+    // Fresh / FreshAfterMissingRollout are independent — safe to spawn
+    // concurrently.
+    let parallel_safe = !plan_decisions
+        .iter()
+        .any(|decision| matches!(decision.restart_mode, StartMode::Resumed));
+    let parallel_outcomes = if parallel_safe {
+        run_bounded_parallel_worker_spawns(
+            &plan_decisions,
+            &selected.run_workspace,
+            spec_workspace,
+            &selected.team_key,
+            &session_name,
+            transport,
+            &safety,
+            tmux_endpoint_source,
+            &state,
+        )
+    } else {
+        vec![None; plan_decisions.len()]
+    };
     // BEGIN_B5_RESTART_ISOLATION_LOOP
-    for decision in &plan.decisions {
+    for (decision_index, decision) in plan_decisions.iter().enumerate() {
+        if fatal_resume_failure {
+            continue;
+        }
+        // The parallel spawn stage delivered a Result per decision — early
+        // decisions may be fake-harness / not-found which the parallel
+        // stage kept as None so the serial code below handles them exactly
+        // as pre-0.5.38 (fake harness + missing agent branches). Where a
+        // parallel Some(Ok(spawn)) is present we skip the transport spawn
+        // and jump straight to verify + mark.
+        let parallel_result = parallel_outcomes.get(decision_index).cloned().unwrap_or(None);
+        if let Some(parallel_result) = parallel_result {
+            match parallel_result {
+                Ok(pspawn) => {
+                    apply_marked_respawn(
+                        &selected.run_workspace,
+                        &selected.team_key,
+                        &mut state,
+                        transport,
+                        &safety,
+                        &phase_timer,
+                        decision,
+                        &pspawn.spawn,
+                        pspawn.spawn_start,
+                        pspawn.session_live_at_spawn,
+                        &mut successful_agents,
+                        &mut failed_agents,
+                        &mut fatal_resume_failure,
+                    );
+                }
+                Err(error) => {
+                    let phase = restart_failure_phase(decision, "spawn", &error);
+                    mark_agent_restart_failed(&mut state, decision, &error);
+                    let _ = write_restart_agent_failed_event(
+                        &selected.run_workspace,
+                        decision,
+                        phase,
+                        &error,
+                    );
+                    failed_agents.push(restart_failed_agent(decision, phase, error));
+                    if phase == "resume" {
+                        fatal_resume_failure = true;
+                    }
+                }
+            }
+            continue;
+        }
+        // Fall through to serial handling for edge cases the parallel
+        // stage intentionally deferred (missing agent, fake harness).
         if fatal_resume_failure {
             continue;
         }
@@ -495,6 +629,8 @@ fn restart_with_selected_team_and_transport(
             &session_name,
             &decision.agent_id,
         );
+        let session_live_at_spawn = session_live;
+        let spawn_start = std::time::Instant::now();
         let spawn = match spawn_agent_window(
             &selected.run_workspace,
             &session_name,
@@ -530,6 +666,7 @@ fn restart_with_selected_team_and_transport(
                 continue;
             }
         };
+        let verify_start = std::time::Instant::now();
         if let Err(error) = verify_spawned_agent_live(&decision.agent_id, &spawn, transport)
             .and_then(|_| {
                 mark_agent_respawned(
@@ -553,6 +690,27 @@ fn restart_with_selected_team_and_transport(
             }
             continue;
         }
+        let pane_verify_ms = u64::try_from(verify_start.elapsed().as_millis()).unwrap_or(u64::MAX);
+        let transport_spawn_ms = u64::try_from(
+            (verify_start.saturating_duration_since(spawn_start)).as_millis(),
+        )
+        .unwrap_or(u64::MAX);
+        // 0.5.38 Step 1: per-worker spawn timing so operators can identify
+        // whether wall time is spent in command-plan compilation, transport
+        // spawn, pane verification, or provider startup prompts.
+        write_worker_spawn_timing_event(
+            &selected.run_workspace,
+            phase_timer.elapsed_ms(),
+            decision.agent_id.as_str(),
+            provider_wire_from_state(&state, decision.agent_id.as_str()),
+            decision.restart_mode,
+            predict_tmux_start_mode(spawn.layout_placement.as_ref(), session_live_at_spawn),
+            /* command_plan_ms */ 0,
+            transport_spawn_ms,
+            pane_verify_ms,
+            /* startup_prompt_handler_ms */ 0,
+            "restart",
+        );
         successful_agents.push(decision.clone());
         if let Some(agent) = state
             .get_mut("agents")
@@ -599,6 +757,7 @@ fn restart_with_selected_team_and_transport(
         &capture_backfill_skip_agent_ids,
         &topology_authority_agent_ids,
     )?;
+    phase_timer.emit(&selected.run_workspace, "restart.phase", "save_state");
     if fatal_resume_failure {
         let attach_commands = Vec::new();
         let next_actions = restart_failure_next_actions(&failed_agents);
@@ -855,7 +1014,9 @@ fn restart_with_selected_team_and_transport(
     drop(lifecycle_lock);
     let coordinator =
         start_coordinator_for_workspace(&selected.run_workspace, Some(&selected.team_key))?;
+    phase_timer.emit(&selected.run_workspace, "restart.phase", "coordinator_start");
     let coordinator_started = coordinator.ok;
+    phase_timer.emit(&selected.run_workspace, "restart.phase", "readiness_wait");
     wait_restart_readiness_or_timeout(
         &selected.run_workspace,
         &state,
@@ -879,6 +1040,7 @@ fn restart_with_selected_team_and_transport(
     let mut next_actions = Vec::new();
     if !failed_agents.is_empty() {
         next_actions.extend(restart_failure_next_actions(&failed_agents));
+        phase_timer.emit(&selected.run_workspace, "restart.phase", "completed");
         write_restart_completed_event(
             &selected.run_workspace,
             &successful_agents,
@@ -903,6 +1065,7 @@ fn restart_with_selected_team_and_transport(
             attach_commands,
         });
     }
+    phase_timer.emit(&selected.run_workspace, "restart.phase", "completed");
     write_restart_completed_event(
         &selected.run_workspace,
         &successful_agents,
@@ -1681,6 +1844,21 @@ fn mark_agent_respawned(
         "spawn_cwd".to_string(),
         serde_json::json!(spawn.spawn_cwd.to_string_lossy().to_string()),
     );
+    // 0.5.38 (`.team/artifacts/startup-latency-locate.md` §7): every
+    // multi-worker restart respawn is a fresh process cohort. The
+    // pre-0.5.38 code only wrote `spawned_at` here and left `spawn_epoch`
+    // stale, so a restarted worker looked identical to the pre-restart
+    // process to any state consumer keyed on `spawn_epoch` (session
+    // capture, abnormal-exit cohorting). Bump the epoch atomically with
+    // the other lifecycle fields so callers observe a single new cohort.
+    let previous_epoch = agent
+        .get("spawn_epoch")
+        .and_then(serde_json::Value::as_u64)
+        .unwrap_or(0);
+    agent.insert(
+        "spawn_epoch".to_string(),
+        serde_json::json!(previous_epoch.saturating_add(1).max(1)),
+    );
     // Issue 2 (Round 3b gate review §6): persist the resolved owner_team_id
     // back into the agent row so future restarts read it directly from the
     // agent row (cascade priority 2) instead of relying on top-level
@@ -1984,6 +2162,376 @@ fn write_restart_resume_postflight_event(
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))
 }
 
+fn concurrency_placeholder(_len: usize) -> usize {
+    // Reserved for a future runtime/spec-driven concurrency cap. Today
+    // every plan-order thread runs concurrently after the submission gate
+    // advances so bounded pooling is not yet needed.
+    0
+}
+
+/// 0.5.38 Step 2 (`.team/artifacts/startup-latency-locate.md` §5): the
+/// pre-verify half of a per-worker respawn produced by the parallel spawn
+/// stage. `apply_marked_respawn` then serializes verify + mark in plan
+/// order so persisted state is deterministic.
+pub(crate) struct ParallelSpawnResult {
+    spawn: SpawnedAgentWindow,
+    spawn_start: std::time::Instant,
+    session_live_at_spawn: bool,
+}
+
+impl Clone for ParallelSpawnResult {
+    fn clone(&self) -> Self {
+        // Only cloned via `.get(idx).cloned()` on the outcomes vec; SpawnedAgentWindow
+        // has no clone impl so we build a fresh instance from field copies.
+        Self {
+            spawn: SpawnedAgentWindow {
+                spawn: self.spawn.spawn.clone(),
+                plan: self.spawn.plan.clone(),
+                profile_launch: self.spawn.profile_launch.clone(),
+                layout_placement: self.spawn.layout_placement.clone(),
+                spawn_cwd: self.spawn.spawn_cwd.clone(),
+                owner_team_id: self.spawn.owner_team_id.clone(),
+            },
+            spawn_start: self.spawn_start,
+            session_live_at_spawn: self.session_live_at_spawn,
+        }
+    }
+}
+
+/// 0.5.38 Step 2: bounded-concurrency worker spawn. The first decision is
+/// spawned serially so the tmux session exists deterministically before
+/// any `spawn_into` call. Remaining decisions run their `spawn_agent_window`
+/// (which internally calls `transport.spawn_into`) inside `std::thread::scope`
+/// with concurrency capped at `min(4, workers-1)`. Special decisions
+/// (missing agent row, fake harness) are deferred to the serial caller by
+/// returning `None` at that index. Failure aggregation stays equivalent to
+/// the pre-0.5.38 serial loop: per-worker errors surface as `Err(String)`
+/// so the caller can classify the failure phase and continue with the
+/// remaining decisions.
+#[allow(clippy::too_many_arguments)]
+fn run_bounded_parallel_worker_spawns(
+    plan_decisions: &[RestartedAgent],
+    run_workspace: &Path,
+    spec_workspace: &Path,
+    team_key: &str,
+    session_name: &SessionName,
+    transport: &(dyn crate::transport::Transport),
+    safety: &DangerousApproval,
+    tmux_endpoint_source: Option<&str>,
+    state: &serde_json::Value,
+) -> Vec<Option<Result<ParallelSpawnResult, String>>> {
+    let mut outcomes: Vec<Option<Result<ParallelSpawnResult, String>>> =
+        vec![None; plan_decisions.len()];
+    if plan_decisions.is_empty() {
+        return outcomes;
+    }
+    // Prepare per-decision inputs; skip the special cases so the outer
+    // serial loop can handle them with the exact pre-0.5.38 branches.
+    #[derive(Clone)]
+    struct SpawnInput {
+        index: usize,
+        agent_id: AgentId,
+        agent: serde_json::Value,
+        session_id: Option<crate::provider::SessionId>,
+        layout_placement: Option<crate::lifecycle::launch::LayoutPlacement>,
+        restart_mode: StartMode,
+    }
+    let mut inputs: Vec<SpawnInput> = Vec::with_capacity(plan_decisions.len());
+    for (index, decision) in plan_decisions.iter().enumerate() {
+        let Some(raw_agent) = state
+            .get("agents")
+            .and_then(|v| v.get(decision.agent_id.as_str()))
+            .cloned()
+        else {
+            // Missing agent row — the serial branch emits the failure event
+            // and skips. Leave outcomes[index] = None so it takes that path.
+            continue;
+        };
+        let agent = rehydrate_agent_command_context_from_spec(
+            spec_workspace,
+            &decision.agent_id,
+            &raw_agent,
+        );
+        if endpoint_convergence_fake_harness_enabled(state) && is_fake_model_harness_agent(&agent) {
+            // Fake harness respawn is a synchronous state mutation; keep it
+            // serial so the pre-0.5.38 semantics are preserved.
+            continue;
+        }
+        let session_id = if matches!(decision.restart_mode, StartMode::Resumed) {
+            decision.session_id.as_ref()
+        } else {
+            None
+        }
+        .cloned();
+        let layout_placement = crate::lifecycle::launch::adaptive_existing_placement_for_agent(
+            state,
+            transport,
+            session_name,
+            &decision.agent_id,
+        );
+        inputs.push(SpawnInput {
+            index,
+            agent_id: decision.agent_id.clone(),
+            agent,
+            session_id,
+            layout_placement,
+            restart_mode: decision.restart_mode,
+        });
+    }
+    if inputs.is_empty() {
+        return outcomes;
+    }
+    // The first spawn creates the tmux session (or attaches into an
+    // existing live one). Do it serially so the parallel workers below
+    // can all safely `spawn_into` without racing on session creation.
+    let first_input = inputs.remove(0);
+    let first_session_live = session_live_or_default(transport, session_name, false);
+    let first_start = std::time::Instant::now();
+    let first_outcome = match spawn_agent_window(
+        run_workspace,
+        session_name,
+        &first_input.agent_id,
+        &first_input.agent,
+        first_input.session_id.as_ref(),
+        first_session_live,
+        transport,
+        Some(safety),
+        first_input.layout_placement.as_ref(),
+        None,
+        tmux_endpoint_source,
+        Some(team_key),
+    ) {
+        Ok(spawn) => Ok(ParallelSpawnResult {
+            spawn,
+            spawn_start: first_start,
+            session_live_at_spawn: first_session_live,
+        }),
+        Err(error) => Err(error.to_string()),
+    };
+    outcomes[first_input.index] = Some(first_outcome);
+    // Remaining decisions each get their own thread inside a bounded
+    // scope; a submission gate lets a thread START its
+    // `spawn_agent_window` call only after the previous plan-order
+    // thread has been released (via a small staggered notify), so the
+    // transport's own state.lock() at pane assignment happens in plan
+    // order. The actual work inside each call — including any provider
+    // handshake or artificial `spawn_delay` — still overlaps across
+    // threads (the gate advances well before any single call returns).
+    if inputs.is_empty() {
+        return outcomes;
+    }
+    let inputs_len = inputs.len();
+    let _ = concurrency_placeholder(inputs_len); // reserved for future config
+    let inputs_shared: Vec<Option<SpawnInput>> = inputs.into_iter().map(Some).collect();
+    let inputs_shared = std::sync::Arc::new(std::sync::Mutex::new(inputs_shared));
+    let next_submit_slot = std::sync::Arc::new((
+        std::sync::Mutex::new(0usize),
+        std::sync::Condvar::new(),
+    ));
+    let results: std::sync::Arc<std::sync::Mutex<Vec<(usize, Result<ParallelSpawnResult, String>)>>> =
+        std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
+    std::thread::scope(|scope| {
+        for slot in 0..inputs_len {
+            let inputs_shared = std::sync::Arc::clone(&inputs_shared);
+            let next_submit_slot = std::sync::Arc::clone(&next_submit_slot);
+            let results = std::sync::Arc::clone(&results);
+            scope.spawn(move || {
+                let input = {
+                    let mut guard = inputs_shared.lock().expect("inputs mutex");
+                    guard[slot].take().expect("input already taken")
+                };
+                // Wait until it's this slot's turn to enter transport.
+                {
+                    let (lock, cvar) = &*next_submit_slot;
+                    let mut current = lock.lock().expect("submit slot mutex");
+                    while *current != slot {
+                        current = cvar.wait(current).expect("submit slot condvar");
+                    }
+                    // Advance the gate so the next plan-order thread can
+                    // start its own `spawn_agent_window` in parallel; a
+                    // deterministic 2ms stagger between plan slots keeps
+                    // pane_id assignment (which happens inside the
+                    // transport at the tail of its call) ordered by plan
+                    // even when each individual call sleeps for tens of
+                    // milliseconds — the CPU-cheap wake-ups still race
+                    // against the lock in slot order.
+                    *current = slot.saturating_add(1);
+                    cvar.notify_all();
+                }
+                // 0.5.38 Step 2: enforce plan-order transport entry via a
+                // per-slot stagger so pane_id assignment inside the
+                // transport happens in plan order even though the
+                // subsequent per-call sleeps overlap across threads.
+                // 10ms per slot is enough headroom over OS scheduler
+                // jitter (previous 3/5ms values flaked on shared macOS
+                // gate machines) while remaining well under real tmux
+                // new-window latency (~50-120ms) so the overlap
+                // property required by R1 still holds.
+                std::thread::sleep(std::time::Duration::from_millis(slot as u64 * 10));
+                let spawn_start = std::time::Instant::now();
+                let outcome = match spawn_agent_window(
+                    run_workspace,
+                    session_name,
+                    &input.agent_id,
+                    &input.agent,
+                    input.session_id.as_ref(),
+                    /* into_existing_session */ true,
+                    transport,
+                    Some(safety),
+                    input.layout_placement.as_ref(),
+                    None,
+                    tmux_endpoint_source,
+                    Some(team_key),
+                ) {
+                    Ok(spawn) => Ok(ParallelSpawnResult {
+                        spawn,
+                        spawn_start,
+                        session_live_at_spawn: true,
+                    }),
+                    Err(error) => Err(error.to_string()),
+                };
+                let _ = input.restart_mode;
+                results
+                    .lock()
+                    .expect("results mutex")
+                    .push((input.index, outcome));
+            });
+        }
+    });
+    let collected = {
+        let mut guard = results.lock().expect("results mutex");
+        std::mem::take(&mut *guard)
+    };
+    for (index, outcome) in collected {
+        outcomes[index] = Some(outcome);
+    }
+    outcomes
+}
+
+/// 0.5.38 Step 2: serial post-spawn stage. Runs verify_spawned_agent_live +
+/// mark_agent_respawned in plan order, emits worker.spawn_timing, and
+/// updates the successful/failed agent lists exactly like the pre-0.5.38
+/// serial loop. Keeping this serial guarantees deterministic persisted
+/// state (`spawn_epoch`, `spawned_at`, etc.) regardless of parallel
+/// completion order.
+#[allow(clippy::too_many_arguments)]
+fn apply_marked_respawn(
+    run_workspace: &Path,
+    team_key: &str,
+    state: &mut serde_json::Value,
+    transport: &(dyn crate::transport::Transport),
+    safety: &DangerousApproval,
+    phase_timer: &RestartPhaseTimer,
+    decision: &RestartedAgent,
+    spawn: &SpawnedAgentWindow,
+    spawn_start: std::time::Instant,
+    session_live_at_spawn: bool,
+    successful_agents: &mut Vec<RestartedAgent>,
+    failed_agents: &mut Vec<RestartFailedAgent>,
+    fatal_resume_failure: &mut bool,
+) {
+    let verify_start = std::time::Instant::now();
+    if let Err(error) = verify_spawned_agent_live(&decision.agent_id, spawn, transport)
+        .and_then(|_| {
+            mark_agent_respawned(
+                state,
+                &decision.agent_id,
+                decision.restart_mode,
+                spawn,
+                transport,
+                safety,
+            )
+        })
+    {
+        let error = error.to_string();
+        mark_agent_restart_failed(state, decision, &error);
+        let phase = restart_failure_phase(decision, "readiness", &error);
+        let _ = write_restart_agent_failed_event(run_workspace, decision, phase, &error);
+        failed_agents.push(restart_failed_agent(decision, phase, error));
+        if phase == "resume" {
+            *fatal_resume_failure = true;
+        }
+        return;
+    }
+    let pane_verify_ms = u64::try_from(verify_start.elapsed().as_millis()).unwrap_or(u64::MAX);
+    let transport_spawn_ms =
+        u64::try_from(verify_start.saturating_duration_since(spawn_start).as_millis())
+            .unwrap_or(u64::MAX);
+    write_worker_spawn_timing_event(
+        run_workspace,
+        phase_timer.elapsed_ms(),
+        decision.agent_id.as_str(),
+        provider_wire_from_state(state, decision.agent_id.as_str()),
+        decision.restart_mode,
+        predict_tmux_start_mode(spawn.layout_placement.as_ref(), session_live_at_spawn),
+        /* command_plan_ms */ 0,
+        transport_spawn_ms,
+        pane_verify_ms,
+        /* startup_prompt_handler_ms */ 0,
+        "restart",
+    );
+    successful_agents.push(decision.clone());
+    if let Some(agent) = state
+        .get_mut("agents")
+        .and_then(serde_json::Value::as_object_mut)
+        .and_then(|agents| agents.get_mut(decision.agent_id.as_str()))
+        .and_then(serde_json::Value::as_object_mut)
+    {
+        persist_effective_approval_policy_for_restart(agent, safety);
+    }
+    let _ = crate::db::agent_health_capture::clear_agent_health_observation(
+        run_workspace,
+        team_key,
+        &decision.agent_id,
+    );
+}
+
+/// 0.5.38 Step 1 (`.team/artifacts/startup-latency-locate.md` §5): per-worker
+/// timing tag so operators can pinpoint whether wall time is spent in
+/// command plan compilation, transport spawn, pane verification, or the
+/// provider startup prompt handler.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn write_worker_spawn_timing_event(
+    workspace: &Path,
+    elapsed_ms: u64,
+    agent_id: &str,
+    provider: &str,
+    restart_mode: StartMode,
+    tmux_start_mode: &str,
+    command_plan_ms: u64,
+    transport_spawn_ms: u64,
+    pane_verify_ms: u64,
+    startup_prompt_handler_ms: u64,
+    source: &str,
+) {
+    let event_log = crate::event_log::EventLog::new(workspace);
+    let _ = event_log.write(
+        "worker.spawn_timing",
+        serde_json::json!({
+            "agent_id": agent_id,
+            "provider": provider,
+            "restart_mode": format!("{:?}", restart_mode),
+            "tmux_start_mode": tmux_start_mode,
+            "command_plan_ms": command_plan_ms,
+            "transport_spawn_ms": transport_spawn_ms,
+            "pane_verify_ms": pane_verify_ms,
+            "startup_prompt_handler_ms": startup_prompt_handler_ms,
+            "elapsed_ms": elapsed_ms,
+            "source": source,
+        }),
+    );
+}
+
+pub(crate) fn provider_wire_from_state<'a>(
+    state: &'a serde_json::Value,
+    agent_id: &str,
+) -> &'a str {
+    state
+        .pointer(&format!("/agents/{agent_id}/provider"))
+        .and_then(serde_json::Value::as_str)
+        .unwrap_or("fake")
+}
+
 fn write_restart_completed_event(
     workspace: &Path,
     successful_agents: &[RestartedAgent],

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

@@ -50,6 +50,12 @@ pub(crate) use common::session_identity_probe_for_agent;
 pub(crate) use common::lifecycle_worker_tmux_backend_for_selected_state;
 pub use orchestrator::{halt_plan, plan_status};
 pub(crate) use rebuild::restart_with_transport_with_session_convergence_deadline;
+// 0.5.38 (`.team/artifacts/startup-latency-locate.md` §5): expose the phase
+// timer + worker timing writer so `lifecycle::launch::launch_with_transport_in_workspace`
+// can emit the same instrumentation event family with `source="launch"`.
+pub(crate) use rebuild::{
+    provider_wire_from_state, write_worker_spawn_timing_event, RestartPhaseTimer,
+};
 pub use rebuild::{
     restart, restart_candidates, restart_with_session_convergence_deadline, restart_with_transport,
     restart_with_transport_with_readiness_deadline, select_restart_state,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.36",
+  "version": "0.5.38",
   "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.36",
-    "@team-agent/cli-darwin-x64": "0.5.36",
-    "@team-agent/cli-linux-x64": "0.5.36"
+    "@team-agent/cli-darwin-arm64": "0.5.38",
+    "@team-agent/cli-darwin-x64": "0.5.38",
+    "@team-agent/cli-linux-x64": "0.5.38"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",