@team-agent/installer 0.5.65 → 0.5.68

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

@@ -1,6 +1,32 @@
+//! ---
+//! purpose: 动态角色文档加一席，失败按快照回滚；force 变体先摘旧席再加
+//! contract:
+//!   provides:
+//!     - name: add_agent
+//!       what: 编译角色进 runtime spec 并起席，失败回滚 spec 与 state
+//!     - name: add_agent_force
+//!       what: 先快照并摘除同名旧席，再走正常加席，失败按快照恢复
+//!     - name: add_agent_with_transport_at_paths
+//!       what: 加席的实体实现，含 owner 门、重名拒绝、原子写 spec 与起席
+//!   depends:
+//!     - crate::lifecycle::lock
+//!     - crate::lifecycle::restart
+//!     - crate::lifecycle::restart::remove
+//!     - crate::compiler
+//!     - crate::state::selector
+//!     - crate::state::projection
+//!     - crate::state::persist
+//!     - crate::tmux_backend
+//! boundary:
+//!   - 不拷贝外部角色文件进 team 目录，就地读取编译
+//!   - 起席一律走 restart 的 start_agent_at_paths，本文件不直接 spawn
+//!   - 回滚只恢复 spec 字节与 runtime state，不回收已 spawn 的 pane
+//! maturity: wired
+//! ---
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 use std::process::Command;
+use std::time::{SystemTime, UNIX_EPOCH};
 
 use crate::lifecycle::*;
 use crate::model::enums::{AuthMode, DisplayBackend, PaneLiveness, Provider, ProviderEffort};
@@ -14,6 +40,165 @@ use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest}
 
 use super::*;
 
