@team-agent/installer 0.5.65 → 0.5.68

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).
 //!

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

@@ -1,3 +1,19 @@
+//! ---
+//! purpose: 两个纯判定——daemon 自己是不是该自杀的孤儿，以及整个队是不是已经全没了
+//! contract:
+//!   provides:
+//!     - name: should_orphan_self_terminate
+//!       what: ppid 变更 + 被 init 收养 + workspace 已消失，三者同时成立才判孤儿
+//!     - name: detect_whole_team_gone
+//!       what: 由存活快照判整队消失，并区分 clean/restart（静默）与 unexpected（写 marker + 延迟升报）
+//!   depends:
+//!     - super::types
+//! boundary:
+//!   - 不杀任何进程，也不发信号；只给判定结果，动作归调用方
+//!   - 不读屏、不命名 provider；只消费结构化存活快照
+//!   - 不直接升报用户，unexpected 只落 durable marker，等下一条 leader 命令再升
+//! maturity: wired
+//! ---
 //!
 //! 孤儿自终止判定(Gap 37b)+ provider-neutral 整队消失检测。
 
@@ -9,6 +25,14 @@ use super::types::{
 /// 孤儿自终止判定(`__main__.py:51-59`,Gap 37b)。仅当
 /// `current_ppid != initial_ppid ∧ current_ppid == 1 ∧ !workspace.exists()` 三者**同时**成立 → true。
 /// 少一个条件都不能误杀正常 daemon(card §91)。
+/// ---
+/// purpose: 判断本 daemon 是否已成为应当自我终止的孤儿
+/// params:
+///   initial_ppid: 进程启动那一刻记下的父 pid
+///   current_ppid: 当前父 pid；被 init/launchd 收养后为 1
+///   workspace: 本 daemon 服务的 workspace 根，用其存在性作第三个条件
+/// returns: 三个条件同时成立才为 true；少一个都返回 false，宁可不自杀
+/// ---
 pub fn should_orphan_self_terminate(
     initial_ppid: u32,
     current_ppid: u32,
@@ -25,6 +49,13 @@ pub fn should_orphan_self_terminate(
 /// `detect_whole_team_gone`(`abnormal_track.py:91`,C10/C13)。coordinator-independent 整队消失检测:
 /// 全死(coordinator + leader + 所有 worker + 所有 session)且非 clean_shutdown/restart →
 /// 写 durable marker + 延迟到下条 leader 命令再 escalate。clean/restart 静默。
+/// ---
+/// purpose: 由整队存活快照判定「整队消失」并给出分类与后续处置标志
+/// params:
+///   snapshot: coordinator/leader/各 worker 进程/transport 会话的存活位，以及 clean_shutdown、restart_in_progress 两个意图位
+///   marker_store: durable marker 写入口；仅 unexpected_exit 分支会被调用
+/// returns: 任一成员存活则 Alive 且全部标志为 false；全死时按 clean_shutdown、restart_in_progress、unexpected_exit 依次分类，只有 unexpected 才置 notify/escalate 并写 marker
+/// ---
 pub fn detect_whole_team_gone(
     snapshot: &TeamPresenceSnapshot,
     marker_store: &mut dyn MarkerStore,

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

@@ -1,3 +1,22 @@
+//! ---
+//! purpose: 三个只读运行时探测——上下文压缩、Codex session 漂移、leader 端 API 错误——全部值变才发事件
+//! contract:
+//!   provides:
+//!     - name: observe_runtime
+//!       what: 对本 tick 的每条捕获事实跑三个探测，收集结果并写变化驱动的事件
+//!   depends:
+//!     - super::runtime_observation
+//!     - super::types
+//!     - crate::event_log
+//!     - crate::state::projection
+//!     - crate::state::ownership
+//!     - crate::model::enums
+//! boundary:
+//!   - 只分类不动作：不重启 agent、不清 session、不投递任何消息，只给 recommendation 文案
+//!   - 事件是 change-driven：计数/指纹不变的那一 tick 不重发，去重键存在 state 里
+//!   - 只读 scrollback 尾与已存 session id，不与 provider 进程交互
+//! maturity: wired
+//! ---
 //!
 use std::collections::BTreeMap;
 use std::path::Path;
@@ -15,6 +34,15 @@ use super::types::{CompactionResult, LeaderApiError, SessionDriftResult};
 
 const COMPACTION_RESET_THRESHOLD_DEFAULT: i64 = 3;
 
+/// ---
+/// purpose: 对本 tick 的全部捕获事实依次跑 compaction / session-drift / leader-api-error 三个探测
+/// params:
+///   workspace: workspace 根，用于打开事件日志
+///   state: 可变运行时状态；探测在其中读写压缩计数、漂移标记与 api-error 指纹这些跨 tick 去重键
+///   captures_by_agent: 本 tick 的 per-agent 捕获事实，按 agent_id 有序
+///   leader_capture: leader 侧捕获；为 None 时 api-error 结果为空，且不清除既有指纹
+/// returns: 捕获事实原样带回，附三组探测结果；未命中的探测对应空 Vec
+/// ---
 pub fn observe_runtime(
     workspace: &Path,
     state: &mut Value,
@@ -554,6 +582,8 @@ fn runtime_event_provider_name(provider: Provider) -> &'static str {
         Provider::Codex => "codex",
         Provider::Copilot => "copilot",
         Provider::GeminiCli => "gemini_cli",
+        Provider::Grok => "grok",
+        Provider::CursorAgent => "cursor_agent",
         Provider::Fake => "fake",
     }
 }

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

@@ -1,3 +1,19 @@
+//! ---
+//! purpose: 运行时观测的类型缝——定义「一次 tick 捕到的事实」与「探测结果集合」两个形状，并把探测转交 runtime_detectors
+//! contract:
+//!   provides:
+//!     - name: observe
+//!       what: 把本 tick 的 per-agent 捕获事实与 leader 捕获事实交给探测器，返回结果集合
+//!   depends:
+//!     - super::runtime_detectors
+//!     - super::types
+//!     - crate::provider
+//!     - crate::transport
+//! boundary:
+//!   - 不做捕获本身（scrollback/pane 快照由 tick 侧采集后传入）
+//!   - 不做任何判定，判定全在 runtime_detectors
+//! maturity: wired
+//! ---
 //!
 //! Shared coordinator runtime observation seam.
 //!
@@ -49,6 +65,15 @@ pub struct RuntimeObservationResults {
     pub api_errors: Vec<LeaderApiError>,
 }
 
+/// ---
+/// purpose: 本 tick 观测的统一入口，把捕获事实转交 runtime_detectors 并原样带回结果
+/// params:
+///   workspace: workspace 根，探测器据此写事件日志
+///   state: 可变运行时状态；探测器在其中保存跨 tick 的去重/计数键
+///   captures_by_agent: 本 tick 每个 agent 的捕获事实（scrollback 尾、pane 信息、已存 session id 等）
+///   leader_capture: leader 侧捕获事实；缺失表示本 tick 没拿到 leader 屏幕，api-error 探测随之为空
+/// returns: 捕获事实原样回传，外加 compaction / session_drift / leader api-error 三组探测结果
+/// ---
 pub fn observe(
     workspace: &Path,
     state: &mut Value,

package/crates/team-agent/src/coordinator/steps/abnormal.rs

@@ -1,3 +1,31 @@
+//! ---
+//! purpose: tick 的异常退出检测步骤——按 agent 读有界 rollout 尾，判「最新一条显式 provider 错误是否属于当前 worker 世代」，据此决定通知还是只留审计
+//! contract:
+//!   provides:
+//!     - name: detect_abnormal_exits
+//!       what: 遍历受监视 agent，产出 worker.abnormal_exit 通知或 dead_only 审计事件，并把本轮观测写回 state 的 abnormal_exit_watch
+//!     - name: explicit_process_liveness
+//!       what: 从 agent JSON 的显式存活字段解析进程存活态，不做任何探测
+//!     - name: read_tail_text
+//!       what: 有界读文件尾部文本，超长时从尾部 max_bytes 处起读
+//!     - name: metadata_mtime_ns
+//!       what: 把文件 metadata 的 mtime 归一成纳秒整数，供跨 tick 变化比较
+//!   depends:
+//!     - super::super::health
+//!     - super::super::tick
+//!     - super::super::types
+//!     - crate::event_log
+//!     - crate::messaging
+//!     - crate::provider
+//!     - crate::transport
+//!     - crate::state::projection
+//! boundary:
+//!   - 不重启、不清理、不做物理注入：写事件与 state 观测记录之外，异常通知会经 crate::messaging 的 leader funnel 入库为 accepted 消息（物理注入由后续 deliver_pending 完成）
+//!   - 进程已死但没有显式错误时不通知，只落 dead_only 审计
+//!   - 通知事件里的 queued 只表示消息入库，不表示已送达
+//!   - rollout 尾读是有界的（首行可能被截断，消费方只解析最后一条完整 JSONL 记录）
+//! maturity: wired
+//! ---
 //!
 //! unit-11 (Stage 4) — coordinator tick `abnormal` step group.
 //!
@@ -23,6 +51,17 @@ use super::super::types::Pid;
 /// provider error that is fresh for the current worker cohort. A dead process
 /// without an explicit error remains a suppressed `dead_only` audit event; process
 /// liveness is otherwise diagnostic data for this path.
+/// ---
+/// purpose: 跑一轮异常退出检测，把结论落成事件与 state 里的 abnormal_exit_watch 记录
+/// params:
+///   workspace: workspace 根，用于解析 rollout 相对路径
+///   transport: pane 存活探测通道；只读探测，不注入
+///   state: 可变运行时状态；本轮观测（size/mtime/世代/去重键）写回 coordinator.abnormal_exit_watch
+///   event_log: 事件出口
+///   targets: 本 tick 已采到的 pane 快照，避免每 agent 重新列一遍
+/// returns: 检测跑完即 Ok；「有没有异常」不由返回值表达，只体现在事件与 state 里
+/// errors: 事件写入等不可恢复失败时返回 TickError；单个 agent 的 rollout metadata 读不到不算错误，记为 unverifiable 继续
+/// ---
 pub(crate) fn detect_abnormal_exits(
     workspace: &Path,
     transport: &dyn crate::transport::Transport,
@@ -476,6 +515,12 @@ fn agent_pid(agent: &Value) -> Option<Pid> {
         .find_map(|key| json_u32(agent.get(key)).map(Pid::new))
 }
 
+/// ---
+/// purpose: 只从 agent JSON 里已写明的存活字段读出进程存活态，不做任何主动探测
+/// params:
+///   agent: agent 状态对象；先下钻 provider_process / process 子对象，再看本层的 *_liveness 串字段
+/// returns: 命中显式字段时给出 Alive/Dead/Unverifiable；没有任何显式字段时为 None，交调用方走探测路径
+/// ---
 pub(crate) fn explicit_process_liveness(agent: &Value) -> Option<ProcessLiveness> {
     if let Some(process) = agent
         .get("provider_process")
@@ -836,6 +881,12 @@ fn process_liveness_wire(state: ProcessLiveness) -> &'static str {
     }
 }
 
+/// ---
+/// purpose: 把文件修改时间归一成自 UNIX 纪元起的纳秒整数，供跨 tick 比较「rollout 有没有变过」
+/// params:
+///   metadata: 目标文件的 metadata
+/// returns: 纳秒时间戳；取不到 mtime 或早于纪元时为 None。乘加均为 saturating，不会回绕
+/// ---
 pub(crate) fn metadata_mtime_ns(metadata: &std::fs::Metadata) -> Option<u64> {
     let duration = metadata
         .modified()
@@ -977,6 +1028,14 @@ const ABNORMAL_TAIL_BYTES: u64 = 131_072;
 ///
 /// P1: bounded tail read; a partial first line is harmless (the consumer only parses
 /// the latest complete JSONL record) and lossy UTF-8 keeps a mid-codepoint seek safe.
+/// ---
+/// purpose: 有界读取文件尾部文本，避免整份 rollout 进内存
+/// params:
+///   path: 目标文件
+///   max_bytes: 最多回读的字节数；文件更短时整份读出
+/// returns: 尾部文本。按字节 seek，首行可能被截断，且用有损 UTF-8 解码，切在码点中间也安全
+/// errors: 打开、取长度或读取失败时返回底层 io::Error
+/// ---
 pub(crate) fn read_tail_text(path: &Path, max_bytes: u64) -> std::io::Result<String> {
     use std::io::{Read, Seek, SeekFrom};
     let mut file = std::fs::File::open(path)?;

package/crates/team-agent/src/coordinator/steps/delivery.rs

@@ -1,3 +1,13 @@
+//! ---
+//! purpose: coordinator tick delivery 步骤组的占位命名空间——实现仍在 tick.rs
+//! contract:
+//!   provides: []
+//!   depends: []
+//! boundary:
+//!   - 本文件当前不含任何 item：消息投递 FSM 的 tick 步骤未来迁入处
+//!   - 迁移落地前不要在此新增逻辑，否则步骤顺序会分裂成两处
+//! maturity: signature_only
+//! ---
 //!
 //! unit-11 (Stage 4) — coordinator tick `delivery` step group.
 //!

package/crates/team-agent/src/coordinator/steps/health_sync.rs

@@ -1,3 +1,13 @@
+//! ---
+//! purpose: coordinator tick health_sync 步骤组的占位命名空间——实现仍在 tick.rs
+//! contract:
+//!   provides: []
+//!   depends: []
+//! boundary:
+//!   - 本文件当前不含任何 item：worker 存活对账步骤未来迁入处
+//!   - 迁移落地前不要在此新增逻辑，否则步骤顺序会分裂成两处
+//! maturity: signature_only
+//! ---
 //!
 //! unit-11 (Stage 4) — coordinator tick `health_sync` step group.
 //!

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

@@ -1,3 +1,17 @@
+//! ---
+//! purpose: tick 步骤组的命名空间与规范顺序——给每个步骤组一个稳定标签与固定次序，供编排器与事件日志共用
+//! contract:
+//!   provides:
+//!     - name: ordered
+//!       what: 步骤组的规范顺序（穷尽枚举），编排器必须按此序调用
+//!     - name: as_str
+//!       what: 步骤组的稳定标签（tick.<group>），进事件与指标字段
+//!   depends: []
+//! boundary:
+//!   - 不含任何步骤的实现，只定义分组身份与顺序
+//!   - persist 必须排最后、session_gate 必须排最前，这是顺序本身承载的约束
+//! maturity: wired
+//! ---
 //!
 //! unit-11 (Stage 4) — coordinator tick steps namespace.
 //!
@@ -37,6 +51,10 @@ pub enum TickStepGroup {
 
 impl TickStepGroup {
     /// Stable label used in event-log and metric fields.
+    /// ---
+    /// purpose: 给步骤组一个稳定标签，供事件日志与指标字段使用
+    /// returns: 形如 tick.<group> 的稳定串；已发布的取值不可改写，只可新增
+    /// ---
     pub fn as_str(self) -> &'static str {
         match self {
             Self::SessionGate => "tick.session_gate",
@@ -50,6 +68,10 @@ impl TickStepGroup {
 
     ///
     /// Canonical ordering as a const slice — exhaustive over the enum.
+    /// ---
+    /// purpose: 给出步骤组的规范调用顺序
+    /// returns: 穷尽覆盖本 enum 全部变体的静态切片，session_gate 在首、persist 在尾；编排器按此序调用，持久化才能反映之前每一步的结果
+    /// ---
     pub fn ordered() -> &'static [TickStepGroup] {
         &[
             TickStepGroup::SessionGate,

package/crates/team-agent/src/coordinator/steps/persist.rs

@@ -1,3 +1,13 @@
+//! ---
+//! purpose: coordinator tick persist 步骤组的占位命名空间——实现仍在 tick.rs
+//! contract:
+//!   provides: []
+//!   depends: []
+//! boundary:
+//!   - 本文件当前不含任何 item：tick 末尾的持久化步骤未来迁入处
+//!   - 迁移落地前不要在此新增逻辑，否则步骤顺序会分裂成两处
+//! maturity: signature_only
+//! ---
 //!
 //! unit-11 (Stage 4) — coordinator tick `persist` step group.
 //!

package/crates/team-agent/src/coordinator/steps/runtime_prompts.rs

@@ -1,3 +1,13 @@
+//! ---
+//! purpose: coordinator tick runtime_prompts 步骤组的占位命名空间——实现仍在 tick.rs
+//! contract:
+//!   provides: []
+//!   depends: []
+//! boundary:
+//!   - 本文件当前不含任何 item：startup / approval / abnormal-exit 提示步骤未来迁入处
+//!   - 迁移落地前不要在此新增逻辑，否则步骤顺序会分裂成两处
+//! maturity: signature_only
+//! ---
 //!
 //! unit-11 (Stage 4) — coordinator tick `runtime_prompts` step group.
 //!