@team-agent/installer 0.5.66 → 0.5.68

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

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

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

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

@@ -1,3 +1,37 @@
+//! ---
+//! purpose: coordinator 的核心——Coordinator 本体与单次 tick 的固定顺序编排，外加心跳 sidecar 与 worker 运行态解析
+//! contract:
+//!   provides:
+//!     - name: tick
+//!       what: 跑一轮固定顺序的编排：会话门 → 捕获缺失 session → 启动/审批提示 → 健康对账 → 投递与到期事件 → 只读探测 → 原子持久化 → 回收结果
+//!     - name: write_coordinator_heartbeat
+//!       what: 写 runtime/coordinator_tick.json 心跳 sidecar（阶段、状态、boot id、迭代计数）
+//!     - name: read_coordinator_heartbeat
+//!       what: 只读取出最近一次心跳，供 status/diagnose 消费
+//!     - name: resolve_worker_runtime_state_with_fg_pgrp
+//!       what: 由 agent JSON 与活动分类结果解析 worker 运行态，缺信号时判 Unknown 而非 Idle
+//!   depends:
+//!     - super::health
+//!     - super::types
+//!     - super::steps
+//!     - super::steps::abnormal
+//!     - super::runtime_observation
+//!     - crate::state
+//!     - crate::message_store
+//!     - crate::messaging
+//!     - crate::leader
+//!     - crate::provider
+//!     - crate::transport
+//!     - crate::event_log
+//!     - crate::os_probe
+//! boundary:
+//!   - 不实现投递、到期事件与结果回收的本体，那些在 crate::messaging，本模块只按序调用
+//!   - 无 pending obligation 时不注入任何探索性 prompt；无既定义务时唯一会投递的是 should_ping 成立时的一条中性提示。例外：屏上出现审批提示且策略允许时，runtime_approval 会经 transport.send_keys 注入应答按键（不是 prompt，是对已观测提示的应答）
+//!   - 监测步骤失败降级并继续，TickReport.ok=true 不代表每一步都成功——各步失败只在事件里
+//!   - 持久化失败走 degraded 报告而不是 panic，也不是 Err
+//!   - 不直接依赖 provider client crate，provider 一律经注入的 ProviderAdapter
+//! maturity: wired
+//! ---
 //!
 //! Coordinator core:daemon lifecycle 宿主 + 单次 tick 编排(19 步固定顺序)+ health/start/stop。
 
