@team-agent/installer 0.5.66 → 0.5.68

package/crates/team-agent/src/compiler.rs

@@ -390,6 +390,8 @@ fn compile_role_agent_with_mode(
     let id = required_string(&meta, role_path, "name")?;
     let role = required_string(&meta, role_path, "role")?;
     let provider = required_string(&meta, role_path, "provider")?;
+    require_explicit_grok_role_model(&meta, role_path, &provider)?;
+    require_explicit_cursor_role_model(&meta, role_path, &provider)?;
     let model = resolve_model(&meta, team_meta, &provider);
     let auth_mode = string_field(&meta, "auth_mode")
         .or_else(|| string_field(team_meta, "default_auth_mode"))
@@ -483,6 +485,15 @@ fn compile_role_agent_with_mode(
                 effort.as_str()
             )));
         }
+        if provider_enum == Provider::CursorAgent {
+            return Err(ModelError::Validation(format!(
+                "{}: cursor_agent does not support effort '{}'. \
+The Cursor CLI has no `--effort` flag; the framework must not drop the field and still launch. \
+Remove effort from the role file (do not map it into `--model[effort=]` until that form is measured).",
+                role_path.display(),
+                effort.as_str()
+            )));
+        }
         agent_items.push(("effort", Value::Str(effort.as_str().to_string())));
     }
     Ok(CompiledRole {
@@ -550,6 +561,54 @@ fn required_string(meta: &Value, path: &Path, key: &str) -> Result<String, Model
     })
 }
 
