@team-agent/installer 0.5.66 → 0.5.68

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

@@ -1,3 +1,28 @@
+//! ---
+//! purpose: worker 进程的环境变量与 argv 占位符处理，以及各 provider 的角色注入落盘
+//! contract:
+//!   provides:
+//!     - name: inherited_env_with_team_overrides
+//!       what: 由当前进程环境按白名单派生 worker spawn 环境，并叠加 team 身份
+//!     - name: apply_mcp_auto_approval_env
+//!       what: 按 bypass 结论写或清 MCP 自动放行相关变量
+//!     - name: apply_copilot_instructions_overlay
+//!       what: 把角色提示词写成 per-agent 的 AGENTS.md 并指向它
+//!     - name: apply_cursor_agent_rules_overlay
+//!       what: 把角色提示词写成 workspace 内 per-agent 的 cursor rules 文件
+//!     - name: fill_spawn_placeholders_full
+//!       what: 替换 argv 里的 workspace、agent_id 与 team_id 占位符
+//!   depends:
+//!     - crate::layout::worker_env
+//!     - crate::event_log::EventLog
+//!     - crate::provider
+//!     - std::fs
+//! boundary:
+//!   - 不写用户全局配置，角色注入一律落在 workspace 或 runtime 目录下的 per-agent 路径
+//!   - 环境里的代理与凭据值只允许记存在与长度，不落值
+//!   - 不 spawn 进程，只准备环境与 argv
+//! maturity: wired
+//! ---
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 use std::process::Command;
@@ -14,10 +39,18 @@ use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest}
 
 use super::*;
 
+/// ---
+/// purpose: 判断 spec 里的该 agent 是否被标为 paused
+/// returns: paused 字段确为真时 true
+/// ---
 pub(super) fn agent_is_paused(agent: &Value) -> bool {
     matches!(agent.get("paused"), Some(Value::Bool(true)))
 }
 
