@team-agent/installer 0.3.1 → 0.3.3

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

@@ -150,6 +150,14 @@ pub(crate) fn write_team_state(
             lines.push(format!("- {id}: {summary}"));
         }
     }
+    if let Some(notes) = team_state_notes(state).filter(|notes| !notes.is_empty()) {
+        lines.push(String::new());
+        lines.push("## Notes".to_string());
+        lines.push(String::new());
+        for note in notes {
+            lines.push(format!("- {note}"));
+        }
+    }
     lines.push(String::new());
     lines.push("## Next Step".to_string());
     lines.push(String::new());
@@ -182,6 +190,17 @@ fn team_state_tasks(spec: &YamlValue, state: &serde_json::Value) -> Vec<TeamStat
     Vec::new()
 }
 
+fn team_state_notes(state: &serde_json::Value) -> Option<Vec<String>> {
+    Some(
+        state
+            .get("notes")?
+            .as_array()?
+            .iter()
+            .filter_map(|note| note.as_str().filter(|text| !text.is_empty()).map(str::to_string))
+            .collect(),
+    )
+}
+
 fn task_field_str(task: &TeamStateTask, key: &str) -> String {
     match task {
         TeamStateTask::Json(v) => v.get(key).and_then(|v| v.as_str()).unwrap_or("").to_string(),

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

@@ -33,8 +33,12 @@ mod team_state;
 
 pub use agent::{reset_agent, reset_agent_with_transport, start_agent, start_agent_with_transport, stop_agent, stop_agent_with_transport};
 pub(crate) use agent::start_agent_at_paths;
+pub(crate) use common::refresh_missing_provider_sessions;
 pub use orchestrator::{halt_plan, plan_status};
-pub use rebuild::{restart, restart_candidates, restart_with_transport, select_restart_state};
+pub use rebuild::{
+    restart, restart_candidates, restart_with_session_convergence_deadline, restart_with_transport,
+    select_restart_state,
+};
 pub use remove::{remove_agent, remove_agent_with_transport};
 pub use selection::{classify_first_send_at, classify_restart_plan, decide_start_mode, python_type_name};
 pub(crate) use team_state::write_team_state;
@@ -45,6 +49,13 @@ pub(crate) fn lifecycle_run_workspace(workspace: &Path) -> Result<std::path::Pat
 }
 
 fn lifecycle_paths(workspace: &Path, team: Option<&str>) -> Result<LifecyclePaths, LifecycleError> {
+    if input_has_no_local_team_context(workspace) {
+        return Err(LifecycleError::TeamSelect(format!(
+            "active team spec not found: input_workspace={} expected_spec_path={}",
+            workspace.display(),
+            workspace.join("team.spec.yaml").display()
+        )));
+    }
     let selected = crate::state::selector::resolve_active_team(
         workspace,
         team,
@@ -60,6 +71,18 @@ fn lifecycle_paths(workspace: &Path, team: Option<&str>) -> Result<LifecyclePath
     })
 }
 
