@team-agent/installer 0.3.9 → 0.3.10

package/Cargo.lock

@@ -566,7 +566,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.3.9"
+version = "0.3.10"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent"]
 
 [workspace.package]
 edition = "2021"
-version = "0.3.9"
+version = "0.3.10"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

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

@@ -258,4 +258,10 @@ fn spine_tick_session_missing_emits_event() {
             .any(|e| e.get("event").and_then(|v| v.as_str()) == Some("coordinator.session_missing")),
         "the tmux-missing gate must emit a coordinator.session_missing event before the stop report; got {events:?}"
     );
+    assert!(
+        events
+            .iter()
+            .any(|e| e.get("event").and_then(|v| v.as_str()) == Some("coordinator.session_missing_alert")),
+        "the tmux-missing gate must emit an explicit leader-visible alert before stopping; got {events:?}"
+    );
 }

package/crates/team-agent/src/coordinator/tick.rs

@@ -198,6 +198,7 @@ impl Coordinator {
                     "coordinator.session_missing",
                     serde_json::json!({"session": session_name}),
                 )?;
+                notify_session_missing(self.workspace.as_path(), &state, &event_log, session_name)?;
                 return Ok(empty_tick_report(
                     false,
                     true,
@@ -971,7 +972,8 @@ impl Coordinator {
                         "runtime_approval.auto_approved",
                         serde_json::json!({
                             "agent_id": agent_id,
-                            "tool": prompt.tool,
+                            "server": prompt.server.as_deref(),
+                            "tool": prompt.tool.as_deref(),
                             "choice": choice,
                             "cleared": cleared,
                             "policy_source": approval_policy.source,
@@ -980,6 +982,23 @@ impl Coordinator {
                             "worker_capability_above_leader": approval_policy.worker_capability_above_leader,
                         }),
                     )?;
+                        event_log.write(
+                            "mcp.tool.auto_approved",
+                            serde_json::json!({
+                                "agent_id": agent_id,
+                                "server": prompt.server.as_deref(),
+                                "tool": prompt.tool.as_deref(),
+                                "choice": choice,
+                                "cleared": cleared,
+                                "inherit_reason": approval_policy.inherit_reason(),
+                                "bypass_source": approval_policy.source,
+                                "provider": approval_policy.provider,
+                                "flag": approval_policy.flag,
+                                "inherited": approval_policy.inherited,
+                                "explicit_yes_confirmed": approval_policy.explicit_yes_confirmed,
+                                "worker_capability_above_leader": approval_policy.worker_capability_above_leader,
+                            }),
+                        )?;
                     }
                     RuntimeApprovalDecision::AwaitingHumanConfirm => {
                         let Some(reason) = awaiting_human_confirm_reason(&prompt, auto_answer_allowed) else {
@@ -2110,6 +2129,8 @@ struct RuntimeApprovalPolicy {
     source: String,
     inherited: bool,
     explicit_yes_confirmed: bool,
+    provider: Option<String>,
+    flag: Option<String>,
     worker_capability_above_leader: bool,
 }
 
@@ -2127,6 +2148,14 @@ impl RuntimeApprovalPolicy {
             && (!self.worker_capability_above_leader
                 || (self.source == "runtime_config" && self.explicit_yes_confirmed))
     }
+
+    fn inherit_reason(&self) -> &'static str {
+        match self.source.as_str() {
+            "leader_process" if self.inherited => "leader_bypass",
+            "runtime_config" if self.explicit_yes_confirmed => "runtime_config_explicit_yes",
+            _ => "none",
+        }
+    }
 }
 
 fn runtime_approval_policy_from_agent(agent: &Value) -> RuntimeApprovalPolicy {
@@ -2151,6 +2180,14 @@ fn runtime_approval_policy_from_agent(agent: &Value) -> RuntimeApprovalPolicy {
             .and_then(|p| p.get("explicit_yes_confirmed"))
             .and_then(Value::as_bool)
             .unwrap_or(false),
+        provider: policy
+            .and_then(|p| p.get("provider"))
+            .and_then(Value::as_str)
+            .map(str::to_string),
+        flag: policy
+            .and_then(|p| p.get("flag"))
+            .and_then(Value::as_str)
+            .map(str::to_string),
         worker_capability_above_leader: policy
             .and_then(|p| p.get("worker_capability_above_leader"))
             .and_then(Value::as_bool)
@@ -2423,3 +2460,48 @@ fn remove_file_if_exists(path: &Path) -> Result<(), std::io::Error> {
         Err(e) => Err(e),
     }
 }
+
+fn notify_session_missing(
+    workspace: &Path,
+    state: &Value,
+    event_log: &EventLog,
+    session_name: &str,
+) -> Result<(), TickError> {
+    let content = format!(
+        "coordinator.session_missing\nerror: tmux session {session_name} is missing; coordinator is stopping\naction: restart the team or recover the missing tmux session\nlog: .team/logs/events.jsonl"
+    );
+    let dedupe_key = format!("coordinator.session_missing:{session_name}");
+    match crate::messaging::send_to_leader_receiver(
+        workspace,
+        state,
+        "leader",
+        &content,
+        None,
+        "coordinator",
+        false,
+        Some(&dedupe_key),
+        event_log,
+    ) {
+        Ok(outcome) => {
+            event_log.write(
+                "coordinator.session_missing_alert",
+                serde_json::json!({
+                    "session": session_name,
+                    "leader_notification_status": crate::messaging::helpers::status_wire(outcome.status),
+                    "message_id": outcome.message_id,
+                }),
+            )?;
+        }
+        Err(error) => {
+            event_log.write(
+                "coordinator.session_missing_alert_failed",
+                serde_json::json!({
+                    "session": session_name,
+                    "error": error.to_string(),
+                    "action": "inspect .team/logs/events.jsonl and restart the team",
+                }),
+            )?;
+        }
+    }
+    Ok(())
+}

package/crates/team-agent/src/leader/lease.rs

@@ -654,6 +654,8 @@ fn leader_command_provider(command: &str) -> Option<Provider> {
         Some(Provider::ClaudeCode)
     } else if lower.contains("codex") {
         Some(Provider::Codex)
+    } else if lower.contains("copilot") {
+        Some(Provider::Copilot)
     } else if lower.contains("fake") {
         Some(Provider::Fake)
     } else {
@@ -1082,3 +1084,20 @@ pub fn detect_dual_state_divergence(
         "team_owner_epoch": team_epoch,
     })))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn leader_command_provider_recognizes_copilot() {
+        assert_eq!(
+            leader_command_provider("copilot --allow-all-tools"),
+            Some(Provider::Copilot)
+        );
+        assert_eq!(
+            leader_command_provider("/usr/local/bin/copilot"),
+            Some(Provider::Copilot)
+        );
+    }
+}

