@team-agent/installer 0.5.66 → 0.5.68

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

@@ -1,3 +1,25 @@
+//! ---
+//! purpose: 零配置一键起队入口，编译角色目录、起全队、判嵌套层级并给出 attach 指引
+//! contract:
+//!   provides:
+//!     - name: quick_start
+//!       what: 由角色目录一键起队
+//!     - name: quick_start_in_workspace_with_display_and_backend
+//!       what: 带显示开关与后端选择的起队入口
+//!     - name: quick_start_with_transport_in_workspace_with_display
+//!       what: 起队的实体实现，含 leader pane 校验、层级门与已有 runtime 的早退
+//!   depends:
+//!     - crate::compiler
+//!     - crate::state::persist
+//!     - crate::transport_factory
+//!     - crate::lifecycle::launch::identity
+//!     - crate::lifecycle::launch::quick_start_transport
+//! boundary:
+//!   - 只管初次起队，已有 runtime 时给出 restart 指引而不接管
+//!   - 显式指定非 tmux 后端时不静默退回 tmux，不可用就如实报错
+//!   - 团队嵌套超过两层直接拒绝
+//! maturity: wired
+//! ---
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 use std::process::Command;
@@ -14,6 +36,17 @@ use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest}
 
 use super::*;
 
+/// ---
+/// purpose: 由角色目录推出 workspace 后一键起队
+/// params:
+///   agents_dir: 角色定义目录
+///   name: 请求的团队名
+///   yes: 免确认标志
+///   team_id: 显式团队键，优先于 name
+/// returns: 起队报告
+/// errors: 透传实体实现的错误
+/// contract_id: lifecycle.quick_start.entry
+/// ---
 /// `quick_start(agents_dir, name, yes, team_id)`(`diagnose/quick_start.py:18`)。
 /// 面向用户的零配置入口:编译 team_dir → `launch` → autobind leader receiver → 起
 /// coordinator → `wait_ready` 轮询就绪。归入 lifecycle module(不与 diagnose 混)。
@@ -27,6 +60,12 @@ pub fn quick_start(
     quick_start_in_workspace(&workspace, agents_dir, name, yes, team_id)
 }
 
+/// ---
+/// purpose: 在指定 workspace 起队，transport 优先复用调用方所在 tmux socket
+/// returns: 起队报告
+/// errors: 透传实体实现的错误
+/// contract_id: lifecycle.quick_start.entry
+/// ---
 pub(crate) fn quick_start_in_workspace(
     workspace: &Path,
     agents_dir: &Path,
@@ -39,6 +78,14 @@ pub(crate) fn quick_start_in_workspace(
     quick_start_with_transport_in_workspace(&workspace, agents_dir, name, yes, team_id, &transport)
 }
 
+/// ---
+/// purpose: 带显示开关与后端字面量的起队入口
+/// params:
+///   open_display: 为假时把 spec 的显示后端改成 none
+///   backend: 未给或为 tmux 时走既有 tmux 路径，其余字面量经 transport 工厂解析
+/// returns: 起队报告
+/// errors: 后端字面量不认识时返回 TeamSelect；工厂拒绝或后端不可用时如实报错，不退回 tmux
+/// ---
 /// 0.5.x Phase 1d Batch 2: quick-start with an optional
 /// `--backend <tmux|conpty>` override. When `backend` is `None` or
 /// `Some("tmux")` the transport is the same one the legacy entrypoint
@@ -182,6 +229,12 @@ pub fn quick_start_in_workspace_with_display_and_backend(
     )
 }
 