+pub(crate) fn input_has_no_local_team_context(workspace: &Path) -> bool {
+    !workspace.join("team.spec.yaml").exists()
+        && !workspace.join(".team").exists()
+        && !crate::state::persist::runtime_state_path(workspace).exists()
+        && workspace.file_name().and_then(|s| s.to_str()) != Some(".team")
+        && workspace
+            .parent()
+            .and_then(|p| p.file_name())
+            .and_then(|s| s.to_str())
+            != Some(".team")
+}
+
 fn selected_state_spec_workspace(state: &serde_json::Value) -> Option<std::path::PathBuf> {
     state
         .get("spec_path")

package/crates/team-agent/src/lifecycle/tests/lane_ops.rs

@@ -496,10 +496,10 @@ fn lanea_fork_window_already_exists_guard_before_spec_mutation() {
 
 // ── FORK (fork-gate-error-text) [RED] + (fork-incomplete-rollback, adapter arm) — golden gate text + spec rollback
 // Golden operations.py:329-330 raises f"{provider} does not support native session fork" when the native
-// fork gate fails (auth_mode==compatible_api). Rust relies on adapter.fork() -> CapabilityUnsupported
+// fork gate fails (auth_mode==compatible_api). Rust relies on adapter.fork_plan() -> CapabilityUnsupported
 // ("Codex:fork") (adapter.rs:310) -> a different observable. AND golden wraps the post-spec-write steps
 // in try/except restoring the spec on ANY failure (operations.py:384-394); Rust writes the spec
-// (launch.rs:443) then errors at adapter.fork (458-460) WITHOUT restoring it. RED on both: the message
+// (launch.rs:443) then errors at adapter.fork_plan (458-460) WITHOUT restoring it. RED on both: the message
 // text AND the spec must be rolled back to not contain the fork agent.
 #[test]
 fn lanea_fork_gate_error_text_and_spec_rollback_on_adapter_arm() {
@@ -516,7 +516,7 @@ fn lanea_fork_gate_error_text_and_spec_rollback_on_adapter_arm() {
     assert!(
         !spec_text.contains("newfork"),
         "golden operations.py:384-394: on the gate failure the spec must be ROLLED BACK; Rust writes the spec \
-         then errors at adapter.fork without restoring it, leaving the fork agent 'newfork' in the spec"
+         then errors at adapter.fork_plan without restoring it, leaving the fork agent 'newfork' in the spec"
     );
 }
 
@@ -568,9 +568,9 @@ fn lanea_remove_rollback_restores_agent_health() {
 // (4) restores prior state. Rust only restores the spec on the spawn_into arm (launch.rs:481); the
 // save_runtime_state (486-487) and start_coordinator (488-493) failure arms leave the spec mutated, the
 // already-spawned window un-killed, and the state un-rolled-back; install_mcp/cleanup_mcp are absent.
-// The adapter.fork arm IS covered HARD above (lanea_fork_gate_error_text_and_spec_rollback_on_adapter_arm).
+// The adapter.fork_plan arm IS covered HARD above (lanea_fork_gate_error_text_and_spec_rollback_on_adapter_arm).
 // The post-SPAWN arms need a failure-injection seam after spawn_into (codex+subscription forks past
-// adapter.fork, so the spawn succeeds and there is no in-process way to fail save/coordinator cleanly).
+// adapter.fork_plan, so the spawn succeeds and there is no in-process way to fail save/coordinator cleanly).
 // PORTER: a Drop guard armed after the spec write, disarmed on success — kills the window, restores spec
 // + state, runs cleanup_mcp on every post-write error arm.
 #[test]

package/crates/team-agent/src/lifecycle/tests/launch_spawn.rs

@@ -649,8 +649,9 @@ pub(super) fn restart_ws_two_resumable_workers() -> PathBuf {
 }
 
 // 2 [P0] — restart_with_transport must drive the REAL Route-B resume spawn: one spawn per resumable
-// worker (first=spawn_first, rest=spawn_into), each carrying the provider build_command, + coordinator
-// started. Today the stub returns RequirementUnmet with ZERO spawns -> RED at recorded.len().
+// worker. The first resumed worker recreates the session with spawn_first; later workers may use
+// spawn_into only after a live-session check proves that recreated session still exists. Each spawn
+// carries the provider build_command, and the coordinator is started.
 #[test]
 fn restart_with_transport_spawns_resumable_workers_not_stub() {
     let ws = restart_ws_two_resumable_workers();
@@ -665,10 +666,13 @@ fn restart_with_transport_spawns_resumable_workers_not_stub() {
         "restart must spawn ONE worker per resumable agent (alpha, bravo); the rt-host-a stub returns \
          RequirementUnmet with ZERO spawns; got {recorded:?}"
     );
-    assert_eq!(recorded[0].0, "spawn_first", "the first resumed worker uses new-session (spawn_first); got {recorded:?}");
-    assert!(
-        recorded.iter().any(|(kind, _)| kind == "spawn_into"),
-        "subsequent resumed workers use new-window (spawn_into); got {recorded:?}"
+    assert_eq!(
+        recorded[0].0, "spawn_first",
+        "with has-session=false before alpha, restart must recreate the session with spawn_first; got {recorded:?}"
+    );
+    assert_eq!(
+        recorded[1].0, "spawn_into",
+        "with has-session=true after alpha spawn, restart may add bravo with spawn_into; this is liveness-based, not index-based; got {recorded:?}"
     );
     assert!(
         recorded.iter().all(|(_, argv)| argv.iter().any(|a| a == "codex")),
@@ -678,6 +682,25 @@ fn restart_with_transport_spawns_resumable_workers_not_stub() {
         matches!(result, Ok(RestartReport::Restarted { coordinator_started: true, .. })),
         "restart must reach RestartReport::Restarted with coordinator_started=true (AlreadyRunning, seeded); got {result:?}"
     );
+
+    let ws = restart_ws_two_resumable_workers();
+    let dead_after_first = OfflineTransport::new().with_session_absent_after_spawn_first();
+    let result = restart_with_transport(&ws, false, None, &dead_after_first);
+    let recorded = dead_after_first.spawn_records();
+    assert_eq!(
+        recorded.len(),
+        1,
+        "if the session disappears after alpha, restart must stop before spawning bravo; got result={result:?} recorded={recorded:?}"
+    );
+    assert!(
+        recorded.iter().all(|(kind, _)| kind != "spawn_into"),
+        "restart must not call spawn_into/new-window for bravo against a dead server; result={result:?} recorded={recorded:?}"
+    );
+    let error = format!("{result:?}");
+    assert!(
+        error.contains("session_disappeared_after_spawn") || error.contains("provider_resume_exited"),
+        "restart must report the first resumed agent/session disappearance explicitly, not continue to a later no-server failure; result={result:?}"
+    );
 }
 
 // 3 [P0] — start_agent_with_transport on a non-paused agent with a session_id must spawn EXACTLY ONE
@@ -899,6 +922,7 @@ fn quick_start_running_agent_state_shape_after_spawn_is_golden() {
             "window",
             "mcp_config",
             "permissions",
+            "effective_approval_policy",
             "session_id",
             "rollout_path",
             "captured_at",
@@ -906,6 +930,7 @@ fn quick_start_running_agent_state_shape_after_spawn_is_golden() {
             "attribution_confidence",
             "spawn_cwd",
             "spawned_at",
+            "pane_id",
         ],
         "running agent state key order must match golden launch/core.py:238-255; raw={raw}"
     );
@@ -935,8 +960,13 @@ fn quick_start_running_agent_state_shape_after_spawn_is_golden() {
     assert!(agent["captured_at"].is_null());
     assert!(agent["captured_via"].is_null());
     assert!(agent["attribution_confidence"].is_null());
-    assert_eq!(agent["spawn_cwd"], json!(workspace.to_string_lossy()));
+    assert_eq!(agent["spawn_cwd"], json!(team.to_string_lossy()));
     assert_eq!(agent["spawned_at"], json!(FIXED_SPAWNED_AT));
+    assert_eq!(
+        agent["pane_id"],
+        json!("%0"),
+        "#252 RC2: launch must persist the real pane_id returned by the transport, not drop it when pane_pid is unavailable"
+    );
 }
 
 // Stage B2 — golden launch/core.py:171-173 writes paused workers as exactly

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

@@ -220,9 +220,15 @@ pub enum WorkerDisplay {
     Adaptive {
         status: DisplayStatus,
         window: Option<WindowName>,
+        workspace_window: Option<WindowName>,
         pane_id: Option<PaneId>,
+        pane_title: Option<String>,
         target: Option<String>,
+        target_worker_session: Option<String>,
+        linked_session: Option<String>,
         leader_session: Option<SessionName>,
+        display_session: Option<SessionName>,
+        fallback: Option<String>,
     },
     GhosttyWindow {
         status: DisplayStatus,
@@ -415,6 +421,7 @@ pub struct LaunchReport {
     pub safety: DangerousApproval,
     /// leader receiver(attach 成功时;经 step10 leader::attach_leader_to_state)。
     pub leader_receiver_attached: bool,
+    pub session_capture_incomplete_agents: Vec<String>,
 }
 
 /// 单个已起 worker(`launch` 的 `agents[]` / `started`)。
@@ -425,6 +432,10 @@ pub struct StartedAgent {
     pub target: String,
     pub session_id: Option<SessionId>,
     pub rollout_path: Option<RolloutPath>,
+    pub pending_session_id: Option<SessionId>,
+    pub claude_config_dir: Option<PathBuf>,
+    pub provider_projects_root: Option<PathBuf>,
+    pub managed_mcp_config: bool,
     pub display: WorkerDisplay,
 }
 
@@ -610,6 +621,14 @@ pub enum RestartReport {
         allow_fresh: bool,
         error: String,
     },
+    /// session capture did not converge before destructive restart. No teardown/spawn occurred.
+    RefusedResumeNotReady {
+        missing: Vec<AgentId>,
+        allow_fresh: bool,
+        deadline: std::time::Duration,
+        elapsed: std::time::Duration,
+        error: String,
+    },
     /// first_send_at 损坏(`reason=invalid_first_send_at`):决策前 hard refuse。
     RefusedInvalidFirstSendAt {
         invalid: Vec<CorruptFirstSendAt>,

package/crates/team-agent/src/mcp_server/helpers.rs

@@ -60,6 +60,7 @@ pub(crate) fn tool_error_reason_wire(reason: ToolErrorReason) -> &'static str {
         ToolErrorReason::InvalidToolArguments => "invalid_tool_arguments",
         ToolErrorReason::InternalRuntimeError => "internal_runtime_error",
         ToolErrorReason::PeerNotInScope => "peer_not_in_scope",
+        ToolErrorReason::McpScopeRefused => "mcp.scope_refused",
     }
 }
 

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

@@ -0,0 +1,341 @@
+use std::path::{Path, PathBuf};
+
+use serde_json::Value;
+
+use crate::lifecycle::{ResetAgentOutcome, ResetRefusal};
+use crate::model::yaml::{self, Value as YamlValue};
+use crate::model::ids::{AgentId, TeamKey};
+
+use super::super::helpers::{enum_value, object_fields, tool_runtime_error};
+use super::super::{ToolOk, ToolResult};
+
+pub(crate) fn stop_agent(
+    workspace: &Path,
+    owner_team: Option<&TeamKey>,
+    agent_id: &str,
+) -> ToolResult {
+    let lifecycle_workspace = lifecycle_workspace(workspace, owner_team, true)?;
+    let report = crate::lifecycle::stop_agent(
+        &lifecycle_workspace,
+        &AgentId::new(agent_id),
+        owner_team.map(TeamKey::as_str),
+    )
+    .map_err(tool_runtime_error)?;
+    Ok(ToolOk {
+        fields: object_fields(serde_json::json!({
+            "ok": true,
+            "agent_id": report.agent_id.as_str(),
+            "status": "stopped",
+            "stopped": report.stopped,
+            "target": report.target,
+            "display_closed": report.display_closed,
+            "state_file": report.state_file.to_string_lossy().to_string(),
+        })),
+    })
+}
+
+pub(crate) fn reset_agent(
+    workspace: &Path,
+    owner_team: Option<&TeamKey>,
+    agent_id: &str,
+    discard_session: bool,
+) -> ToolResult {
+    if !discard_session {
+        return Ok(ToolOk {
+            fields: object_fields(serde_json::json!({
+                "ok": false,
+                "agent_id": agent_id,
+                "status": "refused",
+                "reason": "discard_session_required",
+            })),
+        });
+    }
+    let lifecycle_workspace = lifecycle_workspace(workspace, owner_team, true)?;
+    match crate::lifecycle::reset_agent(
+        &lifecycle_workspace,
+        &AgentId::new(agent_id),
+        discard_session,
+        false,
+        owner_team.map(TeamKey::as_str),
+    )
+    .map_err(tool_runtime_error)?
+    {
+        ResetAgentOutcome::Reset { env, start_mode } => Ok(ToolOk {
+            fields: object_fields(serde_json::json!({
+                "ok": true,
+                "agent_id": env.agent_id.as_str(),
+                "status": "reset",
+                "state_file": env.state_file.to_string_lossy().to_string(),
+                "coordinator_started": env.coordinator_started,
+                "start_mode": enum_value(start_mode),
+            })),
+        }),
+        ResetAgentOutcome::Refused { reason } => Ok(ToolOk {
+            fields: object_fields(serde_json::json!({
+                "ok": false,
+                "agent_id": agent_id,
+                "status": "refused",
+                "reason": reset_refusal_reason(reason),
+            })),
+        }),
+    }
+}
+
+pub(crate) fn fork_agent(
+    workspace: &Path,
+    owner_team: Option<&TeamKey>,
+    source_agent_id: &str,
+    as_agent_id: &str,
+    label: Option<&str>,
+) -> ToolResult {
+    let _ = label;
+    let lifecycle_workspace = lifecycle_workspace(workspace, owner_team, false)?;
+    let report = crate::lifecycle::launch::fork_agent(
+        &lifecycle_workspace,
+        &AgentId::new(source_agent_id),
+        &AgentId::new(as_agent_id),
+        false,
+        owner_team.map(TeamKey::as_str),
+    )
+    .map_err(tool_runtime_error)?;
+    Ok(ToolOk {
+        fields: object_fields(serde_json::json!({
+            "ok": true,
+            "status": "forked",
+            "source_agent_id": report.source_agent_id.as_str(),
+            "agent_id": report.new_agent_id.as_str(),
+            "new_agent_id": report.new_agent_id.as_str(),
+            "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()),
+        })),
+    })
+}
+
+fn reset_refusal_reason(reason: ResetRefusal) -> Value {
+    match reason {
+        ResetRefusal::DiscardSessionRequired => Value::String("discard_session_required".to_string()),
+    }
+}
+
+fn lifecycle_workspace(
+    workspace: &Path,
+    owner_team: Option<&TeamKey>,
+    prepare_state: bool,
+) -> Result<PathBuf, super::super::ToolError> {
+    let team = owner_team.map(TeamKey::as_str);
+    if let Ok(raw_state) = load_local_runtime_state(workspace) {
+        if let Some(path) = state_spec_workspace(&raw_state, team) {
+            return Ok(path);
+        }
+        if raw_state.get("agents").is_some() || raw_state.get("teams").is_some() {
+            return materialize_mcp_lifecycle_spec(workspace, raw_state, team, prepare_state);
+        }
+    }
+    if let Ok(selected) = crate::state::selector::resolve_active_team(
+        workspace,
+        team,
+        crate::state::selector::SelectorMode::RequireSpec,
+    ) {
+        if let Some(path) = selected.spec_workspace {
+            return Ok(path);
+        }
+    }
+    let state = crate::state::projection::select_runtime_state(workspace, team)
+        .map_err(tool_runtime_error)?;
+    if let Some(path) = state_spec_workspace(&state, team) {
+        return Ok(path);
+    }
+    Ok(workspace.to_path_buf())
+}
+
+fn state_spec_workspace(state: &Value, team: Option<&str>) -> Option<PathBuf> {
+    if let Some(team) = team {
+        if let Some(entry) = state
+            .get("teams")
+            .and_then(Value::as_object)
+            .and_then(|teams| teams.get(team))
+        {
+            if let Some(path) = state_spec_workspace_from_entry(entry) {
+                return Some(path);
+            }
+        }
+    }
+    state_spec_workspace_from_entry(state).or_else(|| {
+        let teams = state.get("teams").and_then(Value::as_object)?;
+        if teams.len() == 1 {
+            teams.values().next().and_then(state_spec_workspace_from_entry)
+        } else {
+            None
+        }
+    })
+}
+
+fn state_spec_workspace_from_entry(state: &Value) -> Option<PathBuf> {
+    state
+        .get("spec_path")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+        .and_then(|s| Path::new(s).parent().map(Path::to_path_buf))
+        .filter(|p| p.join("team.spec.yaml").exists())
+        .or_else(|| {
+            state
+                .get("team_dir")
+                .and_then(Value::as_str)
+                .filter(|s| !s.is_empty())
+                .map(PathBuf::from)
+                .filter(|p| p.join("team.spec.yaml").exists())
+        })
+}
+
+fn load_local_runtime_state(workspace: &Path) -> Result<Value, super::super::ToolError> {
+    let path = crate::state::persist::runtime_state_path(workspace);
+    let text = std::fs::read_to_string(&path).map_err(|e| {
+        tool_runtime_error(format!("read local runtime state {}: {e}", path.display()))
+    })?;
+    serde_json::from_str(&text).map_err(|e| {
+        tool_runtime_error(format!("parse local runtime state {}: {e}", path.display()))
+    })
+}
+
+fn materialize_mcp_lifecycle_spec(
+    workspace: &Path,
+    mut state: Value,
+    team: Option<&str>,
+    prepare_state: bool,
+) -> Result<PathBuf, super::super::ToolError> {
+    let team_name = team
+        .filter(|s| !s.is_empty())
+        .or_else(|| state.get("active_team_key").and_then(Value::as_str))
+        .unwrap_or("team");
+    let team_name = team_name.to_string();
+    let Some(agents) = selected_agents(&state, team) else {
+        return Ok(workspace.to_path_buf());
+    };
+    let mut agent_items = Vec::new();
+    let top_agents = state.get("agents").and_then(Value::as_object);
+    for (agent_id, agent_state) in agents {
+        let provider = agent_state
+            .get("provider")
+            .and_then(Value::as_str)
+            .or_else(|| {
+                top_agents
+                    .and_then(|all| all.get(agent_id))
+                    .and_then(|agent| agent.get("provider"))
+                    .and_then(Value::as_str)
+            })
+            .unwrap_or("fake");
+        agent_items.push(YamlValue::Map(vec![
+            ("id".to_string(), YamlValue::Str(agent_id.clone())),
+            ("provider".to_string(), YamlValue::Str(provider.to_string())),
+            ("role".to_string(), YamlValue::Str("Worker".to_string())),
+        ]));
+    }
+    if agent_items.is_empty() {
+        return Ok(workspace.to_path_buf());
+    }
+    let spec = YamlValue::Map(vec![
+        (
+            "team".to_string(),
+            YamlValue::Map(vec![
+                ("name".to_string(), YamlValue::Str(team_name.clone())),
+                (
+                    "objective".to_string(),
+                    YamlValue::Str("MCP lifecycle state-backed team".to_string()),
+                ),
+            ]),
+        ),
+        (
+            "leader".to_string(),
+            YamlValue::Map(vec![("provider".to_string(), YamlValue::Str("codex".to_string()))]),
+        ),
+        ("agents".to_string(), YamlValue::List(agent_items)),
+    ]);
+    let spec_workspace = workspace.join(".team").join(&team_name);
+    std::fs::create_dir_all(&spec_workspace).map_err(|e| {
+        tool_runtime_error(format!("create MCP lifecycle spec dir {}: {e}", spec_workspace.display()))
+    })?;
+    let spec_path = spec_workspace.join("team.spec.yaml");
+    std::fs::write(&spec_path, yaml::dumps(&spec)).map_err(|e| {
+        tool_runtime_error(format!("write MCP lifecycle spec {}: {e}", spec_path.display()))
+    })?;
+    if prepare_state {
+        prepare_selected_team_state(workspace, &mut state, &team_name, &spec_workspace, &spec_path)?;
+    }
+    Ok(spec_workspace)
+}
+
+fn selected_agents<'a>(
+    state: &'a Value,
+    team: Option<&str>,
+) -> Option<&'a serde_json::Map<String, Value>> {
+    team
+        .and_then(|team| {
+            state
+                .get("teams")
+                .and_then(Value::as_object)
+                .and_then(|teams| teams.get(team))
+                .and_then(|entry| entry.get("agents"))
+                .and_then(Value::as_object)
+        })
+        .or_else(|| state.get("agents").and_then(Value::as_object))
+}
+
+fn prepare_selected_team_state(
+    workspace: &Path,
+    state: &mut Value,
+    team: &str,
+    spec_workspace: &Path,
+    spec_path: &Path,
+) -> Result<(), super::super::ToolError> {
+    let Some(root) = state.as_object_mut() else {
+        return Ok(());
+    };
+    let top_session_name = root.get("session_name").cloned();
+    let top_leader_receiver = root.get("leader_receiver").cloned();
+    let top_agents = root.get("agents").and_then(Value::as_object).cloned();
+    let teams = root
+        .entry("teams".to_string())
+        .or_insert_with(|| Value::Object(serde_json::Map::new()));
+    let Some(teams) = teams.as_object_mut() else {
+        return Ok(());
+    };
+    let entry = teams
+        .entry(team.to_string())
+        .or_insert_with(|| Value::Object(serde_json::Map::new()));
+    let Some(entry) = entry.as_object_mut() else {
+        return Ok(());
+    };
+    if let Some(value) = top_session_name {
+        entry.entry("session_name".to_string()).or_insert(value);
+    }
+    if let Some(value) = top_leader_receiver {
+        entry.entry("leader_receiver".to_string()).or_insert(value);
+    }
+    entry.insert(
+        "team_dir".to_string(),
+        Value::String(spec_workspace.to_string_lossy().to_string()),
+    );
+    entry.insert(
+        "spec_path".to_string(),
+        Value::String(spec_path.to_string_lossy().to_string()),
+    );
+    if let Some(top_agents) = top_agents {
+        if let Some(team_agents) = entry.get_mut("agents").and_then(Value::as_object_mut) {
+            for (agent_id, top_agent) in top_agents {
+                let Some(team_agent) = team_agents.get_mut(&agent_id).and_then(Value::as_object_mut) else {
+                    continue;
+                };
+                let Some(top_agent) = top_agent.as_object() else {
+                    continue;
+                };
+                for (key, value) in top_agent {
+                    team_agent.entry(key.clone()).or_insert_with(|| value.clone());
+                }
+            }
+        }
+    }
+    crate::state::persist::save_runtime_state(workspace, state).map_err(|e| {
+        tool_runtime_error(format!("save MCP lifecycle scoped state {}: {e}", workspace.display()))
+    })
+}

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

@@ -0,0 +1,10 @@
+//! MCP lifecycle tool facades.
+//!
+//! S0 keeps the old placeholder behavior behind stable module boundaries so
+//! follow-up lanes can implement real lifecycle logic without touching tools.rs.
+
+mod agent_ops;
+mod state_status;
+
+pub(crate) use agent_ops::{fork_agent, reset_agent, stop_agent};
+pub(crate) use state_status::{get_team_status, update_state};