package/crates/team-agent/src/leader/rediscover/tests.rs

@@ -80,6 +80,18 @@ fn event_named(events: &[Value], name: &str) -> Value {
         .unwrap_or_else(|| panic!("missing event {name}; got {events:?}"))
 }
 
+#[test]
+fn leader_command_provider_recognizes_copilot() {
+    assert_eq!(
+        leader_command_provider("copilot --allow-all-tools"),
+        Some(Provider::Copilot)
+    );
+    assert_eq!(
+        leader_command_provider("/usr/local/bin/copilot"),
+        Some(Provider::Copilot)
+    );
+}
+
 fn last_event_named(events: &[Value], name: &str) -> Value {
     events
         .iter()

package/crates/team-agent/src/leader/rediscover.rs

@@ -590,6 +590,8 @@ fn leader_command_provider(command: &str) -> Option<Provider> {
         Some(Provider::ClaudeCode)
     } else if lower.contains("codex") {
         Some(Provider::Codex)
+    } else if lower.contains("copilot") {
+        Some(Provider::Copilot)
     } else if lower.contains("fake") {
         Some(Provider::Fake)
     } else {

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

@@ -288,6 +288,7 @@ fn spawn_agents(
         let mut env =
             inherited_env_with_team_overrides(workspace, agent_id_raw, Some(&mcp_team_id));
         apply_profile_launch_env(&mut env, &profile_launch);
+        apply_mcp_auto_approval_env(&mut env, &safety);
         // Python providers.py:145 + launch/core.py:253 — fresh launch runs the worker
         // with cwd=workspace, same as the RS fork/add and restart paths.
         let env_unset: Vec<String> = profile_launch.env_unset.iter().cloned().collect();
@@ -1390,6 +1391,39 @@ pub(crate) fn inherited_env_with_team_overrides(
     env
 }
 
+pub(crate) fn apply_mcp_auto_approval_env(
+    env: &mut BTreeMap<String, String>,
+    safety: &DangerousApproval,
+) {
+    for key in [
+        "TEAM_AGENT_LEADER_BYPASS",
+        "TEAM_AGENT_LEADER_BYPASS_SOURCE",
+        "TEAM_AGENT_LEADER_BYPASS_PROVIDER",
+        "TEAM_AGENT_LEADER_BYPASS_FLAG",
+        "TEAM_AGENT_MCP_AUTO_APPROVE",
+        "TEAM_AGENT_MCP_AUTO_APPROVE_SOURCE",
+    ] {
+        env.remove(key);
+    }
+    if safety.enabled
+        && matches!(safety.source, DangerousApprovalSource::LeaderProcess)
+        && safety.inherited
+    {
+        env.insert("TEAM_AGENT_LEADER_BYPASS".to_string(), "1".to_string());
+        env.insert("TEAM_AGENT_LEADER_BYPASS_SOURCE".to_string(), "leader_process".to_string());
+        if let Some(provider) = safety.provider.as_deref() {
+            env.insert("TEAM_AGENT_LEADER_BYPASS_PROVIDER".to_string(), provider.to_string());
+        }
+        if let Some(flag) = safety.flag.as_deref() {
+            env.insert("TEAM_AGENT_LEADER_BYPASS_FLAG".to_string(), flag.to_string());
+        }
+        env.insert("TEAM_AGENT_MCP_AUTO_APPROVE".to_string(), "team_orchestrator".to_string());
+        env.insert("TEAM_AGENT_MCP_AUTO_APPROVE_SOURCE".to_string(), "leader_bypass".to_string());
+    } else {
+        env.insert("TEAM_AGENT_LEADER_BYPASS".to_string(), "0".to_string());
+    }
+}
+
 /// BUG / B2 灵魂件 + C-1-2 + C-6-1 cr verdict — Copilot per-worker AGENTS.md
 /// 写入 + `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` 注入。
 ///
@@ -2971,6 +3005,7 @@ pub fn fork_agent_with_transport(
     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);
+    apply_mcp_auto_approval_env(&mut env, &safety);
     // golden operations.py:336 -> _tmux_start_command_for_agent_window (runtime.py:1017-1020): branch on
     // _tmux_session_exists — an ABSENT session => new-session (spawn_first), present => new-window
     // (spawn_into). The Rust restart seam (restart.rs spawn_agent_window) uses the same branch.

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

@@ -108,17 +108,31 @@ pub(crate) fn start_agent_at_paths(
     let provider = agent_provider(&agent);
     let session_id = agent_session_id(&agent);
     let rollout_path = agent_rollout_path(&agent);
-    let rollout_exists = rollout_path
+    let resume_backing_exists = session_id
         .as_ref()
-        .map(|p| p.as_path().exists())
+        .map(|session| {
+            resume_backing_exists_for_agent(
+                workspace,
+                agent_id,
+                &agent,
+                provider,
+                session,
+                rollout_path.as_ref(),
+            )
+        })
         .unwrap_or(false);
     let start_mode = decide_start_mode(
         provider_wire(provider),
         session_id.as_ref(),
         rollout_path.as_ref(),
-        rollout_exists,
+        resume_backing_exists,
         allow_fresh,
     );
+    if matches!(start_mode, StartMode::Noop) {
+        return Err(LifecycleError::RequirementUnmet(format!(
+            "resume_not_ready: session backing store missing for agent {agent_id}; rerun with --allow-fresh to start fresh"
+        )));
+    }
     let spawn_session_id = if matches!(start_mode, StartMode::Resumed) {
         session_id.as_ref()
     } else {

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

@@ -122,6 +122,7 @@ pub(super) fn spawn_agent_window(
         team_id.as_deref(),
     );
     crate::lifecycle::launch::apply_profile_launch_env(&mut env, &profile_launch);
+    crate::lifecycle::launch::apply_mcp_auto_approval_env(&mut env, safety);
     let spawn_cwd = spawn_cwd_override
         .or_else(|| {
             agent
@@ -242,6 +243,80 @@ pub(super) fn agent_rollout_path(agent: &serde_json::Value) -> Option<RolloutPat
         .map(RolloutPath::new)
 }
 
+pub(super) fn resume_backing_exists_for_agent(
+    workspace: &Path,
+    agent_id: &AgentId,
+    agent: &serde_json::Value,
+    provider: Provider,
+    session_id: &SessionId,
+    rollout_path: Option<&RolloutPath>,
+) -> bool {
+    match provider {
+        Provider::Codex => rollout_path_exists(rollout_path),
+        Provider::Claude | Provider::ClaudeCode => {
+            rollout_path_exists(rollout_path)
+                || event_log_transcript_exists(workspace, agent_id.as_str(), session_id.as_str())
+        }
+        Provider::Copilot => copilot_session_store_has_session(session_id.as_str()),
+        Provider::GeminiCli | Provider::Fake => {
+            let _ = agent;
+            true
+        }
+    }
+}
+
+fn rollout_path_exists(rollout_path: Option<&RolloutPath>) -> bool {
+    rollout_path
+        .as_ref()
+        .is_some_and(|path| path.as_path().exists())
+}
+
+fn event_log_transcript_exists(workspace: &Path, agent_id: &str, session_id: &str) -> bool {
+    let Ok(events) = crate::event_log::EventLog::new(workspace).tail(0) else {
+        return false;
+    };
+    events.iter().rev().any(|event| {
+        event.get("event").and_then(serde_json::Value::as_str) == Some("session.captured")
+            && ["agent_id", "worker_id"]
+                .iter()
+                .any(|key| event.get(*key).and_then(serde_json::Value::as_str) == Some(agent_id))
+            && event.get("session_id").and_then(serde_json::Value::as_str) == Some(session_id)
+            && event_transcript_path(event).is_some_and(|path| path.exists())
+    })
+}
+
+fn event_transcript_path(event: &serde_json::Value) -> Option<PathBuf> {
+    event
+        .get("rollout_path")
+        .or_else(|| event.get("transcript_path"))
+        .and_then(serde_json::Value::as_str)
+        .filter(|path| !path.is_empty())
+        .map(PathBuf::from)
+}
+
+fn copilot_session_store_has_session(session_id: &str) -> bool {
+    let Some(home) = std::env::var_os("HOME").map(PathBuf::from) else {
+        return false;
+    };
+    let db_path = home.join(".copilot").join("session-store.db");
+    if !db_path.exists() {
+        return false;
+    }
+    let Ok(conn) = rusqlite::Connection::open_with_flags(
+        db_path,
+        rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY | rusqlite::OpenFlags::SQLITE_OPEN_NO_MUTEX,
+    ) else {
+        return false;
+    };
+    conn
+        .query_row(
+            "select 1 from sessions where id = ?1 limit 1",
+            [session_id],
+            |_| Ok(()),
+        )
+        .is_ok()
+}
+
 pub(crate) fn refresh_missing_provider_sessions(
     state: &mut serde_json::Value,
 ) -> Result<bool, LifecycleError> {

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

@@ -1,5 +1,5 @@
 use super::common::*;
-use super::selection::classify_restart_plan;
+use super::selection::classify_restart_plan_with_resume_validation;
 use super::*;
 
 // ── lifecycle::restart —— 整队 Route B resume-or-fresh 重建 ──────────────────
@@ -29,6 +29,7 @@ pub fn restart_with_session_convergence_deadline(
         team,
         &crate::tmux_backend::TmuxBackend::for_workspace(&run_ws),
         session_converge_deadline_ms,
+        None,
     )
 }
 
@@ -40,6 +41,16 @@ pub fn restart_with_transport(
     allow_fresh: bool,
     team: Option<&str>,
     transport: &dyn crate::transport::Transport,
+) -> Result<RestartReport, LifecycleError> {
+    restart_with_transport_with_readiness_deadline(workspace, allow_fresh, team, transport, None)
+}
+
+pub fn restart_with_transport_with_readiness_deadline(
+    workspace: &Path,
+    allow_fresh: bool,
+    team: Option<&str>,
+    transport: &dyn crate::transport::Transport,
+    readiness_deadline_ms: Option<u64>,
 ) -> Result<RestartReport, LifecycleError> {
     match restart_with_transport_with_session_convergence_deadline(
         workspace,
@@ -47,6 +58,7 @@ pub fn restart_with_transport(
         team,
         transport,
         None,
+        readiness_deadline_ms,
     )? {
         RestartReport::RefusedResumeNotReady {
             missing,
@@ -76,6 +88,7 @@ pub fn restart_with_transport_with_session_convergence_deadline(
     team: Option<&str>,
     transport: &dyn crate::transport::Transport,
     session_converge_deadline_ms: Option<u64>,
+    readiness_deadline_ms: Option<u64>,
 ) -> Result<RestartReport, LifecycleError> {
     // RED-2-STILL(P0):入口门必须在 canonical_run_workspace 解析后的路径上判,不用 raw workspace。
     // 根因:quick-start <dir> 把 .team/runtime/spec 落在 team_workspace(dir)=**parent**/.team;
@@ -166,7 +179,7 @@ pub fn restart_with_transport_with_session_convergence_deadline(
         convergence.missing.iter().cloned().collect()
     };
     let forced_fresh_convergence = (!convergence.converged).then_some(convergence.clone());
-    let plan = classify_restart_plan(&state, allow_fresh)?;
+    let plan = classify_restart_plan_with_resume_validation(Some(&selected.run_workspace), &state, allow_fresh)?;
     write_restart_resume_decision_events(
         &selected.run_workspace,
         &state,
@@ -186,7 +199,7 @@ pub fn restart_with_transport_with_session_convergence_deadline(
         return Ok(RestartReport::RefusedResumeAtomicity {
             unresumable: plan.unresumable,
             allow_fresh,
-            error: "restart requires resumable workers before live spawn".to_string(),
+            error: "restart requires resumable workers before live spawn; rerun with --allow-fresh to start fresh".to_string(),
         });
     }
     let session_name = state_session_name(&state);
@@ -253,6 +266,15 @@ pub fn restart_with_transport_with_session_convergence_deadline(
     crate::state::projection::save_team_scoped_state(&selected.run_workspace, &state)
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
     let coordinator_started = start_coordinator_for_workspace(&selected.run_workspace)?;
+    wait_restart_readiness_or_timeout(
+        &selected.run_workspace,
+        &state,
+        &session_name,
+        &plan.decisions,
+        transport,
+        restart_readiness_deadline(readiness_deadline_ms),
+        restart_readiness_poll_interval(),
+    )?;
     let attach_commands = crate::tmux_backend::attach_commands_for_windows(
         &selected.run_workspace,
         &session_name,
@@ -455,6 +477,182 @@ fn parse_duration_value_seconds_ms(value: &str) -> Option<u64> {
     }
 }
 
+fn restart_readiness_deadline(requested_ms: Option<u64>) -> std::time::Duration {
+    requested_ms.map(std::time::Duration::from_millis).unwrap_or_else(|| {
+        env_duration_ms(&["TEAM_AGENT_RESTART_READINESS_DEADLINE_MS"], 30_000)
+    })
+}
+
+fn restart_readiness_poll_interval() -> std::time::Duration {
+    env_duration_ms(&["TEAM_AGENT_RESTART_READINESS_POLL_MS"], 200)
+}
+
+#[derive(Debug, Clone, Copy)]
+struct RestartReadiness {
+    session_created: bool,
+    worker_pane_addressable: bool,
+    coordinator_alive: bool,
+}
+
+impl RestartReadiness {
+    fn ready(self) -> bool {
+        self.session_created && self.worker_pane_addressable && self.coordinator_alive
+    }
+}
+
+fn wait_restart_readiness_or_timeout(
+    workspace: &Path,
+    state: &serde_json::Value,
+    session_name: &SessionName,
+    decisions: &[RestartedAgent],
+    transport: &dyn crate::transport::Transport,
+    deadline: std::time::Duration,
+    poll_interval: std::time::Duration,
+) -> Result<(), LifecycleError> {
+    let started = std::time::Instant::now();
+    loop {
+        let readiness = restart_readiness(workspace, state, session_name, decisions, transport);
+        if readiness.ready() {
+            return Ok(());
+        }
+        let elapsed = started.elapsed();
+        if elapsed >= deadline {
+            write_restart_readiness_timeout_event(workspace, readiness, deadline, elapsed)?;
+            return Err(LifecycleError::RequirementUnmet(restart_readiness_timeout_message(
+                workspace, readiness, deadline,
+            )));
+        }
+        std::thread::sleep(std::cmp::min(poll_interval, deadline.saturating_sub(elapsed)));
+    }
+}
+
+fn restart_readiness(
+    workspace: &Path,
+    state: &serde_json::Value,
+    session_name: &SessionName,
+    decisions: &[RestartedAgent],
+    transport: &dyn crate::transport::Transport,
+) -> RestartReadiness {
+    let session_created = session_live_or_default(transport, session_name, false);
+    let worker_pane_addressable = restart_worker_panes_addressable(state, decisions, transport);
+    let coordinator_workspace = crate::coordinator::WorkspacePath::new(workspace.to_path_buf());
+    let coordinator_alive =
+        crate::coordinator::coordinator_health(&coordinator_workspace).ok && session_created;
+    RestartReadiness { session_created, worker_pane_addressable, coordinator_alive }
+}
+
+fn restart_worker_panes_addressable(
+    state: &serde_json::Value,
+    decisions: &[RestartedAgent],
+    transport: &dyn crate::transport::Transport,
+) -> bool {
+    if decisions.is_empty() {
+        return true;
+    }
+    decisions.iter().all(|decision| {
+        let Some(pane_id) = state
+            .get("agents")
+            .and_then(|agents| agents.get(decision.agent_id.as_str()))
+            .and_then(|agent| agent.get("pane_id"))
+            .and_then(serde_json::Value::as_str)
+            .filter(|pane| !pane.is_empty())
+            .map(crate::transport::PaneId::new)
+        else {
+            return false;
+        };
+        pane_addressable(transport, &pane_id)
+    })
+}
+
+fn pane_addressable(
+    transport: &dyn crate::transport::Transport,
+    pane_id: &crate::transport::PaneId,
+) -> bool {
+    match transport.has_pane(pane_id) {
+        Ok(Some(present)) => present,
+        Ok(None) | Err(_) => {
+            transport
+                .list_targets()
+                .map(|targets| targets.iter().any(|pane| pane.pane_id == *pane_id))
+                .unwrap_or(false)
+                || transport
+                    .liveness(pane_id)
+                    .map(|state| state == crate::transport::PaneLiveness::Live)
+                    .unwrap_or(false)
+        }
+    }
+}
+
+fn write_restart_readiness_timeout_event(
+    workspace: &Path,
+    readiness: RestartReadiness,
+    deadline: std::time::Duration,
+    elapsed: std::time::Duration,
+) -> Result<(), LifecycleError> {
+    crate::event_log::EventLog::new(workspace)
+        .write(
+            "restart.readiness_timeout",
+            serde_json::json!({
+                "tmux_session_created": readiness.session_created,
+                "worker_pane_addressable": readiness.worker_pane_addressable,
+                "coordinator_alive": readiness.coordinator_alive,
+                "deadline_ms": deadline.as_millis(),
+                "elapsed_ms": elapsed.as_millis(),
+                "coordinator_log": crate::coordinator::coordinator_log_path(
+                    &crate::coordinator::WorkspacePath::new(workspace.to_path_buf())
+                ).display().to_string(),
+                "state_path": crate::state::persist::runtime_state_path(workspace).display().to_string(),
+                "pid_path": crate::coordinator::coordinator_pid_path(
+                    &crate::coordinator::WorkspacePath::new(workspace.to_path_buf())
+                ).display().to_string(),
+            }),
+        )
+        .map(|_| ())
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))
+}
+
+fn restart_readiness_timeout_message(
+    workspace: &Path,
+    readiness: RestartReadiness,
+    deadline: std::time::Duration,
+) -> String {
+    let coordinator_workspace = crate::coordinator::WorkspacePath::new(workspace.to_path_buf());
+    let deadline_s = deadline.as_secs_f64();
+    format!(
+        "restart not ready within {deadline_s:.1}s: {missing}\n\
+         - tmux session created: {session}\n\
+         - worker pane addressable: {pane}\n\
+         - coordinator alive: {coordinator}\n\
+         Action: check coordinator log {log}, then `team-agent restart <agent> --allow-fresh` or `team-agent diagnose`\n\
+         Log: coordinator_log={log} state={state} pid_file={pid}",
+        missing = restart_readiness_missing_summary(readiness),
+        session = yes_no(readiness.session_created),
+        pane = yes_no(readiness.worker_pane_addressable),
+        coordinator = yes_no(readiness.coordinator_alive),
+        log = crate::coordinator::coordinator_log_path(&coordinator_workspace).display(),
+        state = crate::state::persist::runtime_state_path(workspace).display(),
+        pid = crate::coordinator::coordinator_pid_path(&coordinator_workspace).display(),
+    )
+}
+
+fn restart_readiness_missing_summary(readiness: RestartReadiness) -> String {
+    let mut missing = Vec::new();
+    if !readiness.session_created {
+        missing.push("tmux session created");
+    }
+    if !readiness.worker_pane_addressable {
+        missing.push("worker pane addressable");
+    }
+    if !readiness.coordinator_alive {
+        missing.push("coordinator alive");
+    }
+    missing.join(", ")
+}
+
+fn yes_no(value: bool) -> &'static str {
+    if value { "yes" } else { "no" }
+}
+
 fn verify_spawned_agent_live(
     _agent_id: &AgentId,
     _spawn: &SpawnedAgentWindow,