+/// ---
+/// purpose: 带注入 transport 的起队入口，由角色目录推 workspace
+/// returns: 起队报告
+/// errors: 透传实体实现的错误
+/// contract_id: lifecycle.quick_start.entry
+/// ---
 pub(crate) fn quick_start_with_transport(
     agents_dir: &Path,
     name: Option<&str>,
@@ -193,6 +246,12 @@ pub(crate) fn quick_start_with_transport(
     quick_start_with_transport_in_workspace(&workspace, agents_dir, name, yes, team_id, transport)
 }
 
+/// ---
+/// purpose: 带注入 transport 与显式 workspace 的起队入口，默认开显示
+/// returns: 起队报告
+/// errors: 透传实体实现的错误
+/// contract_id: lifecycle.quick_start.entry
+/// ---
 pub(crate) fn quick_start_with_transport_in_workspace(
     workspace: &Path,
     agents_dir: &Path,
@@ -206,6 +265,13 @@ pub(crate) fn quick_start_with_transport_in_workspace(
     )
 }
 
+/// ---
+/// purpose: 起队的实体实现，校验 leader pane、编译 spec、定团队键、判层级、必要时早退，然后起队并给 attach 指引
+/// params:
+///   open_display: 为假时把显示后端改成 none
+/// returns: 起队报告，含 session 名与 attach 命令
+/// errors: leader pane 环境无效返回 RequirementUnmet；角色目录不存在或编译失败返回 Compile；嵌套层级超限返回 RequirementUnmet；读 state 失败返回 StatePersist
+/// ---
 pub(crate) fn quick_start_with_transport_in_workspace_with_display(
     workspace: &Path,
     agents_dir: &Path,

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

@@ -1,3 +1,26 @@
+//! ---
+//! purpose: 起队路径上的 transport 选择、runtime state 里的 transport 标注与 attach 命令拼装
+//! contract:
+//!   provides:
+//!     - name: quick_start_tmux_backend
+//!       what: 优先复用调用方所在 tmux socket，否则按 workspace 派生
+//!     - name: annotate_runtime_transport
+//!       what: 把 transport 种类与来源写进 state，tmux 时再写 endpoint 三字段
+//!     - name: attach_commands_for_runtime_windows
+//!       what: 拼出用户可直接粘贴的 attach 命令
+//!     - name: attach_window_names_for_state_agents
+//!       what: 由 state 推出这些席位对应的窗口名
+//!   depends:
+//!     - crate::tmux_backend
+//!     - crate::transport::Transport
+//!     - crate::state::projection
+//!     - crate::event_log::EventLog
+//! boundary:
+//!   - 只做选择与标注，不 spawn 也不 kill
+//!   - tmux 专有字段不写进非 tmux 后端的 state
+//!   - pane 标题设置失败只告警不阻断
+//! maturity: wired
+//! ---
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 use std::process::Command;
@@ -14,6 +37,10 @@ use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest}
 
 use super::*;
 
+/// ---
+/// purpose: 定出 quick-start 使用的 tmux 后端
+/// returns: 调用方环境里有 socket 就复用它，否则按 workspace 派生一个
+/// ---
 pub(crate) fn quick_start_tmux_backend(workspace: &Path) -> crate::tmux_backend::TmuxBackend {
     if let Some(endpoint) = crate::tmux_backend::socket_name_from_tmux_env() {
         crate::tmux_backend::TmuxBackend::for_tmux_endpoint(&endpoint)
@@ -22,6 +49,10 @@ pub(crate) fn quick_start_tmux_backend(workspace: &Path) -> crate::tmux_backend:
     }
 }
 
+/// ---
+/// purpose: 说明当前 transport 的 socket 是从哪来的
+/// returns: leader_env 或 workspace；无 endpoint 或两者都不匹配时为 None
+/// ---
 pub(crate) fn selected_tmux_socket_source(
     transport: &dyn Transport,
     workspace: &Path,
@@ -36,6 +67,10 @@ pub(crate) fn selected_tmux_socket_source(
     }
 }
 
+/// ---
+/// purpose: 给 adaptive 布局的 pane 设置标题
+/// returns: 失败只打印告警并写一条事件，不向调用方报错
+/// ---
 pub(crate) fn configure_adaptive_pane_title(
     workspace: &Path,
     transport: &dyn Transport,
@@ -66,6 +101,10 @@ pub(crate) fn configure_adaptive_pane_title(
     }
 }
 
+/// ---
+/// purpose: 把用户给的 workspace 归一成绝对路径
+/// returns: 能 canonicalize 就用它；否则绝对路径原样返回，相对路径接到当前目录后
+/// ---
 pub(super) fn explicit_quick_start_workspace(workspace: &Path) -> PathBuf {
     std::fs::canonicalize(workspace).unwrap_or_else(|_| {
         if workspace.is_absolute() {
@@ -78,6 +117,13 @@ pub(super) fn explicit_quick_start_workspace(workspace: &Path) -> PathBuf {
     })
 }
 
+/// ---
+/// purpose: 把 transport 的种类与来源写进 runtime state
+/// params:
+///   state: 就地写入 transport 段
+///   source: 来源说明，None 时记 unknown
+/// returns: tmux 后端会再调 annotate_runtime_tmux_endpoint，非 tmux 不写 tmux 专有字段
+/// ---
 /// `quick_start` with an injected transport — tests inject a recording mock so the REAL spawn path
 /// (launch dry_run=false → spawn_agents) is asserted without a live tmux; prod uses the real TmuxBackend.
 /// Annotate `state.tmux_endpoint` / `state.tmux_socket` (and `tmux_socket_source`)
@@ -126,6 +172,12 @@ pub fn annotate_runtime_transport(
     }
 }
 
+/// ---
+/// purpose: 把 tmux endpoint、socket 与 socket 来源写进 state
+/// params:
+///   state: 就地写入
+/// returns: transport 没有 endpoint 时不写；socket 名能解析成路径时写路径
+/// ---
 pub(crate) fn annotate_runtime_tmux_endpoint(
     state: &mut serde_json::Value,
     transport: &dyn Transport,
@@ -162,6 +214,12 @@ pub(crate) fn annotate_runtime_tmux_endpoint(
     }
 }
 
+/// ---
+/// purpose: 拼出这些窗口的 tmux attach 命令
+/// params:
+///   endpoint: 已知 endpoint；是绝对路径时直接拼 -S 形式，否则交给 tmux_backend 按 workspace 拼
+/// returns: 与窗口一一对应的命令行
+/// ---
 pub(super) fn attach_commands_for_runtime_windows<'a>(
     endpoint: Option<&str>,
     workspace: &Path,
@@ -199,6 +257,10 @@ pub(super) fn attach_commands_for_runtime_windows<'a>(
     attach
 }
 
+/// ---
+/// purpose: 由本次起的席位推出窗口名
+/// returns: 排序去重后的窗口名，席位没有布局窗口时用 agent id
+/// ---
 pub(super) fn started_attach_window_names(started: &[StartedAgent]) -> Vec<String> {
     let mut windows = started
         .iter()
@@ -215,6 +277,10 @@ pub(super) fn started_attach_window_names(started: &[StartedAgent]) -> Vec<Strin
     windows
 }
 
+/// ---
+/// purpose: 由 state 推出指定席位的窗口名
+/// returns: 每个席位取 layout_window 再取 window，都没有时用 agent id；托管 leader 时追加 leader 窗口
+/// ---
 pub(crate) fn attach_window_names_for_state_agents<'a>(
     state: &serde_json::Value,
     agent_ids: impl IntoIterator<Item = &'a str>,
@@ -240,6 +306,10 @@ pub(crate) fn attach_window_names_for_state_agents<'a>(
     attach_window_names_with_managed_leader(state, windows)
 }
 