+struct AgentReservation {
+    workspace: PathBuf,
+    team_key: String,
+    agent_id: AgentId,
+    owner: String,
+    active: bool,
+}
+
+impl AgentReservation {
+    fn commit(mut self) {
+        self.active = false;
+    }
+}
+
+impl Drop for AgentReservation {
+    fn drop(&mut self) {
+        if !self.active {
+            return;
+        }
+        let request = LifecycleLockRequest {
+            workspace: &self.workspace,
+            operation: "agent-reservation-rollback",
+            team: Some(self.team_key.as_str()),
+            agent_id: Some(&self.agent_id),
+        };
+        let Ok(_lock) = acquire_agent_lifecycle_lock(request) else {
+            let _ = crate::event_log::EventLog::new(&self.workspace).write(
+                "lifecycle.clone_reservation_rollback_failed",
+                serde_json::json!({
+                    "agent_id": self.agent_id.as_str(),
+                    "reservation_owner": self.owner,
+                    "reason": "lifecycle lock unavailable",
+                }),
+            );
+            return;
+        };
+        let result =
+            release_agent_reservation(&self.workspace, &self.team_key, &self.agent_id, &self.owner);
+        let _ = crate::event_log::EventLog::new(&self.workspace).write(
+            if result.is_ok() {
+                "lifecycle.clone_reservation_rolled_back"
+            } else {
+                "lifecycle.clone_reservation_rollback_failed"
+            },
+            serde_json::json!({
+                "agent_id": self.agent_id.as_str(),
+                "reservation_owner": self.owner,
+                "result": result.as_ref().err().map(ToString::to_string),
+            }),
+        );
+    }
+}
+
+fn reserve_agent_slot(
+    workspace: &Path,
+    team: Option<&str>,
+    agent_id: &AgentId,
+) -> Result<AgentReservation, LifecycleError> {
+    let state = crate::state::projection::select_runtime_state(workspace, team)
+        .map_err(|error| LifecycleError::TeamSelect(error.to_string()))?;
+    let team_key = team
+        .filter(|key| !key.is_empty())
+        .map(str::to_string)
+        .or_else(|| explicit_active_team_key(&state))
+        .unwrap_or_else(|| crate::state::projection::team_state_key(&state));
+    let owner = format!(
+        "{}-{}",
+        std::process::id(),
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map_err(|error| LifecycleError::StatePersist(error.to_string()))?
+            .as_nanos()
+    );
+    let mut latest = crate::state::projection::select_runtime_state(workspace, Some(&team_key))
+        .map_err(|error| LifecycleError::TeamSelect(error.to_string()))?;
+    ensure_owner_allowed_for_state(&latest, Some(agent_id))?;
+    if runtime_agent_exists(&latest, agent_id) {
+        return Err(LifecycleError::RequirementUnmet(format!(
+            "agent id already exists: {agent_id}"
+        )));
+    }
+    latest
+        .as_object_mut()
+        .ok_or_else(|| LifecycleError::StatePersist("runtime state root is not an object".into()))?
+        .entry("agents")
+        .or_insert_with(|| serde_json::json!({}));
+    let agents = latest
+        .get_mut("agents")
+        .and_then(serde_json::Value::as_object_mut)
+        .ok_or_else(|| {
+            LifecycleError::StatePersist("runtime state agents is not an object".into())
+        })?;
+    agents.insert(
+        agent_id.as_str().to_string(),
+        serde_json::json!({
+            "agent_id": agent_id.as_str(),
+            "status": "reserved",
+            "reservation_owner": owner,
+        }),
+    );
+    save_launched_team_state_for_key(
+        workspace,
+        &latest,
+        Some(team_key.as_str()),
+        Some(agent_id.as_str()),
+    )?;
+    let _ = crate::event_log::EventLog::new(workspace).write(
+        "lifecycle.clone_reservation_acquired",
+        serde_json::json!({
+            "agent_id": agent_id.as_str(),
+            "reservation_owner": owner,
+            "team": team_key,
+        }),
+    );
+    Ok(AgentReservation {
+        workspace: workspace.to_path_buf(),
+        team_key,
+        agent_id: agent_id.clone(),
+        owner,
+        active: true,
+    })
+}
+
+fn release_agent_reservation(
+    workspace: &Path,
+    team_key: &str,
+    agent_id: &AgentId,
+    owner: &str,
+) -> Result<(), LifecycleError> {
+    let mut state = crate::state::projection::select_runtime_state(workspace, Some(team_key))
+        .map_err(|error| LifecycleError::TeamSelect(error.to_string()))?;
+    let matches = state
+        .get("agents")
+        .and_then(|agents| agents.get(agent_id.as_str()))
+        .and_then(|agent| agent.get("reservation_owner"))
+        .and_then(serde_json::Value::as_str)
+        == Some(owner);
+    if !matches {
+        return Ok(());
+    }
+    state
+        .get_mut("agents")
+        .and_then(serde_json::Value::as_object_mut)
+        .ok_or_else(|| {
+            LifecycleError::StatePersist("runtime state agents is not an object".into())
+        })?
+        .remove(agent_id.as_str());
+    save_launched_team_state_for_key(workspace, &state, Some(team_key), Some(agent_id.as_str()))
+}
+
+/// ---
+/// purpose: 加一席的默认入口，解析活跃 team、拿生命周期锁、路由到该 team 实际使用的 tmux socket
+/// params:
+///   role_file_path: 外部角色文档路径，就地读取不拷贝
+///   open_display: 是否为新席开显示
+/// returns: 新席的环境与启动模式
+/// errors: 选不到 team 返回 TeamSelect，角色文件缺失或编译失败返回 Compile，重名返回 RequirementUnmet
+/// contract_id: lifecycle.add_agent.entry
+/// ---
 /// `add_agent(workspace, agent_id, role_file_path, open_display, team)`
 /// (`lifecycle/operations.py:143`)。动态 role doc 编译进 spec + 起 worker;失败**字节级回滚**
 /// spec_yaml / workspace_state / **team_state.md** / role_file(Gap 15.11),每步发
@@ -55,12 +240,18 @@ pub fn add_agent(
         }
         Err(error) => return Err(LifecycleError::TeamSelect(error.to_string())),
     };
-    let _lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
+    let lifecycle_lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
         workspace: &selected.run_workspace,
         operation: "add-agent",
         team: Some(selected.team_key.as_str()),
         agent_id: Some(agent_id),
     })?;
+    let reservation = reserve_agent_slot(
+        &selected.run_workspace,
+        Some(selected.team_key.as_str()),
+        agent_id,
+    )?;
+    drop(lifecycle_lock);
     // E5 §3:compile_team 要角色定义目录(team_dir),不是 spec 落点(spec_workspace=runtime)。
     let team_dir = selected.team_dir;
     // **0.3.24 add-agent socket drift fix**: route to the live team's persisted
@@ -74,7 +265,7 @@ pub fn add_agent(
         Some(selected.team_key.as_str()),
     )
     .unwrap_or_else(|_| crate::tmux_backend::TmuxBackend::for_workspace(&selected.run_workspace));