+/// ---
+/// purpose: 给出 spawn 时间戳
+/// returns: 测试固定时间戳环境变量优先，否则取当前 UTC 时间的微秒精度串
+/// ---
 pub(crate) fn spawn_timestamp() -> String {
     match std::env::var("TEAM_AGENT_TEST_FIXED_SPAWNED_AT") {
         Ok(value) => value,
@@ -27,6 +60,12 @@ pub(crate) fn spawn_timestamp() -> String {
     }
 }
 
+/// ---
+/// purpose: 给出带偏移的 spawn 时间戳，用于同批席位间保持先后次序
+/// params:
+///   offset_micros: 相对基准时间的微秒偏移，为 0 时等同 spawn_timestamp
+/// returns: 固定时间戳可解析时加上偏移，否则原样返回固定值；无固定值时取当前时间
+/// ---
 pub(super) fn spawn_timestamp_for_agent(offset_micros: u32) -> String {
     if offset_micros == 0 {
         return spawn_timestamp();
@@ -44,10 +83,17 @@ pub(super) fn spawn_timestamp_for_agent(offset_micros: u32) -> String {
     }
 }
 
+/// ---
+/// purpose: 替换 argv 里的 workspace 与 agent_id 占位符，不带 team_id
+/// ---
 pub(crate) fn fill_spawn_placeholders(argv: &mut [String], workspace: &Path, agent_id: &str) {
     fill_spawn_placeholders_full(argv, workspace, agent_id, None);
 }
 
+/// ---
+/// purpose: 给出 auth_mode 写进环境变量时的稳定字符串
+/// returns: subscription、official_api 或 compatible_api
+/// ---
 /// #229 B-layer worker env contract (`worker_spawn_inherits_parent_process_env_for_proxy_and_ca`):
 /// every worker `transport.spawn_first/into` MUST receive an env map that is the **complete**
 /// `team-agent` process environ (so the child sees the user's PATH ordering, HTTP_PROXY /
@@ -59,10 +105,26 @@ pub(crate) fn fill_spawn_placeholders(argv: &mut [String], workspace: &Path, age
 ///
 /// `TMUX` / `TMUX_PANE` are stripped because they bind the inherited shell to the **launching**
 /// tmux pane; leaving them in would point worker-side tmux integrations at the wrong pane.
+pub(crate) fn auth_mode_env_value(mode: AuthMode) -> &'static str {
+    match mode {
+        AuthMode::Subscription => "subscription",
+        AuthMode::OfficialApi => "official_api",
+        AuthMode::CompatibleApi => "compatible_api",
+    }
+}
+
+/// ---
+/// purpose: 由当前进程环境派生 worker 的 spawn 环境
+/// params:
+///   team_id: 作为 owner team id 重新注入给 worker
+///   auth_mode: 写进环境的 auth_mode 字符串
+/// returns: 白名单过滤后的环境，leader 身份类变量与 TMUX 绑定变量已被剥离
+/// ---
 pub(crate) fn inherited_env_with_team_overrides(
     workspace: &Path,
     agent_id: &str,
     team_id: Option<&str>,
+    auth_mode: Option<&str>,
 ) -> BTreeMap<String, String> {
     // 0.3.28 Step 3: delegate to `layout::worker_env::worker_spawn_env` which
     // implements Python's whitelist semantics (`providers.py:130-145`). The
@@ -77,9 +139,22 @@ pub(crate) fn inherited_env_with_team_overrides(
     //   * Strips `COPILOT_DISABLE_TERMINAL_TITLE` (re-injected per-agent by
     //     `apply_copilot_instructions_overlay` based on the WORKER's provider).
     //   * Strips `TMUX` / `TMUX_PANE` (would attach worker to leader's pane).
-    crate::layout::worker_env::worker_spawn_env(std::env::vars(), workspace, agent_id, team_id)
+    crate::layout::worker_env::worker_spawn_env(
+        std::env::vars(),
+        workspace,
+        agent_id,
+        team_id,
+        auth_mode,
+    )
 }
 
+/// ---
+/// purpose: 按 bypass 结论设置或清除 MCP 自动放行相关环境变量
+/// params:
+///   env: 就地改写的环境表，六个相关键先被无条件清掉
+///   safety: 只有来源为 leader 进程且确为继承而来时才写入放行变量
+/// returns: 不满足条件时只写一个关闭标记
+/// ---
 pub(crate) fn apply_mcp_auto_approval_env(
     env: &mut BTreeMap<String, String>,
     safety: &DangerousApproval,
@@ -128,6 +203,14 @@ pub(crate) fn apply_mcp_auto_approval_env(
     }
 }
 
+/// ---
+/// purpose: 把角色提示词写进 per-agent 的 copilot 指令目录并指向它
+/// params:
+///   system_prompt: 写入 AGENTS.md 的正文
+///   env: 就地写入指令目录与禁用终端标题的变量
+/// returns: 成功返回空值
+/// errors: 建目录或写文件失败时返回 StatePersist，不静默吞
+/// ---
 /// BUG / B2 灵魂件 + C-1-2 + C-6-1 cr verdict — Copilot per-worker AGENTS.md
 /// 写入 + `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` 注入。
 ///
@@ -172,6 +255,50 @@ pub(crate) fn apply_copilot_instructions_overlay(
     Ok(())
 }
 
+/// ---
+/// purpose: 把角色提示词写成 workspace 内 per-agent 的 cursor rules 文件
+/// params:
+///   system_prompt: 写入 rules 正文，文件头声明 alwaysApply
+/// returns: 成功返回空值
+/// errors: 建目录或写文件失败时返回 StatePersist
+/// ---
+/// 0.5.67 Cursor append-system-prompt 方案 1 变体（冒烟 PASS, see
+/// .team/artifacts/0.5.67-cursor-rules-smoke.md）— Cursor `agent` CLI 无
+/// append/rule CLI flag, 只从 workspace 静态 rules 文件读:
+///   `.cursor/rules/**/*.mdc` (alwaysApply: true) / `AGENTS.md` / `.cursorrules`。
+///
+/// 这里在 launch 路径写 `<workspace>/.cursor/rules/team-agent-role-<agent_id>.mdc`
+/// 并把 role（= compile_worker_system_prompt 输出）放进去, argv 只带
+/// `--workspace <workspace>`（cursor_agent.rs）。cursor CLI 读取该目录即加载 role。
+///
+/// 目录布局为 workspace 内 `.cursor/rules/`（Cursor 唯一 rules 通道; 无法像 copilot
+/// 那样放 `.team/runtime/` —— 那是 Cursor 不读的路径）。文件名含 `<agent_id>`
+/// 保证 per-agent 隔离, 不互相污染。
+pub(crate) fn apply_cursor_agent_rules_overlay(
+    workspace: &Path,
+    agent_id: &str,
+    system_prompt: &str,
+) -> Result<(), LifecycleError> {
+    let dir = workspace.join(".cursor").join("rules");
+    std::fs::create_dir_all(&dir)
+        .map_err(|e| LifecycleError::StatePersist(format!("{}: {e}", dir.display())))?;
+    let rules = dir.join(format!("team-agent-role-{agent_id}.mdc"));
+    let content = format!(
+        "---\ndescription: Team Agent role injection (auto-generated)\nalwaysApply: true\n---\n\n{system_prompt}\n"
+    );
+    std::fs::write(&rules, content.as_bytes())
+        .map_err(|e| LifecycleError::StatePersist(format!("{}: {e}", rules.display())))?;
+    Ok(())
+}
+
+/// ---
+/// purpose: 扫出 copilot 侧残留的 MCP server，对非本框架的逐个追加禁用参数
+/// params:
+///   argv: 就地追加禁用参数
+///   log_dir: 残留清单落盘目录
+/// returns: 成功返回空值；copilot 命令不可用或退出码非零时只记录不阻断
+/// errors: 写残留清单文件失败时返回 StatePersist
+/// ---
 /// C-3-2/C-3-3 cr verdict v2 — Copilot spawn 前调 `copilot mcp list` 扫用户全局
 /// `~/.copilot/mcp-config.json` 与 workspace `.mcp.json` 的 MCP 残留;对每个非
 /// `team_orchestrator` server 追加 `--disable-mcp-server <name>`(main-help:72-73)
@@ -246,6 +373,12 @@ pub(super) fn apply_copilot_mcp_residual_disables(
     Ok(())
 }
 
+/// ---
+/// purpose: 从 copilot mcp list 输出里解析 server 名集合
+/// params:
+///   text: 命令原始输出
+/// returns: server 名列表；遇到无配置的提示行立即返回空；只在 servers 段内取缩进行首 token
+/// ---
 /// 解析 `copilot mcp list` 输出取 server 名集合(te 真机实证 v2,1.0.59 形态):
 /// ```text
 /// User servers:
@@ -318,6 +451,65 @@ pub(super) fn parse_copilot_mcp_list_server_names(text: &str) -> Vec<String> {
     out
 }
 
+/// Subscription seats inherit parent env, but that is implicit. Cursor cloud
+/// on this host is blocked without a proxy; `profile_launch` copies these
+/// keys only on the compatible-api path. Copy them explicitly here so a
+/// subscription cursor seat sees the same keys. Values may contain
+/// credentials — callers must only log presence/length, never the value.
+const CURSOR_PROXY_KEYS: &[&str] = &[
+    "HTTPS_PROXY",
+    "HTTP_PROXY",
+    "ALL_PROXY",
+    "NO_PROXY",
+    "https_proxy",
+    "http_proxy",
+    "all_proxy",
+    "no_proxy",
+];
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CursorProxyPresence {
+    pub https_proxy: bool,
+    pub no_proxy: bool,
+}
+
+/// ---
+/// purpose: 给订阅制 cursor 席位显式补上父进程里的代理变量
+/// params:
+///   env: 就地补键，已有同名键不覆盖
+/// returns: 记录是否存在 https 代理与 no_proxy，只记存在与否不记值
+/// ---
+pub fn apply_cursor_subscription_proxy_env(
+    env: &mut BTreeMap<String, String>,
+) -> CursorProxyPresence {
+    let mut https_proxy = false;
+    let mut no_proxy = false;
+    for key in CURSOR_PROXY_KEYS {
+        let Ok(value) = std::env::var(key) else {
+            continue;
+        };
+        if value.is_empty() {
+            continue;
+        }
+        if key.eq_ignore_ascii_case("HTTPS_PROXY") {
+            https_proxy = true;
+        }
+        if key.eq_ignore_ascii_case("NO_PROXY") {
+            no_proxy = true;
+        }
+        env.entry((*key).to_string()).or_insert(value);
+    }
+    CursorProxyPresence {
+        https_proxy,
+        no_proxy,
+    }
+}
+
+/// ---
+/// purpose: 把 profile 推出的环境清除与覆盖套用到 spawn 环境上
+/// params:
+///   env: 先按 env_unset 删键，再并入 env_overlay
+/// ---
 pub(crate) fn apply_profile_launch_env(
     env: &mut BTreeMap<String, String>,
     profile_launch: &crate::provider::ProviderProfileLaunch,
@@ -328,6 +520,11 @@ pub(crate) fn apply_profile_launch_env(
     env.extend(profile_launch.env_overlay.clone());
 }
 
+/// ---
+/// purpose: 把已 spawn 席位的 profile 相关信息写进该席位的 state 节点
+/// params:
+///   state: 就地写入待定 session id、projects 根与 profile_launch 摘要
+/// ---
 pub(super) fn persist_started_agent_plan_state(
     state: &mut serde_json::Map<String, serde_json::Value>,
     started_agent: &StartedAgent,
@@ -362,6 +559,12 @@ pub(super) fn persist_started_agent_plan_state(
     }
 }
 
+/// ---
+/// purpose: 把命令计划与 profile 推出的信息写进该席位的 state 节点
+/// params:
+///   plan: 命令计划，其 projects 根优先于 profile 给出的
+///   profile_launch: profile 推出的启动参数
+/// ---
 pub(crate) fn persist_command_plan_state(
     state: &mut serde_json::Map<String, serde_json::Value>,
     plan: &crate::provider::CommandPlan,
@@ -399,6 +602,10 @@ pub(crate) fn persist_command_plan_state(
     }
 }
 
+/// ---
+/// purpose: 判断名字是否是合法的 POSIX shell 标识符
+/// returns: 首字符为字母或下划线且其余为字母数字下划线时为 true
+/// ---
 pub(super) fn is_posix_shell_identifier(name: &str) -> bool {
     let mut chars = name.chars();
     match chars.next() {
@@ -408,6 +615,12 @@ pub(super) fn is_posix_shell_identifier(name: &str) -> bool {
     chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
 }
 
+/// ---
+/// purpose: 替换 argv 里的 workspace、agent_id 与 team_id 占位符
+/// params:
+///   argv: 就地改写；整串等于占位符时整体替换，否则按子串替换
+///   team_id: None 时按空串替换
+/// ---
 /// Same as [`fill_spawn_placeholders`] plus `{team_id}` substitution everywhere it
 /// appears as a SUBSTRING (the MCP config encodes it as `mcp_servers.team_orchestrator
 /// .env.TEAM_AGENT_OWNER_TEAM_ID="{team_id}"`, embedded inside `-c key=value` strings,

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

@@ -1,3 +1,13 @@
+//! ---
+//! purpose: 冷启、add/clone/fork 入口拼装
+//! contract:
+//!   provides:
+//!     - name: fork_agent
+//!       what: 成员分身入口，grok 走窗口内命令
+//! boundary:
+//!   - 不读 provider 会话落盘
+//! maturity: wired
+//! ---
 //!
 //! lifecycle::launch —— 冷启 / quick-start / 危险审批探测 + add/fork / plan 起步与推进。
 
@@ -18,6 +28,16 @@ use super::*;
 
 // ── lifecycle::launch —— 冷启 / quick-start / 危险审批探测 ──────────────────
 
+/// ---
+/// purpose: 冷启全队的默认入口，按 spec 所在目录绑定 per-team tmux socket 后转 launch_with_transport
+/// params:
+///   spec_path: 已编译 spec 的路径，其父目录即 team 目录
+///   dry_run: 只出路由与权限，不 spawn 也不落盘
+///   auto_approve: 当前为 no-op
+///   skip_profile_smoke: 当前为 no-op
+/// returns: LaunchReport
+/// errors: 透传 launch_with_transport 的错误
+/// ---
 ///
 /// `launch(spec_path, dry_run, auto_approve, skip_profile_smoke)`(`launch/core.py:29`)。
 /// 冷启全队:路由 tasks、resolve 权限/危险审批门、session 冲突检查(冲突 →
@@ -42,6 +62,13 @@ pub fn launch(
     )
 }
 
+/// ---
+/// purpose: 由 spec 路径推出 workspace，再转 launch_with_transport_in_workspace
+/// params:
+///   transport: 已绑定 team socket 的 transport
+/// returns: LaunchReport
+/// errors: 透传 launch_with_transport_in_workspace 的错误
+/// ---
 pub(crate) fn launch_with_transport(
     spec_path: &Path,
     dry_run: bool,
@@ -61,6 +88,17 @@ pub(crate) fn launch_with_transport(
     )
 }
 
+/// ---
+/// purpose: 冷启全队的实体实现，编译 spec、检查 session 冲突、按序 spawn、落 state、出报告
+/// params:
+///   workspace: run workspace 根，事件与 state 都落在这里
+///   spec_path: 已编译 spec 的路径
+///   dry_run: 为真时不 spawn 不落盘，started 为空
+///   auto_approve: 未使用
+///   skip_profile_smoke: 未使用
+/// returns: LaunchReport，其中 leader_receiver_attached 恒 false、session_capture_incomplete_agents 恒空
+/// errors: spec 不存在或解析失败返回 Compile，tmux session 已存在返回 SessionConflict，spawn 与落 state 的错误透传
+/// ---
 pub fn launch_with_transport_in_workspace(
     workspace: &Path,
     spec_path: &Path,
@@ -71,8 +109,8 @@ pub fn launch_with_transport_in_workspace(
 ) -> Result<LaunchReport, LifecycleError> {
     let _ = skip_profile_smoke;
     let _ = auto_approve; // 0.5.66: bypass 单源后无 runtime.dangerous_auto_approve,`--yes` 为 no-op。
-    // 0.5.38 (`.team/artifacts/startup-latency-locate.md` §5): launch.phase
-    // timer with monotonic `elapsed_ms` for latency triage.
+                          // 0.5.38 (`.team/artifacts/startup-latency-locate.md` §5): launch.phase
+                          // timer with monotonic `elapsed_ms` for latency triage.
     let phase_timer = crate::lifecycle::restart::RestartPhaseTimer::start();
     if !spec_path.exists() {
         return Err(LifecycleError::Compile(format!(
@@ -107,13 +145,7 @@ pub fn launch_with_transport_in_workspace(
         Vec::new()
     } else {
         phase_timer.emit(workspace, "launch.phase", "spawn_all");
-        let started = spawn_agents(
-            workspace,
-            spec_path,
-            &spec,
-            &session_name,
-            transport,
-        )?;
+        let started = spawn_agents(workspace, spec_path, &spec, &session_name, transport)?;
         persist_spawn_agent_state(
             workspace,
             spec_path,
@@ -224,8 +256,8 @@ mod plan;
 pub(crate) use plan::{handle_report_result, start_plan};
 
 pub mod spawn;
-pub(super) use spawn::*;
 pub(crate) use spawn::agent_id_spec_source_path;
+pub(super) use spawn::*;
 
 mod layout;
 pub(super) use layout::*;
@@ -260,20 +292,38 @@ pub(crate) use agent_state::{
     persist_effective_approval_policy_from_agent,
 };
 
+mod grok_per_seat;
+pub(crate) use grok_per_seat::{
+    is_per_seat_env_key, non_per_seat_env_in_tables, per_seat_keys_in_toml,
+    strip_per_seat_keys_from_toml,
+};
+
 mod mcp_config;
+pub use mcp_config::apply_grok_mcp_overlay;
 pub(super) use mcp_config::*;
 pub(crate) use mcp_config::{
-    point_native_mcp_config_at_file, resolve_mcp_config, write_worker_mcp_config,
+    ensure_grok_login_and_folder_trust, grok_shared_cwd_error, point_native_mcp_config_at_file,
+    reconcile_grok_toml_per_seat_keys, resolve_mcp_config, write_worker_mcp_config,
     write_worker_mcp_config_for_provider,
 };
 
+mod cursor_mcp;
+pub use cursor_mcp::{
+    apply_cursor_mcp_overlay, apply_cursor_workspace_physical_path, cursor_mcp_enable_argv,
+    enable_cursor_workspace_mcp, physical_workspace_path, refuse_second_cursor_occupant,
+};
+
+mod cursor_create_chat;
+
 mod worker_env;
 pub(super) use worker_env::*;
 pub(crate) use worker_env::{
-    apply_copilot_instructions_overlay, apply_mcp_auto_approval_env, apply_profile_launch_env,
+    apply_copilot_instructions_overlay, apply_cursor_agent_rules_overlay,
+    apply_mcp_auto_approval_env, apply_profile_launch_env, auth_mode_env_value,
     fill_spawn_placeholders, fill_spawn_placeholders_full, inherited_env_with_team_overrides,
     persist_command_plan_state, spawn_timestamp,
 };
+pub use worker_env::{apply_cursor_subscription_proxy_env, CursorProxyPresence};
 
 mod identity;
 pub(super) use identity::*;
@@ -300,7 +350,7 @@ pub(crate) use quick_start_transport::{
 };
 
 pub mod readiness;
-pub(crate) use readiness::launched_team_receiver_is_attached;
+pub use readiness::launched_team_receiver_is_attached;
 pub(super) use readiness::*;
 
 mod add_agent;
@@ -313,19 +363,12 @@ pub(crate) use add_agent_state::inject_agent_into_spec;
 pub(super) use add_agent_state::*;
 
 mod fork_agent;
-pub use fork_agent::fork_agent_with_transport;
 pub(super) use fork_agent::*;
+pub use fork_agent::{fork_agent_with_transport, in_window_fork, in_window_fork_command};
 
 mod fork_entry;
 pub use fork_entry::fork_agent;
 
-mod fork_state;
-pub(super) use fork_state::*;
-
-mod fork_finalize;
-pub(super) use fork_finalize::*;
-pub(crate) use fork_finalize::{finalize_pending_fork_capture, ContextForkFinalized};
-
 mod role_source;
 pub(super) use role_source::*;
 
@@ -337,9 +380,7 @@ pub(super) use ownership::*;
 pub(crate) use ownership::{ensure_owner_allowed, ensure_owner_allowed_for_state, state_path};
 
 pub mod spec_state;
-pub(crate) use spec_state::{
-    override_spec_session_name, override_spec_workspace, spec_agent_id_set, write_spec_atomic,
-};
+pub use spec_state::worker_session_name_pub;
 pub(crate) use spec_state::{
     effective_runtime_config_for_worker_spawn, effective_runtime_config_for_worker_spawn_json,
 };
@@ -350,7 +391,9 @@ use spec_state::{
     spec_agent_values, spec_agents, spec_default_assignee, spec_routes, spec_session_name,
     spec_tasks_json, team_workspace, yaml_value_to_json,
 };
-pub use spec_state::worker_session_name_pub;
+pub(crate) use spec_state::{
+    override_spec_session_name, override_spec_workspace, spec_agent_id_set, write_spec_atomic,
+};
 
 #[cfg(test)]
 mod tests {
@@ -361,10 +404,8 @@ mod tests {
     // leader argv 带 bypass flag + 无角色声明 true → 写 warning 事件。
     #[test]
     fn test_leader_flag_present_but_no_role_true_writes_warning_event() {
-        let ws = std::env::temp_dir().join(format!(
-            "ta-bypass-warning-test-{}",
-            std::process::id()
-        ));
+        let ws =
+            std::env::temp_dir().join(format!("ta-bypass-warning-test-{}", std::process::id()));
         let _ = std::fs::remove_dir_all(&ws);
         std::fs::create_dir_all(&ws).unwrap();
         let spec = yaml::loads(
@@ -415,4 +456,33 @@ mod tests {
         );
         let _ = std::fs::remove_dir_all(&ws);
     }
+
+    #[test]
+    fn team_agent_force_flag_does_not_look_like_bypass() {
+        let ws =
+            std::env::temp_dir().join(format!("ta-bypass-force-not-bypass-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&ws);
+        std::fs::create_dir_all(&ws).unwrap();
+        let spec = yaml::loads(
+            "version: 1\nteam: {}\nleader: {}\nagents:\n  - id: a\n    role: r\n    provider: fake\n    dangerously_skip_permissions: false\n",
+        )
+        .unwrap();
+        let argv = vec![
+            "team-agent".to_string(),
+            "remove-agent".to_string(),
+            "x".to_string(),
+            "--confirm".to_string(),
+            "--force".to_string(),
+        ];
+        emit_dangerous_flag_no_role_declared_warning_with_argv(&ws, &spec, &argv);
+        let events = crate::event_log::EventLog::new(&ws).tail(0).unwrap();
+        assert!(
+            !events.iter().any(|event| {
+                event.get("event").and_then(serde_json::Value::as_str)
+                    == Some("dangerously_flag_present_but_no_role_declared")
+            }),
+            "team-agent --force must not emit bypass warning; events={events:?}"
+        );
+        let _ = std::fs::remove_dir_all(&ws);
+    }
 }

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

@@ -1,3 +1,22 @@
+//! ---
+//! purpose: workspace 级 agent-lifecycle 互斥锁，让同一 workspace 的席位增删起停串行
+//! contract:
+//!   provides:
+//!     - name: acquire_agent_lifecycle_lock
+//!       what: 轮询抢锁，成功返回持有到 Drop 的 guard，超时返回 LifecycleLockTimeout
+//!     - name: agent_lifecycle_lock_path
+//!       what: 给出该 workspace 的锁文件路径
+//!   depends:
+//!     - crate::platform::file_lock
+//!     - crate::event_log::EventLog
+//!     - crate::model::paths
+//! boundary:
+//!   - 不锁 pane 输入通道，那是 pane_input_lock
+//!   - 不做跨 workspace 互斥，锁作用域就是一个 workspace
+//!   - 拿不到锁只超时报错，不强抢也不清理他人锁文件
+//!   - 锁文件内容只作观测用，不作为持有权判据
+//! maturity: wired
+//! ---
 use std::io::{Seek, Write};
 use std::path::{Path, PathBuf};
 use std::time::{Duration, Instant};
@@ -17,10 +36,16 @@ pub(crate) struct LifecycleLockRequest<'a> {
 }
 
 pub(crate) struct LifecycleLockGuard {
-    #[allow(dead_code)]
     file: std::fs::File,
 }
 
+/// ---
+/// purpose: 抢 workspace 级 agent-lifecycle 锁，默认 30 秒超时、5 秒起写 lock_held_long 事件
+/// params:
+///   request: 携带 workspace、操作名与可选 team/agent，仅用于锁元数据与事件
+/// returns: 持有锁的 guard，Drop 时解锁
+/// errors: 建目录或打开锁文件失败返回 StatePersist，等待超时返回 LifecycleLockTimeout
+/// ---
 pub(crate) fn acquire_agent_lifecycle_lock(
     request: LifecycleLockRequest<'_>,
 ) -> Result<LifecycleLockGuard, LifecycleError> {
@@ -35,6 +60,14 @@ pub(crate) fn acquire_agent_lifecycle_lock(
     )
 }
 
+/// ---
+/// purpose: 以显式超时与告警阈值抢同一把锁，仅测试构建可见
+/// params:
+///   timeout: 放弃等待的上限
+///   held_long: 超过它写一次 lock_held_long 事件
+/// returns: 持有锁的 guard
+/// errors: 同 acquire_agent_lifecycle_lock
+/// ---
 #[cfg(test)]
 pub(crate) fn acquire_agent_lifecycle_lock_for_test(
     request: LifecycleLockRequest<'_>,
@@ -55,6 +88,10 @@ pub(crate) struct LifecycleLockDeadlineOverrideGuard {
     previous: Option<(Duration, Duration)>,
 }
 
+/// ---
+/// purpose: 线程内改写默认锁超时与告警阈值，仅测试构建可见
+/// returns: guard，Drop 时恢复上一次的取值
+/// ---
 #[cfg(test)]
 pub(crate) fn override_agent_lifecycle_lock_deadlines_for_test(
     timeout: Duration,
@@ -145,6 +182,10 @@ fn acquire_agent_lifecycle_lock_with_deadlines(
     }
 }
 
+/// ---
+/// purpose: 给出该 workspace 的 agent-lifecycle 锁文件路径
+/// returns: runtime 目录下的 agent-lifecycle.lock
+/// ---
 pub(crate) fn agent_lifecycle_lock_path(workspace: &Path) -> PathBuf {
     crate::model::paths::runtime_dir(workspace).join(format!("{AGENT_LIFECYCLE_LOCK_NAME}.lock"))
 }

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

@@ -1,3 +1,13 @@
+//! ---
+//! purpose: team 进程级生命周期编排（起停加减 clone/fork）
+//! contract:
+//!   provides:
+//!     - name: launch
+//!       what: 冷启与成员生命周期入口
+//! boundary:
+//!   - 不拥有物理注入，只调用 transport
+//! maturity: wired
+//! ---
 //!
 //! step 13 · lifecycle — team 进程级生命周期编排器(ROUND-0.5 骨架)。
 //!
@@ -46,6 +56,7 @@ pub mod display;
 pub mod helpers;
 pub mod launch;
 pub(crate) mod lock;
+pub(crate) mod pane_input_lock;
 pub(crate) mod profile_launch;
 pub(crate) mod profile_smoke;
 pub mod restart;