+/// 缺 model 时框架会填内建默认（grok 上是 grok-4），席位因此静默拿到
+/// 与角色文件无关的模型和上下文窗口，而 argv 看起来完全正常。
+/// 角色文件必须自己写死；内建默认、team 级默认、CLI 全局默认都是隐式来源。
+fn require_explicit_grok_role_model(
+    meta: &Value,
+    path: &Path,
+    provider: &str,
+) -> Result<(), ModelError> {
+    if parse_canonical_provider(provider) != Some(Provider::Grok) {
+        return Ok(());
+    }
+    if string_field(meta, "model").is_some_and(|value| !value.trim().is_empty()) {
+        return Ok(());
+    }
+    Err(ModelError::Validation(format!(
+        "{}: missing front matter field model. \
+Without an explicit model the framework fills a built-in default (grok-4 for grok), \
+so the seat silently gets a model and context window that are not in the role file, \
+while argv still looks normal. The role file must name the model itself; \
+built-in defaults, team-level defaults, and the Grok CLI global default are all implicit sources. Example:\n\
+model: grok-4.6",
+        path.display()
+    )))
+}
+
+/// 缺 model 时框架曾填 builtin `sonnet-4-thinking`，本机 shim 还会剥掉该默认。
+/// 角色必须自己写死；内建默认、team 级默认、CLI 全局默认都是隐式来源。
+fn require_explicit_cursor_role_model(
+    meta: &Value,
+    path: &Path,
+    provider: &str,
+) -> Result<(), ModelError> {
+    if parse_canonical_provider(provider) != Some(Provider::CursorAgent) {
+        return Ok(());
+    }
+    if string_field(meta, "model").is_some_and(|value| !value.trim().is_empty()) {
+        return Ok(());
+    }
+    Err(ModelError::Validation(format!(
+        "{}: missing front matter field model. \
+Without an explicit model the framework fills a built-in default (sonnet-4-thinking for cursor_agent), \
+so the seat silently gets a model that is not in the role file, while argv still looks normal. \
+The role file must name the model itself; built-in defaults, team-level defaults, and the Cursor CLI default are all implicit sources. Example:\n\
+model: sonnet-4-thinking",
+        path.display()
+    )))
+}
+
 /// 0.5.66 bypass 单源:角色 md 的 `dangerously_skip_permissions` 必填 bool。
 /// 缺 = 编译失败(消息含硬串);非 bool = 同 fail-loud。
 fn required_dangerously_skip_permissions(

package/crates/team-agent/src/coordinator/backoff.rs

@@ -1,3 +1,29 @@
+//! ---
+//! purpose: coordinator daemon 进程的宿主——装配 transport/registry，跑主循环，把 tick 的崩溃收进退避与事件
+//! contract:
+//!   provides:
+//!     - name: run_daemon
+//!       what: `team-agent coordinator --workspace ..` 子进程入口：解析 transport、构造 Coordinator、进主循环
+//!     - name: backoff_sleep_sec
+//!       what: 连续失败次数到睡眠秒数的纯函数（5→10→20→40→60→60，封顶 BACKOFF_MAX_SEC）
+//!     - name: resolve_tick_interval
+//!       what: 解析 tick 间隔并顺带确保 message store schema 可打开
+//!   depends:
+//!     - super::health
+//!     - super::tick
+//!     - super::types
+//!     - super::conpty_shim
+//!     - crate::state::persist
+//!     - crate::transport_factory
+//!     - crate::tmux_backend
+//!     - crate::message_store
+//!     - crate::event_log
+//! boundary:
+//!   - 不做单次 tick 的编排内容，tick 体在 tick.rs
+//!   - 不决定健康与否，只消费 health.rs 的判定与路径
+//!   - transport 解析失败时降级为 tmux workspace 后端保活，但不静默——降级原因写进 boot metadata
+//! maturity: wired
+//! ---
 //!
 //! daemon 主循环面(`__main__.py`)—— 退避序列 + tick 间隔解析 + 子进程入口。
 
@@ -41,6 +67,13 @@ pub struct DaemonArgs {
 /// daemon 主循环(`main`,`__main__.py:25-98`)。写 pid/meta(source=boot)、装信号→STOP、孤儿自检、
 /// catch-all + 指数退避 + tick_error 去重/抑制、tick_recovered 重置、`result.stop || once` → break。
 /// §10:返 `Result`(顶层 bin 用 anyhow 收;§12 边界)。
+/// ---
+/// purpose: daemon 进程入口——解析 transport 后端、构造 Coordinator、跑主循环直到 stop 或 --once
+/// params:
+///   args: workspace（已 resolve）、once、tick_interval_sec、可选 team_key；team_key 为空时回落到 state.active_team_key
+/// returns: 主循环正常退出（收到 STOP、tick 报 stop、或 --once 跑完一轮）时为 Ok
+/// errors: 写 pid/metadata、事件日志或 tick 间隔解析失败时返回 DaemonError
+/// ---
 pub fn run_daemon(args: DaemonArgs) -> Result<(), DaemonError> {
     // CP-1: the daemon's whole tick surface (has_session / capture / inject / list_windows / kill)
     // runs through this backend. Prefer the persisted runtime endpoint so attached explicit-socket
@@ -123,6 +156,14 @@ pub fn run_daemon(args: DaemonArgs) -> Result<(), DaemonError> {
     run_daemon_with_coordinator_and_boot_tmux(&args, &coordinator, Some(tmux_metadata))
 }
 
+/// ---
+/// purpose: 用调用方已装配好的 Coordinator 跑主循环（测试与内部复用入口，跳过 transport 解析）
+/// params:
+///   args: 与 run_daemon 同一份参数
+///   coordinator: 已注入 provider registry 与 transport 的实例
+/// returns: 与 run_daemon 相同的主循环退出语义
+/// errors: 同 run_daemon
+/// ---
 pub(crate) fn run_daemon_with_coordinator(
     args: &DaemonArgs,
     coordinator: &Coordinator,
@@ -520,6 +561,13 @@ fn current_ppid() -> u32 {
 
 /// 计算 tick 间隔(`_tick_interval`,`__main__.py:104-115`)。读 spec `runtime.tick_interval_sec`,
 /// 缺失/出错 → `DEFAULT_TICK_INTERVAL_SEC`;并确保 schema 存在(`MessageStore(workspace)`)。
+/// ---
+/// purpose: 取本 workspace 的 tick 间隔秒数，并顺带确保 message store schema 可打开
+/// params:
+///   workspace: 已 resolve 的 workspace 根
+/// returns: tick 间隔秒数；当前实现恒为 DEFAULT_TICK_INTERVAL_SEC（spec 覆盖尚未接线）
+/// errors: MessageStore::open 失败时返回 TickError
+/// ---
 pub(super) fn resolve_tick_interval(workspace: &WorkspacePath) -> Result<f64, TickError> {
     let _ = MessageStore::open(workspace.as_path())?;
     Ok(DEFAULT_TICK_INTERVAL_SEC)
@@ -527,6 +575,13 @@ pub(super) fn resolve_tick_interval(workspace: &WorkspacePath) -> Result<f64, Ti
 
 /// 退避序列(`__main__.py:65`):`min(interval * 2^min(failures-1, 5), 60.0)` → 5→10→20→40→60→60s。
 /// unit test 锁死本序列(card §85)。**纯函数,无 I/O,可直接 impl 钉死**(但 ROUND-0 仍占位)。
+/// ---
+/// purpose: 由连续失败次数算出本轮该睡多少秒的纯函数
+/// params:
+///   interval: 基准 tick 间隔秒数
+///   consecutive_failures: 至今连续失败次数；0 与 1 同视为首次失败
+/// returns: interval * 2^min(failures-1, 5)，上限 BACKOFF_MAX_SEC
+/// ---
 pub(super) fn backoff_sleep_sec(interval: f64, consecutive_failures: u32) -> f64 {
     let failures = consecutive_failures.saturating_sub(1).min(5);
     let exp = i32::try_from(failures).unwrap_or(5);

package/crates/team-agent/src/coordinator/conpty_shim.rs

@@ -1,3 +1,30 @@
+//! ---
+//! purpose: Windows ConPTY shim 的生命周期主人——定位并启动 windows-shim.exe、做 Hello 握手、把可复用的连接与 pid/pipe 名记进 state
+//! contract:
+//!   provides:
+//!     - name: ensure_shim_running
+//!       what: 幂等入口：state 里记的 shim 还活着就重连，否则新起一个并握手
+//!     - name: reconnect_recorded_shim
+//!       what: 只按 state 记的 pipe 名重连并重做 Hello，绝不新起进程
+//!     - name: recorded_shim_pid
+//!       what: 读 state.transport.shim.pid，供停机路由
+//!     - name: recorded_shim_pipe_name
+//!       what: 读 state.transport.shim.pipe_name，供重连路由
+//!     - name: mark_transport_unavailable
+//!       what: shim 不可达时发 stale 家族事件并清掉 state 里的 pipe_ready
+//!   depends:
+//!     - conpty_transport
+//!     - crate::state::repository
+//!     - crate::state::persist
+//!     - crate::event_log
+//!     - crate::platform::process
+//! boundary:
+//!   - pipe_token 绝不落 state：只经子进程环境变量传递并留在本进程内存里，state 只记 pid/pipe_name/pipe_ready
+//!   - 终态失败不静默回落 tmux，交由调用方按传输不可用处理
+//!   - 重连只证明线协议可用，不做新的令牌认证
+//!   - 整个文件仅在 Windows 编译；非 Windows 调用方必须自己 cfg 门控
+//! maturity: wired
+//! ---
 //!
 //! Windows ConPTY shim lifecycle manager.
 //!
@@ -75,16 +102,28 @@ pub struct ShimHandle {
 impl ShimHandle {
     /// The connected pipe client, ready for the factory to wire into
     /// `ConPtyBackend`. Callable exactly once — takes ownership.
+    /// ---
+    /// purpose: 取走已完成 Hello 握手的管道客户端，交给传输后端接线
+    /// returns: 首次调用返回客户端并转移所有权；再次调用为 None
+    /// ---
     pub fn take_client(&mut self) -> Option<NamedPipeClient> {
         self.client.take()
     }
 
     /// The shim pid (for status + shutdown routing).
+    /// ---
+    /// purpose: 给出 shim 进程号，用于状态展示与停机路由
+    /// returns: 启动时记下的 pid；子进程句柄已被 detach 或 drop 后该值仍可读
+    /// ---
     pub fn pid(&self) -> u32 {
         self.pid
     }
 
     /// The pipe name the shim listens on.
+    /// ---
+    /// purpose: 给出 shim 正在监听的命名管道名
+    /// returns: 形如 team-agent-conpty-<hash>-<team> 的管道全名
+    /// ---
     pub fn pipe_name(&self) -> &str {
         &self.pipe_name
     }
@@ -95,6 +134,11 @@ impl ShimHandle {
     /// an explicit `platform::process::terminate_pid` via
     /// `recorded_shim_pid`. Without this call, going out of scope
     /// would terminate the shim and orphan every worker.
+    /// ---
+    /// purpose: 放弃对 shim 子进程的所有权，使本句柄析构时不再杀它
+    /// returns: shim 的 pid，供调用方日后按精确 pid 显式终止
+    /// ---
+    /// 不调用它就让句柄离开作用域，会连带杀掉 shim 并使全部 worker 变成孤儿。
     pub fn detach(mut self) -> u32 {
         // Forget the child so its own Drop doesn't run either. The
         // shim survives until an explicit kill.
@@ -453,6 +497,12 @@ fn finalize(
 /// `None` when no shim is currently registered (Unix / never-launched
 /// Windows worker). Callers use `platform::process::terminate_pid`
 /// on the returned pid.
+/// ---
+/// purpose: 从 state 读出已登记的 shim 进程号
+/// params:
+///   workspace: workspace 根
+/// returns: state.transport.shim.pid 存在且能转成 u32 时给值；没有登记过 shim（未起过或非 Windows 队）时为 None。只读状态，不做存活探测
+/// ---
 pub fn recorded_shim_pid(workspace: &Path) -> Option<u32> {
     let state = crate::state::repository::StateRepository::new(workspace)
         .load_workspace_if_exists_without_migrations()
@@ -466,6 +516,12 @@ pub fn recorded_shim_pid(workspace: &Path) -> Option<u32> {
 }
 
 /// Read `state.transport.shim.pipe_name` for reconnect routing.
+/// ---
+/// purpose: 从 state 读出已登记的 shim 管道名
+/// params:
+///   workspace: workspace 根
+/// returns: state.transport.shim.pipe_name 的字符串值；未登记时为 None
+/// ---
 pub fn recorded_shim_pipe_name(workspace: &Path) -> Option<String> {
     let state = crate::state::repository::StateRepository::new(workspace)
         .load_workspace_if_exists_without_migrations()
@@ -497,6 +553,15 @@ pub fn recorded_shim_pipe_name(workspace: &Path) -> Option<String> {
 /// This gives the "coord can die, shim survives" invariant: a fresh
 /// coord that finds a live shim just reconnects; a fresh coord that
 /// finds no shim spawns one.
+/// ---
+/// purpose: 保证本 (workspace, team) 有一个可用的 shim——这是 coordinator 侧唯一的 shim 所有权入口
+/// params:
+///   workspace: workspace 根
+///   team_key: 目标 team，进 Hello 请求的作用域
+///   workspace_hash: 管道名里用的 workspace 摘要
+/// returns: 已登记 pid 还活着且重连成功 → 复用原进程的句柄（不拥有子进程）；否则新起一个并握手，返回拥有子进程的句柄
+/// errors: 找不到 shim 可执行文件、spawn 失败、连接超时、Hello 失败或落盘 state 失败时返回对应 ShimError。重连失败不算错误，会直接落到新起那条路
+/// ---
 pub fn ensure_shim_running(
     workspace: &Path,
     team_key: &str,
@@ -541,6 +606,15 @@ pub fn ensure_shim_running(
 /// Handle returned from this fn has no owned child (the shim is
 /// somebody else's — usually a previous coord instance). `detach()`
 /// on the handle is a no-op for the child.
+/// ---
+/// purpose: 只重连 state 里已登记的 shim 并重做 Hello，用来证明线协议仍然可用
+/// params:
+///   workspace: workspace 根
+///   team_key: 目标 team，进 Hello 请求的作用域
+///   _workspace_hash: 未使用；管道名直接取自 state，不再重算
+/// returns: 连上且 Hello 回 ok 时给出不拥有子进程的句柄，对它调 detach 对子进程是空操作
+/// errors: state 里没有管道名或多次连接均失败 → ConnectTimeout；连上但 Hello 回 ok=false → HelloFailed。本函数绝不新起进程
+/// ---
 pub fn reconnect_recorded_shim(
     workspace: &Path,
     team_key: &str,
@@ -630,6 +704,14 @@ fn reconnect_hello(client: &mut NamedPipeClient, team_key: &str) -> Result<(), S
 /// The Windows-only `#[cfg]` gate is at the mod level (see
 /// `coordinator/mod.rs`); on Unix this file isn't compiled, so
 /// downstream callers must cfg-gate their reference themselves.
+/// ---
+/// purpose: 把「shim 不可达」这件事诚实地写出去——发 stale 家族事件，并清掉 state 里的就绪位
+/// params:
+///   workspace: workspace 根
+///   reason: 不可达原因，同时进事件与 state.transport.shim.unavailable_reason
+/// returns: 状态里本来就没有 shim 块时也返回 Ok。事件写入是尽力而为，写不出去不影响返回；清状态才是权威动作
+/// errors: 读写 state 失败时返回 StateError；state JSON 损坏时按空状态继续
+/// ---
 pub fn mark_transport_unavailable(workspace: &Path, reason: &str) -> Result<(), StateError> {
     // Best-effort event emission — a failed event write should not
     // fail the caller. The state-clearing step below is authoritative.

package/crates/team-agent/src/coordinator/health.rs

@@ -1,3 +1,43 @@
+//! ---
+//! purpose: coordinator daemon 的健康判定、幂等启停与只读观测面——pid/metadata/schema 三合一健康、spawn 与终止、runtime 路径、以及 team-agent watch 的事件渲染
+//! contract:
+//!   provides:
+//!     - name: coordinator_health
+//!       what: 由 pid 文件、coordinator.json 与 message store schema 合成 HealthReport，ok 与 service_available 分开表达
+//!     - name: start_coordinator
+//!       what: 幂等启动：已健康则 no-op，metadata 不兼容先停再起，schema 不兼容拒启并给修复 hint
+//!     - name: start_coordinator_with_team
+//!       what: 同上，并把 team_key 以 --team 传给子进程，免得 daemon 自己从 state 推
+//!     - name: stop_coordinator
+//!       what: 终止 daemon 并清 pid/meta；pid 文件缺失时用 ps 扫描发现流浪 coordinator
+//!     - name: collect_watch_lines
+//!       what: 从 events.jsonl 与结果表增量取出可渲染行，并推进 WatchCursor
+//!     - name: render_event_line
+//!       what: 把一条结构化事件渲染成人类可读行，不认识的事件返回 None
+//!     - name: run_watch
+//!       what: team-agent watch 主循环：反复 collect 后输出并 sleep
+//!     - name: coordinator_pid_path
+//!       what: coordinator.pid 的位置
+//!     - name: coordinator_meta_path
+//!       what: coordinator.json 的位置
+//!     - name: coordinator_log_path
+//!       what: coordinator.log 的位置
+//!   depends:
+//!     - super::types
+//!     - crate::message_store
+//!     - crate::db::schema
+//!     - crate::event_log
+//!     - crate::model::paths
+//!     - crate::packaging
+//!     - crate::platform::process
+//!     - crate::os_probe
+//! boundary:
+//!   - 不做 tick 编排，也不投递任何消息
+//!   - 不读 provider 凭据、不碰 .env；身份只取自当前可执行文件与已落盘 metadata
+//!   - 终止进程限定本 workspace：优先按本次判定拿到的精确 pid；pid 文件缺失时的流浪回收会按 ps 命令行匹配「coordinator --workspace <本 ws>」发现目标，仍不做跨 workspace 的 pkill/killall 泛清
+//!   - watch 侧只读：不重放已归档段，rotation 只插一条 marker 并重置 offset
+//! maturity: wired
+//! ---
 //!
 //! coordinator 健康/身份 & 只读可观测面:metadata 身份原语 + coordinator 路径 + watch 实时流。
 
@@ -27,6 +67,12 @@ use super::types::{
 // ===========================================================================
 
 /// `coordinator_health`(`lifecycle.py:38-46`):`running ∧ metadata_ok ∧ schema_ok` → typed report.
+/// ---
+/// purpose: 一次性判定本 workspace 的 coordinator daemon 是否健康
+/// params:
+///   workspace: workspace 根；pid/metadata 路径与 message store 都由它派生
+/// returns: HealthReport。ok = 进程在跑 ∧ metadata 三元全等 ∧ 二进制身份一致 ∧ schema 兼容；service_available 刻意排除二进制身份，表示「这个 daemon 还能处理本队队列」；status 区分 Missing / InvalidPid / Running / Stale
+/// ---
 pub fn coordinator_health(workspace: &WorkspacePath) -> HealthReport {
     let schema = message_store_schema_health(workspace);
     let current_binary_identity = current_coordinator_binary_identity();
@@ -73,6 +119,13 @@ pub fn coordinator_health(workspace: &WorkspacePath) -> HealthReport {
 
 /// `start_coordinator`(`lifecycle.py:49-121`):幂等 — 已健康 no-op(AlreadyRunning);metadata 不兼容
 /// 先 stop 再起;schema 不兼容拒启 + hint;否则 spawn `team-agent coordinator --workspace <ws>`。
+/// ---
+/// purpose: 不带 team_key 的幂等启动入口
+/// params:
+///   workspace: workspace 根
+/// returns: 与 start_coordinator_with_team(workspace, None) 完全一致
+/// errors: 同 start_coordinator_with_team
+/// ---
 pub fn start_coordinator(workspace: &WorkspacePath) -> Result<StartReport, StartError> {
     start_coordinator_with_team(workspace, None)
 }
@@ -85,6 +138,14 @@ pub fn start_coordinator(workspace: &WorkspacePath) -> Result<StartReport, Start
 ///
 /// Callers that CAN pass team_key (Batch 9 quick-start Windows path)
 /// SHOULD — that avoids Batch 8's F8 seed-state trap.
+/// ---
+/// purpose: 幂等启动 coordinator daemon 子进程，并把不兼容/需轮换的情形分成互不折叠的结局
+/// params:
+///   workspace: workspace 根
+///   team_key: 传给子进程的 --team；None 或空串时子进程回落到 state.active_team_key
+/// returns: StartReport。已健康 → AlreadyRunning（含「daemon 比调用方新，保留不动」这一支，rotation_reason=daemon_newer_than_caller）；schema 不兼容 → SchemaIncompatible 且 ok=false 并带修复 hint；在跑但 wire metadata 不兼容、或 metadata 指向调用方自身、或先停失败 → RestartIncompatibleStopFailed；成功 spawn → Started，因身份轮换而重起则为 StartedAfterRotation
+/// errors: 建目录、开日志、spawn、写 pid/metadata 或写事件失败时返回 StartError；「拒启」不是 Err，而是 ok=false 的报告
+/// ---
 pub fn start_coordinator_with_team(
     workspace: &WorkspacePath,
     team_key: Option<&str>,
@@ -322,6 +383,13 @@ fn detach_daemon_child(command: &mut Command) {
 fn detach_daemon_child(_command: &mut Command) {}
 
 /// `stop_coordinator`(`lifecycle.py:228-247`):SIGTERM pid + 清 pid/meta → typed report。
+/// ---
+/// purpose: 停掉本 workspace 的 coordinator daemon 并清掉 pid/meta 文件
+/// params:
+///   workspace: workspace 根
+/// returns: StopReport。pid 文件不存在时先尝试按 ps 发现流浪 coordinator，仍没有则 Missing；pid 文件内容非法 → 清文件并报 InvalidPidRemoved；终止成功 → Stopped；信号发不出去 → KillFailed
+/// errors: 删 pid/meta 文件失败时返回 StopError；本函数不写事件（EventLog 变体在此路径无产生点）
+/// ---
 pub fn stop_coordinator(workspace: &WorkspacePath) -> Result<StopReport, StopError> {
     let pid_path = coordinator_pid_path(workspace);
     if !pid_path.exists() {
@@ -498,6 +566,12 @@ fn terminate_pid(pid: Pid) -> bool {
 
 /// Public wrapper for diagnostic cleanup paths that must reuse coordinator
 /// shutdown's SIGTERM-then-SIGKILL semantics.
+/// ---
+/// purpose: 把 coordinator 停机用的「先温和后强制」终止语义暴露给诊断清理路径复用
+/// params:
+///   pid: 要终止的进程；只终止这棵进程树，不做名字匹配的批量清理
+/// returns: 超时窗口内整棵树都不再存活为 true
+/// ---
 pub fn terminate_pid_tree(pid: Pid) -> bool {
     terminate_pid(pid)
 }
@@ -607,6 +681,14 @@ fn wait_until_not_running(pid: Pid, timeout: Duration) -> bool {
 /// `ps stat=` step has no analogue). This preserves the coordinator's
 /// "am I the owner" check without silently reporting stale pids as
 /// alive.
+/// ---
+/// purpose: 判断某 pid 是不是本 coordinator 还能拥有的活进程（Unix 实现）
+/// params:
+///   pid: 待判定进程号
+/// returns: 存活且非僵尸为 true。语义与通用存活探针不同：signal 返回 EPERM 一律判 false，因为 coordinator 只认自己能发信号的进程；另用 ps 的 stat 排掉僵尸
+/// errors: 除 EPERM/ESRCH 外的 signal 错误、以及 ps 探测失败时返回 io::Error
+/// cfg: unix
+/// ---
 #[cfg(unix)]
 pub fn pid_is_running(pid: Pid) -> Result<bool, std::io::Error> {
     let Ok(pid_t) = libc::pid_t::try_from(pid.get()) else {
@@ -640,6 +722,14 @@ pub fn pid_is_running(pid: Pid) -> Result<bool, std::io::Error> {
 /// treats as `Live`; so on Windows the coordinator sees a process
 /// it can't query as still-running (safer than pretending it's gone
 /// and losing the ownership handle).
+/// ---
+/// purpose: 判断某 pid 是不是本 coordinator 还能拥有的活进程（非 Unix 实现）
+/// params:
+///   pid: 待判定进程号
+/// returns: 平台层报 Live 为 true，Dead 或 Unknown 均为 false。Windows 没有僵尸态，故不做 ps stat 那一步；平台层把拒绝访问算作 Live，于是查不动的进程仍被视为在跑
+/// errors: 平台层存活查询失败时返回 io::Error
+/// cfg: not(unix)
+/// ---
 #[cfg(not(unix))]
 pub fn pid_is_running(pid: Pid) -> Result<bool, std::io::Error> {
     match crate::platform::process::pid_liveness(pid.get())? {
@@ -650,11 +740,21 @@ pub fn pid_is_running(pid: Pid) -> Result<bool, std::io::Error> {
 }
 
 /// `read_coordinator_metadata`(`metadata.py:28-34`)。读 `coordinator.json`;损坏/缺失/非 dict → `None`。
+/// ---
+/// purpose: 读出已落盘的 coordinator.json
+/// params:
+///   workspace: workspace 根
+/// returns: 解析成功才有值；文件缺失、读不动或 JSON 形状不符一律为 None，绝不返回半份 metadata
+/// ---
 pub fn read_coordinator_metadata(workspace: &WorkspacePath) -> Option<CoordinatorMetadata> {
     let text = std::fs::read_to_string(coordinator_meta_path(workspace)).ok()?;
     serde_json::from_str(&text).ok()
 }
 
+/// ---
+/// purpose: 给出「当前这个 CLI 二进制」的身份，用于和 daemon 已记录的身份比对
+/// returns: 路径取自当前可执行文件（尽量 canonicalize）而非 PATH 查找，版本取自编译进来的包版本；路径取不到时退化成 <unknown>。测试可用 TEAM_AGENT_TEST_CALLER_BINARY_IDENTITY 覆盖，且只有两字段都非空才采信
+/// ---
 pub fn current_coordinator_binary_identity() -> CoordinatorBinaryIdentity {
     if let Ok(raw) = std::env::var("TEAM_AGENT_TEST_CALLER_BINARY_IDENTITY") {
         if let Ok(identity) = serde_json::from_str::<CoordinatorBinaryIdentity>(&raw) {
@@ -675,10 +775,24 @@ pub fn current_coordinator_binary_identity() -> CoordinatorBinaryIdentity {
 
 /// `coordinator_metadata_ok` now includes daemon binary identity in addition
 /// to the original pid/protocol/schema tuple.
+/// ---
+/// purpose: 判断已落盘 metadata 是否与当前事实完全一致
+/// params:
+///   metadata: 已读出的 coordinator.json；None 视为不一致
+///   pid: 实际观测到的 daemon pid
+/// returns: pid、协议版本、message store schema 版本、以及 daemon 二进制身份四者全对才为 true
+/// ---
 pub fn coordinator_metadata_ok(metadata: Option<&CoordinatorMetadata>, pid: Pid) -> bool {
     coordinator_metadata_mismatch_reason(metadata, pid).is_none()
 }
 
+/// ---
+/// purpose: 给出 metadata 不一致的机器可读原因，而不是只给一个布尔
+/// params:
+///   metadata: 已读出的 coordinator.json；None 时原因为 MetadataMissing
+///   pid: 实际观测到的 daemon pid
+/// returns: 第一个不匹配项对应的原因；全部一致时为 None。先判 pid/协议/schema 这组线协议字段，再判二进制身份
+/// ---
 pub fn coordinator_metadata_mismatch_reason(
     metadata: Option<&CoordinatorMetadata>,
     pid: Pid,
@@ -833,6 +947,15 @@ fn path_matches(metadata_path: &str, path: &Path) -> bool {
 
 /// `write_coordinator_metadata`(`metadata.py:46-61`)。写 `coordinator.json`(pretty indent=2),
 /// `updated_at = now(utc).isoformat()`。
+/// ---
+/// purpose: 落盘 coordinator.json，把当前 daemon 的身份三元与二进制身份记下来
+/// params:
+///   workspace: workspace 根
+///   pid: 本次要记录的 daemon pid
+///   source: 这份 metadata 是 daemon 自举时写的还是 CLI start 时写的
+/// returns: 写成功返回 ()。协议版本与 schema 版本取自当前构建常量，updated_at 是写入时刻的 UTC
+/// errors: 建目录、序列化或写文件失败时返回 io::Error
+/// ---
 pub fn write_coordinator_metadata(
     workspace: &WorkspacePath,
     pid: Pid,
@@ -856,6 +979,12 @@ pub fn write_coordinator_metadata(
     std::fs::write(path, text)
 }
 
+/// ---
+/// purpose: 用「能不能真的打开本队 message store」来判 schema 兼容门
+/// params:
+///   workspace: workspace 根
+/// returns: 打开成功则 ok=true 且 error/action 为空；失败则 ok=false，带 InitFailed 原文与修复 hint。schema_version 恒为当前构建的版本号
+/// ---
 pub(crate) fn message_store_schema_health(workspace: &WorkspacePath) -> SchemaHealth {
     match MessageStore::open(workspace.as_path()) {
         Ok(_) => SchemaHealth {
@@ -894,16 +1023,34 @@ fn remove_file_if_exists(path: &Path) -> Result<(), std::io::Error> {
 // ===========================================================================
 
 /// `coordinator.pid` 路径(`paths.py:8`)= `runtime_dir(workspace)/coordinator.pid`。
+/// ---
+/// purpose: 给出 coordinator.pid 的位置
+/// params:
+///   workspace: workspace 根
+/// returns: runtime 目录下的 coordinator.pid；只算路径，不保证文件存在
+/// ---
 pub fn coordinator_pid_path(workspace: &WorkspacePath) -> PathBuf {
     crate::model::paths::runtime_dir(workspace.as_path()).join("coordinator.pid")
 }
 
 /// `coordinator.json` 路径(`paths.py:12`)。
+/// ---
+/// purpose: 给出 coordinator.json 的位置
+/// params:
+///   workspace: workspace 根
+/// returns: runtime 目录下的 coordinator.json；只算路径，不保证文件存在
+/// ---
 pub fn coordinator_meta_path(workspace: &WorkspacePath) -> PathBuf {
     crate::model::paths::runtime_dir(workspace.as_path()).join("coordinator.json")
 }
 
 /// `coordinator.log` 路径(`paths.py:16`)。
+/// ---
+/// purpose: 给出 coordinator.log 的位置
+/// params:
+///   workspace: workspace 根
+/// returns: runtime 目录下的 coordinator.log；daemon 子进程的 stdout/stderr 都追加到这里
+/// ---
 pub fn coordinator_log_path(workspace: &WorkspacePath) -> PathBuf {
     crate::model::paths::runtime_dir(workspace.as_path()).join("coordinator.log")
 }
@@ -915,6 +1062,16 @@ pub fn coordinator_log_path(workspace: &WorkspacePath) -> PathBuf {
 /// `collect_watch_lines`(`watch.py:40`)。tail events.jsonl(过滤 team)+ latest_results,
 /// 渲染人类可读行;处理 log rotation(ROTATION_MARKER + offset 重置,不重放历史段)。
 /// 推进 `cursor`。
+/// ---
+/// purpose: 增量取出自上次游标以来的可渲染 watch 行（事件 + 结果两路）
+/// params:
+///   workspace: workspace 根
+///   cursor: 可变游标，函数会推进 offset、已见结果 id 集合与归档签名
+///   store: 已打开的 message store，用于取结果行
+///   team: 只看这个 team 的事件；None 表示不过滤
+/// returns: 本次新增的渲染行，事件行在前、结果行在后；无新内容时为空 Vec
+/// errors: 读事件文件或查库失败时返回 WatchError
+/// ---
 pub fn collect_watch_lines(
     workspace: &WorkspacePath,
     cursor: &mut WatchCursor,
@@ -1031,6 +1188,12 @@ fn collect_result_lines(
 /// `render_event_line`(`watch.py:46-63`)。把一条 step 4 事件渲染成人类可读行;非可渲染事件 → `None`。
 /// 消费的事件类型:`result_received` / `leader_receiver.{injected,submitted}` / `send.failed` /
 /// `leader_receiver.rebind_required` / `leader.api_error`(card 表)。
+/// ---
+/// purpose: 把一条结构化事件渲染成一行人类可读文本
+/// params:
+///   event: 事件 JSON 对象；靠其中的 event 字段分派
+/// returns: 已知事件类型返回渲染行，其余一律 None（不猜、不打印原始 JSON）。摘要字段做长度截断
+/// ---
 pub fn render_event_line(event: &Value) -> Option<String> {
     let event_name = event.get("event").and_then(Value::as_str)?;
     match event_name {
@@ -1087,6 +1250,16 @@ pub fn render_event_line(event: &Value) -> Option<String> {
 
 /// `run_watch`(`watch.py:25`)。`team-agent watch` 主循环:反复 `collect_watch_lines` + 输出 + sleep。
 /// `output`/`sleep` 注入便于测试。§10 返 Result。
+/// ---
+/// purpose: team-agent watch 的主循环：反复增量收集、输出、休眠
+/// params:
+///   workspace: workspace 根
+///   team: 只看这个 team；None 表示不过滤
+///   interval_sec: 轮询间隔；非有限值或非正数时回落到内置默认
+///   output: 输出回调，注入以便测试；本函数自己不写 stdout
+/// returns: 循环结束时为 Ok。这是个长跑循环，正常运行期间不返回
+/// errors: 打开 message store 或某轮收集失败时返回 WatchError
+/// ---
 pub fn run_watch(
     workspace: &WorkspacePath,
     team: Option<&str>,

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

@@ -1,3 +1,34 @@
+//! ---
+//! purpose: coordinator 子系统装配面——声明各子模块并把它们的公开面重导出到 crate::coordinator
+//! contract:
+//!   provides:
+//!     - name: run_daemon
+//!       what: per-workspace daemon 进程入口（主循环 + 退避）
+//!     - name: coordinator_health
+//!       what: pid/metadata/schema 三合一健康判定
+//!     - name: start_coordinator
+//!       what: 幂等启动 daemon 子进程
+//!     - name: stop_coordinator
+//!       what: 停 daemon 并清 pid/meta
+//!     - name: run_watch
+//!       what: team-agent watch 的只读事件流主循环
+//!     - name: detect_whole_team_gone
+//!       what: 不依赖 coordinator 存活的整队消失判定
+//!   depends:
+//!     - crate::state
+//!     - crate::message_store
+//!     - crate::messaging
+//!     - crate::transport
+//!     - crate::provider
+//!     - crate::leader
+//!     - crate::event_log
+//! boundary:
+//!   - 不实现消息投递与结果回收本体（在 crate::messaging，本模块只按固定顺序调用）
+//!   - 不直接依赖任何 provider client crate，provider 一律经 ProviderAdapter trait
+//!   - 不做物理注入/键盘写入，注入归 crate::transport
+//!   - 无 pending obligation 时不注入任何探索性 prompt
+//! maturity: wired
+//! ---
 //!
 //! step 12 · coordinator — daemon lifecycle / single-tick orchestration SKELETON (ROUND-0).
 //!