@@ -166,6 +200,14 @@ pub struct Coordinator {
 
 impl Coordinator {
     /// 构造(注入 provider registry + transport)。spawn 出的 daemon 在 `run` 前装配它。
+    /// ---
+    /// purpose: 装配一个 Coordinator——注入 provider registry 与 transport，两者都是 trait object 以便替换与 mock
+    /// params:
+    ///   workspace: 本实例服务的 workspace 根
+    ///   provider_registry: provider adapter 解析器；provider 一律经它取，绝不直连 provider client crate
+    ///   transport: 会话/pane 控制面，用于存活探测与注入
+    /// returns: 未绑定 team_key、无 save 钩子、无顺序探针的实例
+    /// ---
     pub fn new(
         workspace: WorkspacePath,
         provider_registry: Box<dyn ProviderRegistry>,
@@ -181,6 +223,12 @@ impl Coordinator {
         }
     }
 
+    /// ---
+    /// purpose: 绑定 daemon 侧选定的 team_key，让 tick 的状态投影用它而不是可能过期的根 active_team_key
+    /// params:
+    ///   team_key: 目标 team；None 或空串都视为未绑定，tick 会回落到 state 推导
+    /// returns: 绑定后的自身
+    /// ---
     pub(crate) fn with_team_key(mut self, team_key: Option<String>) -> Self {
         self.daemon_team_key = team_key.filter(|key| !key.is_empty());
         self
@@ -190,6 +238,17 @@ impl Coordinator {
     /// transport + mock provider registry + 可选 save 注入钩 + ORDER 探针。**纯 test-support
     /// 脚手架**(真实 impl,非 `unimplemented!()`):它只装配字段,不执行任何 daemon 逻辑;
     /// tick/health/start/stop 仍是 `unimplemented!()` 生产体,因此调它们的契约仍 RED。
+    /// ---
+    /// purpose: 测试装配口——直接构出实例并注入 save 钩子与步骤顺序探针
+    /// params:
+    ///   workspace: workspace 根
+    ///   provider_registry: 可 mock 的 provider adapter 解析器
+    ///   transport: 可 mock 的传输控制面
+    ///   save_hook: 替换真实持久化，用于制造持久化失败
+    ///   order_recorder: 记录 tick 内各步骤名，用于断言固定顺序
+    /// returns: 只装配字段的实例，本函数自身不执行任何 daemon 逻辑
+    /// cfg: test
+    /// ---
     #[cfg(test)]
     pub(crate) fn for_test(
         workspace: WorkspacePath,
@@ -226,6 +285,11 @@ impl Coordinator {
     /// `state::save_runtime_state`,bug-084 测试注入失败);在每个 step8-11 原子调用点
     /// `if let Some(rec) = &self.order_recorder { rec.lock()...push(STEP_NAME) }`(tick
     /// 副作用 ORDER 测试断言固定序列)。生产两者均 `None`,零开销。
+    /// ---
+    /// purpose: 跑一轮 tick——按固定顺序把各步骤串起来，只投递既定义务，绝不凭空注入
+    /// returns: TickReport。传输会话不在了 → stop=true 且 reason=TmuxSessionMissing，主循环据此退出；持久化失败 → ok=false、reason=PersistenceDegraded、persisted=Some(false)，但仍是 Ok；正常 → ok=true 并带本轮投递、到期事件、回收结果等清单。注意 ok=true 只说明主干走完，监测类步骤失败已被降级吞掉，真相只在事件日志里
+    /// errors: 加载状态、打开 message store、传输探测或事件写入这些主干操作失败时返回 TickError，由主循环 catch 后退避
+    /// ---
     pub fn tick(&self) -> Result<TickReport, TickError> {
         self.record_step(TickStepGroup::SessionGate, "load_state");
         let raw_state = crate::state::persist::load_runtime_state(self.workspace.as_path())?;
@@ -271,17 +335,12 @@ impl Coordinator {
         }
 
         self.record_step(TickStepGroup::SessionGate, "capture_missing");
-        let pending_context_fork_audits =
-            match self.capture_missing_sessions(&mut state, &event_log) {
-                Ok(audits) => audits,
-                Err(error) => {
-                    let _ = event_log.write(
-                        "coordinator.tick.capture_missing_failed",
-                        serde_json::json!({"error": error.to_string()}),
-                    );
-                    Vec::new()
-                }
-            };
+        if let Err(error) = self.capture_missing_sessions(&mut state, &event_log) {
+            let _ = event_log.write(
+                "coordinator.tick.capture_missing_failed",
+                serde_json::json!({"error": error.to_string()}),
+            );
+        }
 
         // Slice 1 energy gate: one pane snapshot per tick feeds probe eligibility,
         // health sync, and abnormal-exit detection. Missing panes are filtered
@@ -461,15 +520,6 @@ impl Coordinator {
                 collections,
             ));
         }
-        for context_fork in &pending_context_fork_audits {
-            context_fork.write_audit(&event_log).map_err(|error| {
-                eprintln!(
-                    "[coordinator] context_fork audit publish failed after state commit: {error}"
-                );
-                TickError::EventLog(error)
-            })?;
-        }
-
         self.record_step(TickStepGroup::Delivery, "collect_results");
         collections.results =
             collect_results(crate::messaging::collect_results_and_notify_watchers(
@@ -489,7 +539,7 @@ impl Coordinator {
         &self,
         state: &mut Value,
         event_log: &EventLog,
-    ) -> Result<Vec<crate::lifecycle::launch::ContextForkFinalized>, TickError> {
+    ) -> Result<(), TickError> {
         let report = crate::session_capture::capture_missing_provider_sessions_once(
             state,
             &mut |provider| self.provider_registry.adapter_for(provider),
@@ -653,7 +703,7 @@ impl Coordinator {
                 }),
             )?;
         }
-        Ok(report.context_forks)
+        Ok(())
     }
 
     fn sync_agent_health(
@@ -1371,6 +1421,11 @@ impl Coordinator {
 
     /// `coordinator_health`(`lifecycle.py:26`)。pid + meta + schema 三合一健康。
     /// doctor / start 前置调它。`ok = running ∧ metadata_ok ∧ schema_ok`。
+    /// ---
+    /// purpose: 取本 workspace 的 coordinator 健康报告
+    /// returns: 与 health::coordinator_health 完全一致的报告
+    /// errors: 当前实现恒为 Ok；返回类型保留 Result 以便未来健康判定引入可失败路径
+    /// ---
     pub fn health(&self) -> Result<HealthReport, TickError> {
         Ok(super::health::coordinator_health(&self.workspace))
     }
@@ -1379,11 +1434,23 @@ impl Coordinator {
     /// schema 不兼容拒启给 hint;否则 spawn 自身二进制子命令(`team-agent coordinator --workspace ..`,
     /// Python 是 `python -m team_agent.coordinator`,`lifecycle.py:108`)。
     /// **schema 兼容门**:三元任一不匹配 → restart_incompatible,**不可静默继续**(card §89)。
+    /// ---
+    /// purpose: 幂等启动本 workspace 的 daemon 子进程
+    /// returns: 与 health::start_coordinator 完全一致的报告；「拒启」体现为 ok=false 而非 Err
+    /// errors: 建目录、开日志、spawn 或写 pid/metadata 失败时返回 StartError
+    /// ---
     pub fn start(&self) -> Result<StartReport, StartError> {
         super::health::start_coordinator(&self.workspace)
     }
 
     /// `stop_coordinator`(`lifecycle.py:229`)。SIGTERM + 清 pid/meta。pid 非整数 → 清文件返回。
+    /// ---
+    /// purpose: 清掉本 workspace 的 coordinator pid/meta 文件
+    /// returns: pid 文件不存在 → Missing；文件在且内容可解析 → Stopped 并带该 pid；文件在但内容非法 → InvalidPidRemoved
+    /// errors: 删文件失败时返回 StopError
+    /// ---
+    /// 注意：本方法只删文件，**不向 daemon 发任何信号**——与 health::stop_coordinator
+    /// 的「真终止进程」语义不同。调它之后 daemon 仍会继续 tick，而健康探测会报 Missing。
     pub fn stop(&self) -> Result<StopReport, StopError> {
         let pid_path = coordinator_pid_path(&self.workspace);
         if !pid_path.exists() {
@@ -1412,6 +1479,10 @@ impl Coordinator {
 
     /// `message_store_schema_health`(`lifecycle.py:197`)。DB 列兼容门:区分 pre-init 必需列缺失
     /// (拒启)vs migratable 列缺失(可迁移)。`doctor --fix-schema` 用其 action hint。
+    /// ---
+    /// purpose: 查本队 message store 的 schema 兼容门
+    /// returns: 与 health::message_store_schema_health 一致；打不开库时 ok=false 并带原文与修复 hint
+    /// ---
     pub fn schema_health(&self) -> SchemaHealth {
         // A-8: the gate must inspect the REAL team.db (Python lifecycle.py:197+
         // message_store_schema_health); a hardcoded ok:true left the card §89
@@ -1525,6 +1596,21 @@ fn increment_coordinator_tick_iteration_count(workspace: &WorkspacePath) {
     );
 }
 
+/// ---
+/// purpose: 写心跳 sidecar runtime/coordinator_tick.json，让外部不必进程内也能看到 daemon 走到哪一步
+/// params:
+///   workspace: workspace 根
+///   pid: 当前 daemon pid
+///   boot_id: daemon 世代 id；None 时沿用文件里已有值，都没有则用 coord_unknown_<pid>
+///   last_phase: 本次写入代表的阶段名；值为 tick_running 时刷新 last_tick_started_at，否则刷新 last_tick_finished_at
+///   last_tick_status: 上一轮 tick 的状态串
+///   last_error: 上一轮的错误串
+///   increment_count: 是否把迭代计数加一
+/// returns: 写成功返回 ()；先写临时文件再 rename，读方不会看到半份
+/// errors: 建目录、写临时文件或 rename 失败时返回 io::Error
+/// ---
+/// ⚠ 字段 `host_boot_time` 写的是**本次写入时刻的墙钟**，不是主机启动时间——
+/// 每次心跳都会变。主机启动身份在 `host_boot_id`，按名消费 host_boot_time 会拿到假事实。
 pub(crate) fn write_coordinator_heartbeat(
     workspace: &WorkspacePath,
     pid: Pid,
@@ -1597,6 +1683,10 @@ fn coordinator_heartbeat_path(workspace: &WorkspacePath) -> PathBuf {
 /// falls back to a formatted timestamp. Returns None when the platform
 /// signal cannot be read — the caller MUST NOT guess; downstream
 /// treats a missing/mismatched host boot separately from a matched one.
+/// ---
+/// purpose: 探测当前主机的启动身份，用来识别「所有 pane/pid/会话绑定都早于本次开机」
+/// returns: Linux 读 boot_id 得 linux-<uuid>；macOS 读 kern.boottime 得 macos-<...>；测试可用 TEAM_AGENT_TEST_HOST_BOOT_ID 覆盖。平台信号读不到时为 None——调用方必须把「读不到」与「不匹配」分开处理，不许猜
+/// ---
 pub(crate) fn probe_host_boot_id() -> Option<String> {
     if let Ok(override_id) = std::env::var("TEAM_AGENT_TEST_HOST_BOOT_ID") {
         if !override_id.is_empty() {
@@ -1634,6 +1724,12 @@ pub(crate) fn probe_host_boot_id() -> Option<String> {
 /// error (missing file, malformed JSON) returns None — callers treat
 /// that as "unknown, fall back to existing facts" per locate §8 risk
 /// note, they must never guess a stale/fresh verdict from absence.
+/// ---
+/// purpose: 只读取出最近一次写入的心跳 sidecar
+/// params:
+///   workspace: workspace 根
+/// returns: 解析成功才有值；文件缺失或 JSON 损坏一律 None。调用方须把 None 当作「未知」回落到既有事实，不得据此断定新鲜或陈旧
+/// ---
 pub fn read_coordinator_heartbeat(workspace: &WorkspacePath) -> Option<Value> {
     let path = coordinator_heartbeat_path(workspace);
     let text = std::fs::read_to_string(path).ok()?;
@@ -2529,6 +2625,13 @@ fn write_activity(
 ///                     conflict (or probe unavailable + activity idle).
 ///   5. Unknown      — missing pane_pid, probe error, or no decisive
 ///                     signal. Iron law: never silently Idle.
+/// ---
+/// purpose: 由 agent 状态与活动分类结果解析出 worker 的运行态
+/// params:
+///   agent: agent 状态对象；读 pane_pid、awaiting_human_confirm 与审批/信任标志
+///   activity: JSONL 活动分类结果；None 表示本轮没有分类信号
+/// returns: 按优先级判定——先 Blocked（等人确认/等信任提示），再用前台进程组探测判 Busy，再由活动分类给 Busy/ProbablyIdle；任何一步缺信号都落到 Unknown。铁律是绝不在信息不足时静默判 Idle
+/// ---
 pub(crate) fn resolve_worker_runtime_state_with_fg_pgrp(
     agent: &Value,
     activity: Option<&crate::messaging::AgentActivity>,
@@ -2612,6 +2715,14 @@ fn agent_health_status_wire(status: crate::messaging::ActivityStatus) -> &'stati
 /// 0.4.x Phase 1: read the worker_state wire string that `write_activity`
 /// persisted alongside the legacy activity. Returns None when no worker_state
 /// has been written yet (older state row pre-upgrade).
+/// ---
+/// purpose: 读回 write_activity 与活动一起持久化的 worker_state 线字符串
+/// params:
+///   agent: agent 状态对象
+/// returns: 已写过 worker_state 时解析出运行态；升级前的旧状态行没有该字段，返回 None
+/// ---
+/// 现状：本仓内没有任何调用点（仅定义），与其他 pub(crate) 项不同——按机器事实记录，
+/// 不据此推断它「已接线」。
 pub(crate) fn agent_worker_state(agent: &Value) -> Option<crate::messaging::WorkerRuntimeState> {
     agent
         .get("worker_state")