-    add_agent_with_transport_at_paths(
+    add_agent_with_transport_at_paths_reserved(
         &selected.run_workspace,
         &team_dir,
         agent_id,
@@ -82,9 +273,19 @@ pub fn add_agent(
         open_display,
         Some(selected.team_key.as_str()),
         &transport,
+        Some(reservation),
+        false,
     )
 }
 
+/// ---
+/// purpose: 强制重建一席，先快照旧席再摘除再加回
+/// params:
+///   force: 为假时直接退回普通 add_agent
+/// returns: 新席的环境与启动模式
+/// errors: 任一步失败都按快照恢复，恢复本身再出错时错误里附 rollback_errors
+/// contract_id: lifecycle.add_agent.force_entry
+/// ---
 /// Reconcile a single existing/inconsistent seat, then reuse the normal add
 /// path. The external role source is preserved by remove-agent ownership
 /// checks, so this is a one-command force-recreate rather than a team restart.
@@ -128,6 +329,12 @@ pub fn add_agent_force(
     )
 }
 
+/// ---
+/// purpose: 带注入 transport 的加席入口，归一 workspace 并拿锁后转实体实现
+/// returns: 新席的环境与启动模式
+/// errors: 归一 workspace 失败返回 StatePersist，其余透传
+/// contract_id: lifecycle.add_agent.entry
+/// ---
 /// `add_agent` with an injected transport — after the recompile+write, wires the new worker spawn
 /// (via start_agent_with_transport) + start_coordinator (rt-host-a sweep: recompiled but never spawned).
 pub(crate) fn add_agent_with_transport(
@@ -140,13 +347,15 @@ pub(crate) fn add_agent_with_transport(
 ) -> Result<AddAgentReport, LifecycleError> {
     let run_workspace = crate::model::paths::canonical_run_workspace(workspace)
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
-    let _lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
+    let lifecycle_lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
         workspace: &run_workspace,
         operation: "add-agent",
         team,
         agent_id: Some(agent_id),
     })?;
