@team-agent/installer 0.3.15 → 0.3.16

package/crates/team-agent/src/cli/tests/status_send.rs

@@ -36,6 +36,10 @@ use super::*;
         for key in [
             "team",
             "session_name",
+            "leader_topology",
+            "is_external_leader",
+            "leader_attach_command",
+            "leader_client",
             "tmux_session_present",
             "leader_receiver",
             "agents",
@@ -61,6 +65,27 @@ use super::*;
         let _ = std::fs::remove_dir_all(&ws);
     }
 
+    #[test]
+    fn status_port_status_reports_managed_leader_topology_and_attach_command() {
+        let ws = seed_status_workspace();
+        let mut state = crate::state::persist::load_runtime_state(&ws).unwrap();
+        if let Some(obj) = state.as_object_mut() {
+            obj.insert("is_external_leader".to_string(), json!(false));
+            obj.insert("session_name".to_string(), json!("team-current"));
+        }
+        crate::state::persist::save_runtime_state(&ws, &state).unwrap();
+
+        let v = status_port::status(&ws, /*compact=*/ true, /*detail=*/ false).expect("status");
+
+        assert_eq!(v["leader_topology"], json!("managed"));
+        assert_eq!(v["is_external_leader"], json!(false));
+        let attach = v["leader_attach_command"]
+            .as_str()
+            .expect("managed status includes attach command");
+        assert!(attach.contains("attach -t team-current:leader"), "{attach}");
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+
     #[test]
     fn status_port_status_detail_full_keeps_uncompacted_events() {
         // cmd_status --json --detail -> status_port::status(compact=false): the FULL dict

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

@@ -202,6 +202,8 @@ pub struct LeaderLauncherArgs {
     pub confirm_attach: bool,
     /// `--attach-session <name>` / `--attach-session=<name>`。
     pub attach_session: Option<String>,
+    /// 0.3.16 topology opt-out: keep the old external/current-pane leader launcher path.
+    pub external_leader: bool,
 }
 
 // =============================================================================

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

@@ -7,7 +7,7 @@ use std::process::{Command, Stdio};
 
 use crate::provider::{get_adapter, Provider};
 use crate::tmux_backend::TmuxBackend;
-use crate::transport::{PaneId, SessionName, Target, Transport};
+use crate::transport::{PaneId, SessionName, SpawnResult, Target, Transport, WindowName};
 
 use super::helpers::{
     provider_wire, resolve_workspace_for_hash, sanitize_session_folder, sha1_hex_prefix,
@@ -29,6 +29,7 @@ pub fn leader_start_plan(
     attach_existing: bool,
     confirm_attach: bool,
     attach_session: Option<&SessionName>,
+    external_leader: bool,
 ) -> Result<LeaderStartPlan, LeaderError> {
     if attach_session.is_some() && !confirm_attach {
         return Err(LeaderError::Start(
@@ -49,15 +50,24 @@ pub fn leader_start_plan(
             command_name
         )));
     }
-    let identity = leader_identity_context(workspace, None, None)?;
-    let session_name = attach_session
-        .cloned()
-        .or_else(|| Some(leader_session_name(provider, workspace)));
+    let state = crate::state::persist::load_runtime_state(workspace).ok();
+    let identity = leader_identity_context(workspace, None, state.as_ref())?;
+    let external_path = external_leader || attach_existing || attach_session.is_some();
+    let session_name = if external_path {
+        attach_session
+            .cloned()
+            .or_else(|| Some(leader_session_name(provider, workspace)))
+    } else {
+        Some(managed_team_session_name(&identity))
+    };
     let in_tmux = std::env::var_os("TMUX").is_some();
-    if !in_tmux {
+    if !in_tmux || !external_path {
         ensure_tmux_installed()?;
     }
-    let existing_session = if !in_tmux && !attach_existing && attach_session.is_none() {
+    if !external_path {
+        validate_managed_tmux_context(workspace)?;
+    }
+    let existing_session = if external_path && !in_tmux && !attach_existing && attach_session.is_none() {
         match session_name.as_ref() {
             Some(session) => tmux_session_exists(workspace, session)?,
             None => false,
@@ -65,7 +75,9 @@ pub fn leader_start_plan(
     } else {
         false
     };
-    let mode = if in_tmux {
+    let mode = if !external_path {
+        LeaderStartMode::ManagedTmuxClient
+    } else if in_tmux {
         LeaderStartMode::ExecProvider
     } else if attach_existing || attach_session.is_some() || existing_session {
         LeaderStartMode::AttachExisting
@@ -86,6 +98,7 @@ pub fn leader_start_plan(
     } else {
         leader_env.clone()
     };
+    let provider_argv = provider_command_argv(provider, provider_args);
     Ok(LeaderStartPlan {
         mode,
         provider,
@@ -93,6 +106,10 @@ pub fn leader_start_plan(
         socket: LeaderLaunchSocket::Workspace,
         session_name,
         argv,
+        provider_argv,
+        leader_window: (mode == LeaderStartMode::ManagedTmuxClient)
+            .then(|| WindowName::new("leader")),
+        is_external_leader: external_path,
         leader_env: plan_env,
         identity: Some(identity),
         detached: false,
@@ -142,6 +159,7 @@ pub fn start_leader(
     attach_existing: bool,
     confirm_attach: bool,
     attach_session: Option<&SessionName>,
+    external_leader: bool,
 ) -> Result<(), LeaderError> {
     let plan = leader_start_plan(
         provider,
@@ -150,6 +168,7 @@ pub fn start_leader(
         attach_existing,
         confirm_attach,
         attach_session,
+        external_leader,
     )?;
     crate::event_log::EventLog::new(workspace).write(
         super::LeaderEvent::LeaderStart.name(),
@@ -170,6 +189,9 @@ pub fn execute_leader_plan(
     plan: &LeaderStartPlan,
     workspace: &Path,
 ) -> Result<LeaderLaunchOutcome, LeaderError> {
+    if plan.mode == LeaderStartMode::ManagedTmuxClient {
+        return execute_managed_leader_plan(plan, workspace);
+    }
     let mut argv = plan.argv.clone();
     let detached = plan.mode == LeaderStartMode::NewTmuxSession
         && !std::io::stdin().is_terminal()
@@ -236,6 +258,12 @@ fn start_argv(
             argv.extend(provider_args.iter().cloned());
             Ok(argv)
         }
+        LeaderStartMode::ManagedTmuxClient => {
+            let Some(session) = session_name else {
+                return Err(LeaderError::Start("managed leader session missing".to_string()));
+            };
+            managed_client_argv(workspace, session)
+        }
         LeaderStartMode::AttachExisting => {
             let Some(session) = session_name else {
                 return Err(LeaderError::Start("attach session missing".to_string()));
@@ -283,6 +311,224 @@ fn start_argv(
     }
 }
 
+fn provider_command_argv(provider: Provider, provider_args: &[String]) -> Vec<String> {
+    let mut argv = vec![provider_command_name(provider).to_string()];
+    argv.extend(provider_args.iter().cloned());
+    argv
+}
+
+fn managed_team_session_name(identity: &LeaderIdentity) -> SessionName {
+    let team = identity.team_id.as_str();
+    if team.starts_with("team-") {
+        SessionName::new(team.to_string())
+    } else {
+        SessionName::new(format!("team-{team}"))
+    }
+}
+
+fn managed_client_argv(workspace: &Path, session: &SessionName) -> Result<Vec<String>, LeaderError> {
+    let target = format!("{}:leader", session.as_str());
+    let argv = if std::env::var_os("TMUX").is_some() {
+        vec![
+            "tmux".to_string(),
+            "switch-client".to_string(),
+            "-t".to_string(),
+            target,
+        ]
+    } else {
+        vec![
+            "tmux".to_string(),
+            "attach-session".to_string(),
+            "-t".to_string(),
+            target,
+        ]
+    };
+    Ok(TmuxBackend::argv_for_workspace(workspace, &argv))
+}
+
+fn validate_managed_tmux_context(workspace: &Path) -> Result<(), LeaderError> {
+    let Some(current_endpoint) = crate::tmux_backend::socket_name_from_tmux_env() else {
+        return Ok(());
+    };
+    let expected = crate::tmux_backend::socket_name_for_workspace(workspace);
+    if tmux_endpoint_matches_socket_name(&current_endpoint, &expected) {
+        return Ok(());
+    }
+    Err(LeaderError::Start(format!(
+        "Error: managed leader launch refused inside a different tmux server\nReason: current TMUX socket is {current_endpoint}, but this team uses {expected}\nAction: detach and run from a normal shell, or use --external-leader for the external leader topology"
+    )))
+}
+
+fn tmux_endpoint_matches_socket_name(endpoint: &str, socket_name: &str) -> bool {
+    endpoint == socket_name
+        || Path::new(endpoint)
+            .file_name()
+            .and_then(|name| name.to_str())
+            == Some(socket_name)
+}
+
+fn execute_managed_leader_plan(
+    plan: &LeaderStartPlan,
+    workspace: &Path,
+) -> Result<LeaderLaunchOutcome, LeaderError> {
+    let Some(session) = plan.session_name.as_ref() else {
+        return Err(LeaderError::Start("managed leader session missing".to_string()));
+    };
+    let Some(window) = plan.leader_window.as_ref() else {
+        return Err(LeaderError::Start("managed leader window missing".to_string()));
+    };
+    let transport = TmuxBackend::for_workspace(workspace);
+    let spawned = ensure_managed_leader_pane(&transport, session, window, plan, workspace)?;
+    persist_managed_leader_binding(plan, workspace, &spawned)?;
+    spawn_managed_provider_startup_prompt_handler(
+        plan.provider,
+        workspace.to_path_buf(),
+        spawned.pane_id.as_str().to_string(),
+    );
+    let status = run_leader_argv(&plan.argv, &BTreeMap::new(), plan, workspace)?;
+    let code = status.code();
+    if !status.success() {
+        return Err(LeaderError::Start(format!(
+            "leader launcher exited with status {}",
+            code.map(|c| c.to_string())
+                .unwrap_or_else(|| "signal".to_string())
+        )));
+    }
+    Ok(LeaderLaunchOutcome {
+        status: LeaderLaunchStatus::Exited,
+        exit_code: code,
+        session_name: plan.session_name.clone(),
+        reason: None,
+    })
+}
+
+fn ensure_managed_leader_pane(
+    transport: &TmuxBackend,
+    session: &SessionName,
+    window: &WindowName,
+    plan: &LeaderStartPlan,
+    workspace: &Path,
+) -> Result<SpawnResult, LeaderError> {
+    if transport.has_session(session).unwrap_or(false) {
+        if transport
+            .list_windows(session)
+            .unwrap_or_default()
+            .iter()
+            .any(|existing| existing.as_str() == window.as_str())
+        {
+            if let Some(existing) = transport
+                .list_targets()
+                .unwrap_or_default()
+                .into_iter()
+                .find(|pane| {
+                    pane.session.as_str() == session.as_str()
+                        && pane.window_name.as_ref().map(WindowName::as_str)
+                            == Some(window.as_str())
+                })
+            {
+                return Ok(SpawnResult {
+                    pane_id: existing.pane_id,
+                    session: session.clone(),
+                    window: window.clone(),
+                    child_pid: existing.pane_pid,
+                });
+            }
+        }
+        transport
+            .spawn_into(session, window, &plan.provider_argv, workspace, &plan.leader_env)
+            .map_err(|error| LeaderError::Start(error.to_string()))
+    } else {
+        transport
+            .spawn_first(session, window, &plan.provider_argv, workspace, &plan.leader_env)
+            .map_err(|error| LeaderError::Start(error.to_string()))
+    }
+}
+
+fn persist_managed_leader_binding(
+    plan: &LeaderStartPlan,
+    workspace: &Path,
+    spawned: &SpawnResult,
+) -> Result<(), LeaderError> {
+    let identity = plan
+        .identity
+        .as_ref()
+        .ok_or_else(|| LeaderError::Start("managed leader identity missing".to_string()))?;
+    let mut state = crate::state::persist::load_runtime_state(workspace)
+        .unwrap_or_else(|_| serde_json::json!({}));
+    let owner_epoch = state
+        .get("owner_epoch")
+        .and_then(serde_json::Value::as_u64)
+        .or_else(|| {
+            state
+                .get("team_owner")
+                .and_then(|owner| owner.get("owner_epoch"))
+                .and_then(serde_json::Value::as_u64)
+        })
+        .unwrap_or(0)
+        .saturating_add(1);
+    let now = chrono::Utc::now().to_rfc3339();
+    let socket = crate::tmux_backend::socket_name_for_workspace(workspace);
+    let provider = serde_json::to_value(plan.provider)?;
+    let session = spawned.session.as_str().to_string();
+    let window = spawned.window.as_str().to_string();
+    let pane = spawned.pane_id.as_str().to_string();
+    let receiver = serde_json::json!({
+        "mode": "direct_tmux",
+        "status": "attached",
+        "provider": provider.clone(),
+        "pane_id": pane,
+        "pane": pane,
+        "session_name": session,
+        "window_name": window,
+        "tmux_socket": socket,
+        "leader_session_uuid": identity.leader_session_uuid,
+        "owner_epoch": owner_epoch,
+        "attached_at": now,
+        "discovery": "managed_launcher",
+    });
+    let owner = serde_json::json!({
+        "pane_id": pane,
+        "provider": provider.clone(),
+        "machine_fingerprint": identity.machine_fingerprint,
+        "leader_session_uuid": identity.leader_session_uuid,
+        "owner_epoch": owner_epoch,
+        "claimed_at": now,
+        "claimed_via": "claim-leader",
+        "os_user": identity.os_user,
+    });
+    if let Some(obj) = state.as_object_mut() {
+        obj.insert("session_name".to_string(), serde_json::json!(session));
+        obj.insert(
+            "active_team_key".to_string(),
+            serde_json::json!(identity.team_id.as_str()),
+        );
+        obj.insert("tmux_socket".to_string(), serde_json::json!(socket));
+        obj.insert("is_external_leader".to_string(), serde_json::json!(false));
+        obj.insert(
+            "leader_client".to_string(),
+            serde_json::json!({
+                "diagnostic_only": true,
+                "attach_mode": if std::env::var_os("TMUX").is_some() { "switch-client" } else { "attach-session" },
+                "tmux": std::env::var("TMUX").ok(),
+            }),
+        );
+        obj.insert("leader_receiver".to_string(), receiver);
+        obj.insert("team_owner".to_string(), owner);
+        obj.insert("owner_epoch".to_string(), serde_json::json!(owner_epoch));
+    }
+    let entry = crate::state::projection::compact_team_state(&state);
+    if let Some(obj) = state.as_object_mut() {
+        let teams = obj
+            .entry("teams".to_string())
+            .or_insert_with(|| serde_json::json!({}));
+        if let Some(teams) = teams.as_object_mut() {
+            teams.insert(identity.team_id.as_str().to_string(), entry);
+        }
+    }
+    crate::state::persist::save_runtime_state(workspace, &state)?;
+    Ok(())
+}
+
 fn insert_detach_flag(argv: &mut Vec<String>) -> bool {
     if argv.iter().any(|arg| arg == "-d") {
         return false;
@@ -342,6 +588,24 @@ fn spawn_exec_provider_startup_prompt_handler(provider: Provider, workspace: Pat
     });
 }
 
+fn spawn_managed_provider_startup_prompt_handler(
+    provider: Provider,
+    workspace: PathBuf,
+    pane_id: String,
+) {
+    std::thread::spawn(move || {
+        let transport = TmuxBackend::for_workspace(&workspace);
+        let _ = handle_exec_provider_startup_prompts(
+            provider,
+            &workspace,
+            &pane_id,
+            &transport,
+            30,
+            0.5,
+        );
+    });
+}
+
 fn tmux_transport_for_current_pane() -> TmuxBackend {
     crate::tmux_backend::socket_name_from_tmux_env()
         .map(|endpoint| TmuxBackend::for_tmux_endpoint(&endpoint))

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

@@ -94,6 +94,7 @@ use super::*;
     #[test]
     fn leader_start_mode_serializes_to_python_strings() {
         assert_eq!(serde_json::to_string(&LeaderStartMode::ExecProvider).unwrap(), "\"exec_provider\"");
+        assert_eq!(serde_json::to_string(&LeaderStartMode::ManagedTmuxClient).unwrap(), "\"managed_tmux_client\"");
         assert_eq!(serde_json::to_string(&LeaderStartMode::NewTmuxSession).unwrap(), "\"new_tmux_session\"");
         assert_eq!(serde_json::to_string(&LeaderStartMode::AttachExisting).unwrap(), "\"attach_existing\"");
     }

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

@@ -59,35 +59,131 @@ use super::*;
     #[test]
     #[serial_test::serial(env)]
     fn leader_start_plan_pins_mode_and_leader_env() {
+        let _g = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let _e = EnvGuard::apply(&[("TMUX", None), ("TMUX_PANE", None)]);
         let ws = std::env::temp_dir().join(format!("ta_rs_lsp_{}", std::process::id()));
         std::fs::create_dir_all(&ws).unwrap();
-        let plan = leader_start_plan(Provider::Fake, &[], &ws, false, false, None).unwrap();
+        let plan = leader_start_plan(Provider::Fake, &[], &ws, false, false, None, false).unwrap();
         assert_eq!(plan.provider, Provider::Fake);
-        if std::env::var_os("TMUX").is_some() {
-            // 已在 tmux 内 → exec in-place。
-            assert_eq!(plan.mode, LeaderStartMode::ExecProvider);
-        } else {
-            // 不在 tmux → 新建 tmux session(测试环境假定 tmux 可用;否则 Err(Start))。
-            assert_eq!(plan.mode, LeaderStartMode::NewTmuxSession);
-            // session_name 由派生公式确定。
-            assert_eq!(plan.session_name.as_ref(), Some(&leader_session_name(Provider::Fake, &ws)));
-            // plan 边界 detached 恒 false(`-d` 插入在 start_leader 层,非此处)。
-            assert!(!plan.detached, "leader_start_plan 返回值 detached 恒 false");
-            // leader_env 携带 5 个 TEAM_AGENT_* 导出键(_leader_provider_env)。
-            for key in [
-                "TEAM_AGENT_LEADER_PROVIDER",
-                "TEAM_AGENT_LEADER_SESSION_UUID",
-                "TEAM_AGENT_MACHINE_FINGERPRINT",
-                "TEAM_AGENT_WORKSPACE",
-                "TEAM_AGENT_TEAM_ID",
-            ] {
-                assert!(plan.leader_env.contains_key(key), "leader_env 缺导出键 {key}");
-            }
-            assert_eq!(
-                plan.leader_env.get("TEAM_AGENT_LEADER_PROVIDER").map(String::as_str),
-                Some("fake")
-            );
+        assert_eq!(plan.mode, LeaderStartMode::ManagedTmuxClient);
+        assert_eq!(
+            plan.session_name.as_ref().map(SessionName::as_str),
+            Some("team-current")
+        );
+        assert_eq!(plan.leader_window.as_ref().map(WindowName::as_str), Some("leader"));
+        assert!(!plan.is_external_leader);
+        assert!(
+            plan.argv.iter().any(|arg| arg == "attach-session"),
+            "no-tmux managed launch attaches the user client to the team leader window: {:?}",
+            plan.argv
+        );
+        assert!(
+            plan.argv.iter().any(|arg| arg == "team-current:leader"),
+            "managed client target must be the team leader window: {:?}",
+            plan.argv
+        );
+        // plan 边界 detached 恒 false(`-d` 插入在 start_leader 层,非此处)。
+        assert!(!plan.detached, "leader_start_plan 返回值 detached 恒 false");
+        // leader_env 携带 5 个 TEAM_AGENT_* 导出键(_leader_provider_env)。
+        for key in [
+            "TEAM_AGENT_LEADER_PROVIDER",
+            "TEAM_AGENT_LEADER_SESSION_UUID",
+            "TEAM_AGENT_MACHINE_FINGERPRINT",
+            "TEAM_AGENT_WORKSPACE",
+            "TEAM_AGENT_TEAM_ID",
+        ] {
+            assert!(plan.leader_env.contains_key(key), "leader_env 缺导出键 {key}");
         }
+        assert_eq!(
+            plan.leader_env.get("TEAM_AGENT_LEADER_PROVIDER").map(String::as_str),
+            Some("fake")
+        );
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn leader_start_plan_external_leader_keeps_exec_provider_in_tmux() {
+        let _g = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let _e = EnvGuard::apply(&[("TMUX", Some("/private/tmp/tmux-501/default,88432,187"))]);
+        let ws = std::env::temp_dir().join(format!("ta_rs_lsp_external_{}", std::process::id()));
+        std::fs::create_dir_all(&ws).unwrap();
+
+        let plan = leader_start_plan(Provider::Fake, &[], &ws, false, false, None, true).unwrap();
+
+        assert_eq!(plan.mode, LeaderStartMode::ExecProvider);
+        assert!(plan.is_external_leader);
+        assert_eq!(plan.leader_window, None);
+        assert_eq!(plan.argv, vec!["fake".to_string()]);
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn managed_leader_reuses_existing_team_session_name_without_double_prefix() {
+        let _g = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let _e = EnvGuard::apply(&[("TMUX", None), ("TMUX_PANE", None)]);
+        let ws = std::env::temp_dir().join(format!("ta_rs_lsp_existing_{}", std::process::id()));
+        std::fs::create_dir_all(&ws).unwrap();
+        crate::state::persist::save_runtime_state(
+            &ws,
+            &serde_json::json!({"session_name": "team-alpha"}),
+        )
+        .unwrap();
+
+        let plan = leader_start_plan(Provider::Fake, &[], &ws, false, false, None, false).unwrap();
+
+        assert_eq!(plan.mode, LeaderStartMode::ManagedTmuxClient);
+        assert_eq!(
+            plan.session_name.as_ref().map(SessionName::as_str),
+            Some("team-alpha")
+        );
+        assert!(
+            !plan.argv.iter().any(|arg| arg.contains("team-team-alpha")),
+            "managed session name must not gain a second team- prefix: {:?}",
+            plan.argv
+        );
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn managed_leader_in_same_tmux_server_switches_client() {
+        let _g = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let ws = std::env::temp_dir().join(format!("ta_rs_lsp_switch_{}", std::process::id()));
+        std::fs::create_dir_all(&ws).unwrap();
+        let socket = crate::tmux_backend::socket_name_for_workspace(&ws);
+        let endpoint = format!("/private/tmp/tmux-501/{socket},88432,187");
+        let _e = EnvGuard::apply(&[("TMUX", Some(&endpoint))]);
+
+        let plan = leader_start_plan(Provider::Fake, &[], &ws, false, false, None, false).unwrap();
+
+        assert_eq!(plan.mode, LeaderStartMode::ManagedTmuxClient);
+        assert!(
+            plan.argv.iter().any(|arg| arg == "switch-client"),
+            "same-server managed launch must switch the existing tmux client: {:?}",
+            plan.argv
+        );
+        assert!(
+            plan.argv.iter().any(|arg| arg == "team-current:leader"),
+            "managed switch target must be the team leader window: {:?}",
+            plan.argv
+        );
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn managed_leader_in_different_tmux_server_refuses_with_n38_hint() {
+        let _g = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let _e = EnvGuard::apply(&[("TMUX", Some("/private/tmp/tmux-501/default,88432,187"))]);
+        let ws = std::env::temp_dir().join(format!("ta_rs_lsp_refuse_{}", std::process::id()));
+        std::fs::create_dir_all(&ws).unwrap();
+
+        let err = leader_start_plan(Provider::Fake, &[], &ws, false, false, None, false)
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("Error:"), "{err}");
+        assert!(err.contains("Reason:"), "{err}");
+        assert!(err.contains("Action:"), "{err}");
+        assert!(err.contains("--external-leader"), "{err}");
     }
 
     #[test]

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

@@ -145,6 +145,9 @@ pub enum RereadReason {
 pub enum LeaderStartMode {
     /// `os.environ["TMUX"]` 已在 tmux 内 → exec provider in-place。
     ExecProvider,
+    /// Managed launcher topology: provider pane lives in the team session's `leader` window;
+    /// the invoking terminal is only a tmux client attached/switched to that pane.
+    ManagedTmuxClient,
     /// 无 tmux session → 新建 tmux session。
     NewTmuxSession,
     /// session 已存在 / `--attach-session` → attach。
@@ -331,6 +334,12 @@ pub struct LeaderStartPlan {
     pub session_name: Option<SessionName>,
     /// 要 exec 的 argv(provider argv 或 tmux argv)。
     pub argv: Vec<String>,
+    /// For managed launches, the provider command argv spawned inside the leader pane.
+    pub provider_argv: Vec<String>,
+    /// For managed launches, the window that hosts the leader provider pane.
+    pub leader_window: Option<WindowName>,
+    /// True for external/current-pane leader compatibility paths.
+    pub is_external_leader: bool,
     /// `new_tmux_session` / `exec_provider` 的 leader env 导出。
     pub leader_env: BTreeMap<String, String>,
     pub identity: Option<LeaderIdentity>,