+/// ---
+/// purpose: 由 state 里的全部席位推出窗口名
+/// returns: 排序去重后的窗口名，托管 leader 时含 leader 窗口
+/// ---
 pub(super) fn quick_start_attach_window_names(state: &serde_json::Value) -> Vec<String> {
     let windows = state
         .get("agents")
@@ -261,6 +331,10 @@ pub(super) fn quick_start_attach_window_names(state: &serde_json::Value) -> Vec<
     attach_window_names_with_managed_leader(state, windows)
 }
 
+/// ---
+/// purpose: 托管 leader 时补上 leader 窗口并排序去重
+/// returns: 处理后的窗口名列表
+/// ---
 pub(super) fn attach_window_names_with_managed_leader(
     state: &serde_json::Value,
     mut windows: Vec<String>,
@@ -273,6 +347,10 @@ pub(super) fn attach_window_names_with_managed_leader(
     windows
 }
 
+/// ---
+/// purpose: 判断该 state 是否走托管 leader
+/// returns: 由 state::projection 给出的判定
+/// ---
 pub(super) fn state_uses_managed_leader(state: &serde_json::Value) -> bool {
     crate::state::projection::state_is_managed_leader(state)
 }

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

@@ -1,3 +1,22 @@
+//! ---
+//! purpose: 起队后的就绪判定，含 worker 状态汇总与 leader 收件可达性
+//! contract:
+//!   provides:
+//!     - name: quick_start_worker_readiness
+//!       what: 汇总各席位状态给出就绪结论
+//!     - name: quick_start_session_capture_incomplete_agents
+//!       what: 列出会话捕获尚未收敛的席位
+//!     - name: launched_team_receiver_is_attached
+//!       what: 以宿主注册表为准判断 leader 收件是否已挂上
+//!   depends:
+//!     - crate::state::persist
+//!     - crate::session_capture
+//!     - crate::leader::registry
+//! boundary:
+//!   - 可达性以宿主注册表为权威，workspace state 只是副本
+//!   - 判不出来一律当作未挂上，不乐观放行
+//! maturity: wired
+//! ---
 //! unit-8 (Stage 3) — `lifecycle::launch::readiness` phase boundary.
 //!
 //! Dedicated home for coordinator-start + readiness-verdict computation.
@@ -20,6 +39,12 @@ use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest}
 
 use super::*;
 