-    add_agent_with_transport_at_paths(
+    let reservation = reserve_agent_slot(&run_workspace, team, agent_id)?;
+    drop(lifecycle_lock);
+    add_agent_with_transport_at_paths_reserved(
         &run_workspace,
         workspace,
         agent_id,
@@ -154,9 +363,19 @@ pub(crate) fn add_agent_with_transport(
         open_display,
         team,
         transport,
+        Some(reservation),
+        false,
     )
 }
 
+/// ---
+/// purpose: 带注入 transport 的强制重建入口
+/// params:
+///   force: 为假时退回普通 add_agent_with_transport
+/// returns: 新席的环境与启动模式
+/// errors: 归一 workspace 失败返回 StatePersist，其余透传
+/// contract_id: lifecycle.add_agent.force_entry
+/// ---
 pub(crate) fn add_agent_with_transport_force(
     workspace: &Path,
     agent_id: &AgentId,
@@ -195,6 +414,11 @@ pub(crate) fn add_agent_with_transport_force(
     )
 }
 
+/// ---
+/// purpose: 已持锁状态下的强制重建，先校验替换源可用再消费旧席
+/// returns: 新席报告；成功后还要过快照的一致性校验
+/// errors: 角色文件不存在先行返回 Compile；摘除、加回或一致性校验失败时按快照恢复并返回错误
+/// ---
 pub(super) fn force_recreate_with_transport_locked(
     run_workspace: &Path,
     team_dir: &Path,
@@ -230,7 +454,7 @@ pub(super) fn force_recreate_with_transport_locked(
         let restore_errors = snapshot.restore(team, transport);
         return force_recreate_rollback_error(agent_id, error, restore_errors);
     }
-    let operation = add_agent_with_transport_at_paths(
+    let operation = add_agent_with_transport_at_paths_locked(
         run_workspace,
         team_dir,
         agent_id,
@@ -256,6 +480,10 @@ pub(super) fn force_recreate_with_transport_locked(
     }
 }
 
+/// ---
+/// purpose: 把原始错误与回滚过程中的错误合成一个对外错误
+/// returns: 回滚干净时原样返回原始错误；否则包成 StatePersist 并附 rollback_errors
+/// ---
 pub(super) fn force_recreate_rollback_error<T>(
     agent_id: &AgentId,
     error: LifecycleError,
@@ -271,6 +499,11 @@ pub(super) fn force_recreate_rollback_error<T>(
     }
 }
 
+/// ---
+/// purpose: 测试用注入点，按环境变量在 spawn 之后制造一次失败
+/// returns: 环境变量未设或为空时直接成功
+/// errors: 设了非空值时返回 StatePersist
+/// ---
 pub(super) fn maybe_fail_force_recreate_after_spawn() -> Result<(), LifecycleError> {
     let Ok(reason) = std::env::var("TEAM_AGENT_TEST_FAIL_FORCE_RECREATE_AFTER_SPAWN") else {
         return Ok(());
@@ -283,6 +516,14 @@ pub(super) fn maybe_fail_force_recreate_after_spawn() -> Result<(), LifecycleErr
     )))
 }
 
+/// ---
+/// purpose: 加席的实体实现，含 owner 门、重名拒绝、重编译 spec 原子写、席位 state upsert 与起席
+/// params:
+///   run_workspace: 已归一的 run workspace
+///   team_dir: 角色定义所在目录，编译 team 用它
+/// returns: 新席的环境与启动模式
+/// errors: owner 门不过或重名返回 RequirementUnmet，角色文件缺失或编译不一致返回 Compile，state 与 spawn 失败先回滚再透传原错
+/// ---
 pub(super) fn add_agent_with_transport_at_paths(
     run_workspace: &Path,
     team_dir: &Path,
@@ -291,6 +532,54 @@ pub(super) fn add_agent_with_transport_at_paths(
     open_display: bool,
     team: Option<&str>,
     transport: &dyn Transport,
+) -> Result<AddAgentReport, LifecycleError> {
+    add_agent_with_transport_at_paths_reserved(
+        run_workspace,
+        team_dir,
+        agent_id,
+        role_file_path,
+        open_display,
+        team,
+        transport,
+        None,
+        false,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+fn add_agent_with_transport_at_paths_locked(
+    run_workspace: &Path,
+    team_dir: &Path,
+    agent_id: &AgentId,
+    role_file_path: &Path,
+    open_display: bool,
+    team: Option<&str>,
+    transport: &dyn Transport,
+) -> Result<AddAgentReport, LifecycleError> {
+    add_agent_with_transport_at_paths_reserved(
+        run_workspace,
+        team_dir,
+        agent_id,
+        role_file_path,
+        open_display,
+        team,
+        transport,
+        None,
+        true,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+fn add_agent_with_transport_at_paths_reserved(
+    run_workspace: &Path,
+    team_dir: &Path,
+    agent_id: &AgentId,
+    role_file_path: &Path,
+    open_display: bool,
+    team: Option<&str>,
+    transport: &dyn Transport,
+    reservation: Option<AgentReservation>,
+    lifecycle_lock_held: bool,
 ) -> Result<AddAgentReport, LifecycleError> {
     let runtime_state = crate::state::persist::load_runtime_state(run_workspace)
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
@@ -309,7 +598,15 @@ pub(super) fn add_agent_with_transport_at_paths(
             role_file_path.display()
         )));
     }
-    if runtime_agent_exists(&owner_state, agent_id) {
+    let reservation_owned = reservation.as_ref().is_some_and(|reservation| {
+        owner_state
+            .get("agents")
+            .and_then(|agents| agents.get(agent_id.as_str()))
+            .and_then(|agent| agent.get("reservation_owner"))
+            .and_then(serde_json::Value::as_str)
+            == Some(reservation.owner.as_str())
+    });
+    if runtime_agent_exists(&owner_state, agent_id) && !reservation_owned {
         return Err(LifecycleError::RequirementUnmet(format!(
             "agent id already exists: {agent_id}"
         )));
@@ -336,21 +633,40 @@ pub(super) fn add_agent_with_transport_at_paths(
             compiled.id, agent_id
         )));
     }
-    inject_agent_into_spec(&mut spec, compiled.agent, &compiled.id)?;
-    let safety = effective_runtime_config(&spec)?;
+    let compiled_agent = compiled.agent.clone();
+    inject_agent_into_spec(&mut spec, compiled_agent.clone(), &compiled.id)?;
     // E5 spec 迁移:重编译的 spec 原子写到 .team/runtime/<team_key>/(不落用户目录 team_dir)。
     let spec_path = crate::model::paths::runtime_spec_path(run_workspace, &canonical_team_key);
     // E42 (0.3.24 P0): capture pre-write bytes for atomic rollback. If anything
     // downstream of write_spec_atomic + upsert_agent_state_from_role + spawn
     // fails, restore the prior bytes so the canonical spec / runtime state never
     // get a half-written row that disagrees with what remove-agent can see.
+    let reservation_lock = if lifecycle_lock_held {
+        None
+    } else {
+        Some(acquire_agent_lifecycle_lock(LifecycleLockRequest {
+            workspace: run_workspace,
+            operation: "add-agent",
+            team,
+            agent_id: Some(agent_id),
+        })?)
+    };
     let pre_spec_text = match std::fs::read_to_string(&spec_path) {
         Ok(text) => Some(text),
         Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
         Err(e) => return Err(LifecycleError::StatePersist(format!("read spec: {e}"))),
     };
-    let pre_runtime_state = crate::state::persist::load_runtime_state(run_workspace).ok();
-    write_spec_atomic(&spec_path, &spec)?;
+    // Merge against the latest runtime spec while holding only the short
+    // filesystem critical section. Role compilation happened before this lock;
+    // peer reservations therefore remain visible instead of being overwritten
+    // by a stale base-spec snapshot.
+    let mut latest_spec = pre_spec_text
+        .as_deref()
+        .and_then(|text| crate::model::yaml::loads(text).ok())
+        .unwrap_or(spec);
+    inject_agent_into_spec(&mut latest_spec, compiled_agent, &compiled.id)?;
+    write_spec_atomic(&spec_path, &latest_spec)?;
+    drop(reservation_lock);
     let (meta, _) = crate::compiler::read_front_matter(role_file_path)
         .map_err(|e| LifecycleError::Compile(e.to_string()))?;
     // upsert writes status="starting" (E42) — start_agent_at_paths::mark_agent_started
@@ -362,13 +678,12 @@ pub(super) fn add_agent_with_transport_at_paths(
         agent_id,
         &meta,
         role_file_path,
-        &safety,
     ) {
         rollback_add_agent_atomic(
             run_workspace,
             &spec_path,
             pre_spec_text.as_deref(),
-            pre_runtime_state.as_ref(),
+            None,
             agent_id,
             "state_upsert_failed",
         );
@@ -390,7 +705,7 @@ pub(super) fn add_agent_with_transport_at_paths(
                 run_workspace,
                 &spec_path,
                 pre_spec_text.as_deref(),
-                pre_runtime_state.as_ref(),
+                None,
                 agent_id,
                 "start_agent_failed",
             );
@@ -407,7 +722,7 @@ pub(super) fn add_agent_with_transport_at_paths(
                 run_workspace,
                 &spec_path,
                 pre_spec_text.as_deref(),
-                pre_runtime_state.as_ref(),
+                None,
                 agent_id,
                 "added_agent_paused",
             );
@@ -416,6 +731,9 @@ pub(super) fn add_agent_with_transport_at_paths(
             )));
         }
     };
+    if let Some(reservation) = reservation {
+        reservation.commit();
+    }
     Ok(AddAgentReport {
         env,
         start_mode,

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

@@ -1,3 +1,26 @@
+//! ---
+//! purpose: 加席过程中的 state 写入、spec 注入与失败回滚
+//! contract:
+//!   provides:
+//!     - name: rollback_add_agent_atomic
+//!       what: 尽力恢复 spec 字节与 runtime state，并写一条回滚事件
+//!     - name: upsert_agent_state_from_role
+//!       what: 由角色文档 front matter 写出该席位的 state 行
+//!     - name: inject_agent_into_spec
+//!       what: 把编译出的 agent 注入 spec 的 agents 与 routing 规则
+//!     - name: runtime_agent_exists
+//!       what: 判断 state 里是否已有同 id 席位
+//!   depends:
+//!     - crate::state::repository
+//!     - crate::state::persist
+//!     - crate::lifecycle::restart::remove
+//!     - crate::event_log::EventLog
+//! boundary:
+//!   - 回滚是尽力而为，回滚自身的错误被吞掉，只在事件里如实记录成败
+//!   - 注入 spec 不落盘，落盘由调用方原子写
+//!   - 已存在同 id 的条目不重复注入
+//! maturity: wired
+//! ---
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 use std::process::Command;
@@ -14,6 +37,14 @@ use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest}
 
 use super::*;
 
+/// ---
+/// purpose: 加席失败后恢复 spec 与 runtime state，并给新席立墓碑防止被合并回来
+/// params:
+///   pre_spec_text: 写之前的 spec 字节；None 表示原本没有该文件，回滚即删除
+///   pre_runtime_state: 写之前的 runtime state；None 时改为从当前 state 里摘掉该席位
+///   reason: 写进回滚事件的原因串
+/// returns: 无返回值；回滚成败如实写进 add_agent.rollback 事件
+/// ---
 /// E42 (0.3.24 P0, double-spec deadlock): best-effort atomic rollback for a
 /// failed add-agent. Restores the canonical spec to its pre-write bytes (or
 /// removes the file if it didn't exist), and restores runtime state to its
@@ -110,13 +141,20 @@ pub(super) fn rollback_add_agent_atomic(
     );
 }
 