+/// ---
+/// purpose: 由 runtime state 汇总该团队的就绪结论
+/// params:
+///   team_key: 团队键，teams 表里没有时退到顶层 state
+/// returns: 有非 running 席位时返回 Degraded 并列出它们，否则返回 PendingToolLoad
+/// ---
 pub(super) fn quick_start_worker_readiness(
     workspace: &Path,
     team_key: &str,
@@ -66,6 +91,10 @@ pub(super) fn quick_start_worker_readiness(
     }
 }
 
+/// ---
+/// purpose: 列出会话捕获尚未收敛的席位
+/// returns: 席位 id 列表；读不出 state 时为空
+/// ---
 pub(super) fn quick_start_session_capture_incomplete_agents(
     workspace: &Path,
     team_key: &str,
@@ -81,48 +110,66 @@ pub(super) fn quick_start_session_capture_incomplete_agents(
     crate::session_capture::incomplete_interacted_resumable_agent_ids(team_state)
 }
 
-pub(crate) fn launched_team_receiver_is_attached(workspace: &Path, team_key: &str) -> bool {
-    let Ok(state) = load_runtime_state(workspace) else {
-        return true;
-    };
-    let team_state = state
-        .get("teams")
-        .and_then(serde_json::Value::as_object)
-        .and_then(|teams| teams.get(team_key))
-        .unwrap_or(&state);
-    if team_state.get("leader_receiver").is_none() {
-        return crate::state::projection::state_is_external_leader(team_state);
+/// ---
+/// purpose: 判断该团队的 leader 收件端是否真的挂上了
+/// returns: 注册表明确记为 attached 且 state 可读时为 true；未绑定或判不出一律 false
+/// ---
+/// Host registry is the deliverability authority. Workspace `state.json`
+/// is only a copy. Detection failure is unbound, never attached.
+pub fn launched_team_receiver_is_attached(workspace: &Path, team_key: &str) -> bool {
+    match registry_deliverability(workspace, team_key) {
+        RegistryDeliverability::Attached => {}
+        RegistryDeliverability::Unbound | RegistryDeliverability::Undecidable => return false,
     }
-    if team_uses_fake_model_harness(team_state) {
-        return true;
-    }
-    leader_receiver_is_attached(team_state)
+    load_runtime_state(workspace).is_ok()
 }
 
-pub(super) fn team_uses_fake_model_harness(team_state: &serde_json::Value) -> bool {
-    team_state
-        .get("agents")
-        .and_then(serde_json::Value::as_object)
-        .is_some_and(|agents| {
-            !agents.is_empty()
-                && agents.values().all(|agent| {
-                    agent.get("model").and_then(serde_json::Value::as_str) == Some("fake")
-                })
-        })
+enum RegistryDeliverability {
+    Attached,
+    Unbound,
+    Undecidable,
 }
 
-pub(super) fn leader_receiver_is_attached(team_state: &serde_json::Value) -> bool {
-    let Some(receiver) = team_state.get("leader_receiver") else {
-        return false;
+fn registry_deliverability(workspace: &Path, team_key: &str) -> RegistryDeliverability {
+    let Some(dir) = crate::leader::registry::registry_dir() else {
+        return RegistryDeliverability::Undecidable;
     };
-    let status = receiver
-        .get("status")
-        .and_then(serde_json::Value::as_str)
-        .unwrap_or("");
-    let pane_id = receiver
-        .get("pane_id")
-        .and_then(serde_json::Value::as_str)
-        .or_else(|| receiver.get("pane").and_then(serde_json::Value::as_str))
-        .unwrap_or("");
-    status == "attached" && !pane_id.is_empty() && pane_id != "__team_agent_unbound__"
+    if team_key.is_empty() {
+        return RegistryDeliverability::Unbound;
+    }
+    let hash = crate::leader::registry::workspace_hash(workspace);
+    let path = dir.join(format!("{hash}__{team_key}.json"));
+    match std::fs::read_to_string(&path) {
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            RegistryDeliverability::Unbound
+        }
+        Err(_) => RegistryDeliverability::Undecidable,
+        Ok(text) => {
+            match serde_json::from_str::<crate::leader::registry::LeaderRegistryEntry>(&text) {
+                Err(_) => RegistryDeliverability::Undecidable,
+                Ok(entry) => {
+                    if entry.status != "attached" {
+                        return RegistryDeliverability::Unbound;
+                    }
+                    if let Some(authorized) = entry
+                        .channel
+                        .get("authorized_team_workspace")
+                        .and_then(serde_json::Value::as_str)
+                        .filter(|value| !value.is_empty())
+                    {
+                        if !same_workspace_path(Path::new(authorized), workspace) {
+                            return RegistryDeliverability::Unbound;
+                        }
+                    }
+                    RegistryDeliverability::Attached
+                }
+            }
+        }
+    }
+}
+
+fn same_workspace_path(left: &Path, right: &Path) -> bool {
+    let left = std::fs::canonicalize(left).unwrap_or_else(|_| left.to_path_buf());
+    let right = std::fs::canonicalize(right).unwrap_or_else(|_| right.to_path_buf());
+    left == right
 }

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

@@ -1,10 +1,37 @@
+//! ---
+//! purpose: 把源席最新角色文件物化到 dynamic-role-files
+//! contract:
+//!   provides:
+//!     - name: materialize_latest_role
+//!       what: clone/add 用的角色落盘，以磁盘最新文件为准
+//! boundary:
+//!   - 不负责 fork 窗口注入
+//!   - 不读 provider session 落盘
+//! maturity: wired
+//! ---
 use std::path::{Path, PathBuf};
 
 use crate::lifecycle::LifecycleError;
 use crate::model::ids::AgentId;
 use crate::model::yaml::{self, Value};
 
-use super::set_yaml_map_value;
+fn set_yaml_map_value(
+    value: &mut Value,
+    key: &str,
+    next: Value,
+) -> Result<(), LifecycleError> {
+    let Value::Map(pairs) = value else {
+        return Err(LifecycleError::Compile(
+            "agent entry is not a map".to_string(),
+        ));
+    };
+    if let Some((_, existing)) = pairs.iter_mut().find(|(k, _)| k == key) {
+        *existing = next;
+    } else {
+        pairs.push((key.to_string(), next));
+    }
+    Ok(())
+}
 
 pub(super) struct MaterializedRole {
     path: PathBuf,
@@ -12,10 +39,17 @@ pub(super) struct MaterializedRole {
 }
 
 impl MaterializedRole {
+/// ---
+/// purpose: 取物化出来的角色文件路径
+/// returns: 落盘路径
+/// ---
     pub(super) fn path(&self) -> &Path {
         &self.path
     }
 
+/// ---
+/// purpose: 标记该文件由调用方接管，Drop 时不再删除
+/// ---
     pub(super) fn keep(&mut self) {
         self.keep = true;
     }
@@ -29,6 +63,15 @@ impl Drop for MaterializedRole {
     }
 }
 
+/// ---
+/// purpose: 读源席最新角色文件，改名后物化到托管目录
+/// params:
+///   state: 用于找源席的 dynamic_role_file，找不到时退到 team 目录下的同名 md
+///   as_agent_id: 新席位名，写进 front matter 的 name
+///   label: 非空时覆盖 front matter 的 role
+/// returns: 物化结果，未调用 keep 时 Drop 会删掉该文件
+/// errors: 源文件缺失、未声明 name 或声明与源席不符时返回 Compile；目标已存在返回 RequirementUnmet；建目录或写盘失败返回 StatePersist
+/// ---
 pub(super) fn materialize_latest_role(
     run_workspace: &Path,
     team_dir: &Path,
@@ -86,49 +129,6 @@ pub(super) fn materialize_latest_role(
     Ok(MaterializedRole { path, keep: false })
 }
 
-pub(super) fn clamp_materialized_role_to_leader(
-    materialized: &Path,
-    spec: &Value,
-) -> Result<(), LifecycleError> {
-    let leader_tools = spec
-        .get("leader")
-        .and_then(|leader| leader.get("tools"))
-        .and_then(Value::as_list)
-        .map(|items| {
-            items
-                .iter()
-                .filter_map(Value::as_str)
-                .map(str::to_string)
-                .collect::<Vec<_>>()
-        })
-        .unwrap_or_default();
-    let (mut meta, body) = crate::compiler::read_front_matter(materialized)
-        .map_err(|error| LifecycleError::Compile(error.to_string()))?;
-    let requested = meta
-        .get("tools")
-        .and_then(Value::as_list)
-        .map(|items| {
-            items
-                .iter()
-                .filter_map(Value::as_str)
-                .map(str::to_string)
-                .collect::<Vec<_>>()
-        })
-        .unwrap_or_default();
-    let ceiling = crate::model::permissions::expand_tool_strings(&leader_tools)
-        .into_iter()
-        .collect::<std::collections::BTreeSet<_>>();
-    let effective = crate::model::permissions::expand_tool_strings(&requested)
-        .into_iter()
-        .filter(|tool| ceiling.contains(tool))
-        .map(Value::Str)
-        .collect::<Vec<_>>();
-    set_yaml_map_value(&mut meta, "tools", Value::List(effective))?;
-    let rendered = format!("---\n{}---\n\n{}", yaml::dumps(&meta), body);
-    std::fs::write(materialized, rendered.as_bytes())
-        .map_err(|error| LifecycleError::StatePersist(error.to_string()))
-}
-
 fn resolve_role_source(
     run_workspace: &Path,
     team_dir: &Path,

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

@@ -1,3 +1,22 @@
+//! ---
+//! purpose: 冷启路径的 worker spawn 执行器，按 spec 逐个起席并汇总启动结果
+//! contract:
+//!   provides:
+//!     - name: spawn_agents
+//!       what: 按 spec 顺序起各非 paused 席位，返回已起席位清单
+//!     - name: agent_id_spec_source_path
+//!       what: 尽力还原某席位角色文档的路径，用于审计事件
+//!   depends:
+//!     - crate::transport::Transport
+//!     - crate::provider
+//!     - crate::state::persist
+//!     - crate::lifecycle::profile_launch
+//!     - crate::lifecycle::worker_command_context
+//! boundary:
+//!   - 只负责起席与收集结果，state 落盘由 state_projection 负责
+//!   - 启动提示按掉与 fast 模式启用都是尽力而为，失败不阻断
+//! maturity: wired
+//! ---
 //!
 //! unit-8 (Stage 3) — `lifecycle::launch::spawn` phase boundary.
 //!
@@ -22,6 +41,14 @@ use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest}
 
 use super::*;
 
+/// ---
+/// purpose: 按 spec 顺序起各席位
+/// params:
+///   spec_path: spec 路径，team 目录优先取 state 里的 team_dir
+///   session_name: 目标 tmux session
+/// returns: 已起席位清单，含目标 pane、启动模式、布局与显示信息；spawn 后 pane 已死的席位被跳过
+/// errors: 命令拼装或 transport spawn 失败时返回 LifecycleError
+/// ---
 pub(super) fn spawn_agents(
     workspace: &Path,
     spec_path: &Path,
@@ -207,8 +234,12 @@ pub(super) fn spawn_agents(
             )?;
         }
         fill_spawn_placeholders_full(&mut plan.argv, workspace, agent_id_raw, Some(&mcp_team_id));
-        let mut env =
-            inherited_env_with_team_overrides(workspace, agent_id_raw, Some(&mcp_team_id));
+        let mut env = inherited_env_with_team_overrides(
+            workspace,
+            agent_id_raw,
+            Some(&mcp_team_id),
+            Some(auth_mode_env_value(auth_mode)),
+        );
         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
@@ -256,6 +287,31 @@ pub(super) fn spawn_agents(
                 );
             }
         }
+        // Cursor: role 经 .cursor/rules；MCP 身份必须写进 mcp.json env
+        // （不继承父进程 TEAM_AGENT_*）。--workspace 钉物理路径。
+        // mcp.json last-writer：同 workspace 第二 CursorAgent 拒绝。
+        if matches!(provider, Provider::CursorAgent) {
+            refuse_second_cursor_occupant(workspace, agent_id_raw, Some(spec))?;
+            apply_cursor_agent_rules_overlay(workspace, agent_id_raw, system_prompt.as_str())?;
+            apply_cursor_mcp_overlay(workspace, &mcp_config)?;
+            enable_cursor_workspace_mcp(workspace)?;
+            apply_cursor_workspace_physical_path(&mut plan.argv, workspace);
+            let proxy = apply_cursor_subscription_proxy_env(&mut env);
+            let event_log = crate::event_log::EventLog::new(workspace);
+            let _ = event_log.write(
+                "provider.cursor.proxy_presence",
+                serde_json::json!({
+                    "agent_id": agent_id_raw,
+                    "https_proxy": proxy.https_proxy,
+                    "no_proxy": proxy.no_proxy,
+                }),
+            );
+        }
+        // Grok 无 --mcp-config；写 <cwd>/.grok/config.toml 让 CLI 读到 team-agent。
+        if matches!(provider, Provider::Grok) {
+            ensure_grok_login_and_folder_trust(workspace)?;
+            apply_grok_mcp_overlay(workspace, &mcp_config)?;
+        }
         let spawn_epoch = u64::try_from(started.len()).unwrap_or(u64::MAX);
         let spawned_at = spawn_timestamp_for_agent(u32::try_from(spawn_epoch).unwrap_or(u32::MAX));
         // E6 层1 实证3 + 诊断留痕:落最终 worker argv(spawn 前的真实形态)。
@@ -401,6 +457,10 @@ pub(super) fn spawn_agents(
     Ok(started)
 }
 
+/// ---
+/// purpose: 尽力还原某席位角色文档的路径
+/// returns: state 里有 team_dir 时用它下的 agents 目录，否则退到 workspace 下的当前团队目录
+/// ---
 /// 0.5.66 bypass 单源 §2.7:审计事件里角色 md 的 spec 来源路径(尽力解析,失败空串)。
 pub(crate) fn agent_id_spec_source_path(workspace: &Path, agent_id: &str) -> String {
     let team_dir = crate::state::persist::load_runtime_state(workspace)