+/// ---
+/// purpose: 由角色文档的 front matter 写出该席位的 state 行并落盘
+/// params:
+///   meta: 角色文档 front matter
+///   dynamic_role_file: 角色文件路径，记进 state 供 restart 重建 spec 用
+/// returns: 成功返回空值，席位状态记为 starting
+/// errors: 读或写 runtime state 失败时返回 StatePersist
+/// ---
 pub(super) fn upsert_agent_state_from_role(
     workspace: &Path,
     canonical_team_key: &str,
     agent_id: &AgentId,
     meta: &Value,
     dynamic_role_file: &Path,
-    safety: &DangerousApproval,
 ) -> Result<(), LifecycleError> {
     let mut state =
         crate::state::projection::select_runtime_state(workspace, Some(canonical_team_key))
@@ -195,7 +233,13 @@ pub(super) fn upsert_agent_state_from_role(
         }
     }
     if let Some(obj) = entry.as_object_mut() {
-        persist_effective_approval_policy(obj, safety);
+        // 0.5.66 bypass 单源:policy 从 role 文档字段派生,不再用全队 `DangerousApproval`。
+        let meta_provider = meta
+            .get("provider")
+            .and_then(Value::as_str)
+            .and_then(crate::provider::wire::parse_provider)
+            .unwrap_or(Provider::Codex);
+        persist_effective_approval_policy_from_yaml_agent(obj, meta, meta_provider);
     }
     agent_map.insert(agent_id.as_str().to_string(), entry);
     crate::lifecycle::restart::remove::clear_agent_retirement_in_state(&mut state, agent_id);
@@ -207,6 +251,10 @@ pub(super) fn upsert_agent_state_from_role(
     )
 }
 
+/// ---
+/// purpose: 判断角色文件是框架托管的还是外部的
+/// returns: 路径落在托管目录下为 managed，否则为 external
+/// ---
 pub(super) fn role_source_ownership(workspace: &Path, role_file: &Path) -> &'static str {
     let managed_root = workspace.join(".team").join("dynamic-role-files");
     match (
@@ -218,6 +266,13 @@ pub(super) fn role_source_ownership(workspace: &Path, role_file: &Path) -> &'sta
     }
 }
 
+/// ---
+/// purpose: 把编译出的 agent 注入 spec 的 agents 列表并补一条同形路由规则
+/// params:
+///   spec: 就地改写；已有同 id 的 agent 或同目标的路由规则时不重复追加
+/// returns: 成功返回空值，不落盘
+/// errors: spec 不是 map 或 agents 缺失时返回 Compile
+/// ---
 /// E5 Bug1:把 add-agent 就地编译出的 agent 条目注入 base team spec(`agents` 列表 +
 /// `routing.rules` 加 `route-<id>`),复刻 [`compile_team`] 的路由规则形态。不落任何文件。
 ///
@@ -274,6 +329,10 @@ pub(crate) fn inject_agent_into_spec(
     Ok(())
 }
 
+/// ---
+/// purpose: 判断 state 的 agents 表里是否已有该 id
+/// returns: 存在则 true
+/// ---
 pub(super) fn runtime_agent_exists(state: &serde_json::Value, agent_id: &AgentId) -> bool {
     state
         .get("agents")
@@ -281,6 +340,10 @@ pub(super) fn runtime_agent_exists(state: &serde_json::Value, agent_id: &AgentId
         .is_some_and(|agents| agents.contains_key(agent_id.as_str()))
 }
 
+/// ---
+/// purpose: 取 YAML agent 节点的 id
+/// returns: id 是字符串时返回它，否则 None
+/// ---
 pub(super) fn yaml_agent_id(agent: &Value) -> Option<&str> {
     let Value::Map(pairs) = agent else {
         return None;
@@ -294,6 +357,10 @@ pub(super) fn yaml_agent_id(agent: &Value) -> Option<&str> {
         })
 }
 
+/// ---
+/// purpose: 取 YAML 路由规则的 assign_to
+/// returns: 该字段是字符串时返回它，否则 None
+/// ---
 pub(super) fn yaml_route_assigns_to(rule: &Value) -> Option<&str> {
     let Value::Map(pairs) = rule else {
         return None;