@team-agent/installer 0.5.66 → 0.5.69

package/crates/team-agent/src/provider/session/capture.rs

@@ -1,4 +1,42 @@
-//!
+//! ---
+//! purpose: 会话捕获通道——把「席位有 pending id 但还没有权威会话」这件事，经扫描候选 + 分配器，收敛成 state 上的原子四元组(session_id + rollout_path + captured_at + captured_via)，收敛不了就写明确的诊断态
+//! contract:
+//!   provides:
+//!     - name: capture_missing_provider_sessions_once
+//!       what: 单次捕获通道:挑 pending 席位 → adapter 扫候选 → 分配 → 写四元组或写 ambiguous/identity_mismatch/transcript_missing
+//!     - name: converge_missing_provider_sessions
+//!       what: 破坏性生命周期门用的有界收敛屏障:显式 deadline + poll_interval，反复调上一函数直到无缺口或超预算
+//!     - name: recover_resume_session_from_events
+//!       what: 从 event log 的 session.captured 记录补回缺失的四元组，captured_via=event_log_repair
+//!     - name: incomplete_resumable_agent_ids
+//!       what: 列出「provider 支持 resume 但四元组不完整」的席位 id，已排序
+//!     - name: incomplete_interacted_resumable_agent_ids
+//!       what: 上一条再筛「有过 first_send_at」的子集
+//!     - name: CapturePassReport
+//!       what: 单次捕获的结果面:changed/pending/assigned/ambiguous/identity_mismatches/capture_failures/candidate_count_by_agent/transcript_missing
+//!     - name: SessionConvergence
+//!       what: 收敛结果:converged 是否达成、changed、剩余 missing、预算与实耗
+//!     - name: SessionConvergenceProgress
+//!       what: 每轮回调给调用方的进度快照
+//!     - name: SESSION_CAPTURE_CONVERGENCE_DEADLINE_MS
+//!       what: 默认收敛预算 12s(restart 复用同一常量)
+//!     - name: SESSION_CAPTURE_CONVERGENCE_POLL_MS
+//!       what: 默认轮询间隔 250ms
+//!   requires:
+//!     - name: crate::provider::ProviderAdapter
+//!       what: 候选扫描一律经 adapter.capture_session_candidates，本文件不直接读 provider 存档
+//!     - name: crate::state::identity_keys::SessionAttributionKey
+//!       what: 分配器的 claimed 键空间(Session/Transcript × team-scoped/global)
+//!     - name: crate::event_log::EventLog
+//!       what: event-log 修复通道的事实源
+//! boundary:
+//!   - 四元组是原子的:缺 session_id 或 rollout_path 就整条不写，宁可留 pending 也不写半条
+//!   - 不发事件——transcript_missing 只进报告，事件由 coordinator tick 节流发出
+//!   - 不启动/销毁席位，不决定 restart 走向;只提供事实与诊断态
+//!   - capture_state 只是诊断字段，写它不等于写权威四元组
+//!   - 歧义只在 finalize_ambiguous=true 的那一趟才落盘;收敛超时的那趟不 finalize
+//! maturity: wired
+//! ---
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 
@@ -30,7 +68,6 @@ pub struct CapturePassReport {
     /// (coordinator tick) emits a throttled
     /// `provider.session.transcript_missing` event for each entry.
     pub transcript_missing: Vec<TranscriptMissing>,
-    pub(crate) context_forks: Vec<crate::lifecycle::launch::ContextForkFinalized>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -97,6 +134,26 @@ pub struct SessionConvergenceProgress {
 /// unbounded wait: callers must pass an explicit `deadline` and `poll_interval`.
 /// Each poll runs the shared allocator once, reports progress, and sleeps until
 /// either all required agents have provider sessions or the deadline expires.
+/// ---
+/// purpose: 有界收敛屏障——在显式预算内反复跑单次捕获，直到调用方指定的必需席位都拿到会话，或预算耗尽
+/// params:
+///   state: 就地修改的 state JSON;每轮的写入都直接落在它上面
+///   adapter_for: provider → adapter 的工厂
+///   deadline: 总预算;绝不无限等待
+///   poll_interval: 轮询间隔;同时用作单次捕获的 timeout(取秒数，至少 1)
+///   missing_agent_ids: 由调用方定义「谁必须有会话」——本函数不自己判定必需集
+///   progress: 每轮回调;返回 Err 即整体中止并把该错误上抛
+/// returns: converged=true 表示 missing 已空;converged=false 表示预算到期仍有缺口，两者都是正常返回而非错误
+/// errors: 单次捕获的 ProviderError 与 progress 回调的错误都被转成 String 上抛
+/// contract:
+///   provides:
+///     - name: converge_missing_provider_sessions
+///       what: 只有 missing 清空后才会补跑一趟 finalize_ambiguous=true;超时路径不补跑
+/// boundary:
+///   - 不是机会式单次捕获，也不是无界等待——预算必须由调用方显式给出
+///   - 超时返回时歧义态未被 finalize:行上不会出现 attribution_ambiguous 标记;capture_state 保持前值(可能缺失)——非歧义的 pending 席位仍会被单次捕获写成 pending_first_turn / pending_context_fork / transcript_missing，这不受 finalize 开关控制
+///   - progress 只报告不决策;是否继续由预算决定
+/// ---
 pub fn converge_missing_provider_sessions<F, M, P>(
     state: &mut Value,
     adapter_for: &mut F,
@@ -168,6 +225,25 @@ where
     }
 }
 
+/// ---
+/// purpose: 跑一趟捕获——为每个还缺权威会话的席位扫候选、经分配器定归属，把能确定的写成原子四元组，把不能确定的写成诊断态
+/// params:
+///   state: 就地修改的 state JSON;无 agents 对象时直接返回空报告
+///   adapter_for: provider → adapter 的工厂;扫描一律经 adapter
+///   finalize_ambiguous: false 时歧义只进报告不落盘;true 时才把 attribution_ambiguous / capture_state 写进 agent 行
+///   timeout_s: 传给 adapter.capture_session_candidates 的单席位扫描预算
+/// returns: CapturePassReport;changed 表示 state 被改过，调用方据此决定是否持久化
+/// errors: 当前实现不产生 Err(Result 签名为与调用方同形);取不到 agents 视图返回空报告;单席位扫描失败进 capture_failures 且该席位保持 pending，不中断整趟
+/// contract:
+///   provides:
+///     - name: capture_missing_provider_sessions_once
+///       what: 写权威四元组的唯一常规通道(另一条是 event-log 修复)
+/// boundary:
+///   - 候选的 embedded worker id 与本席位不符 → 记 identity_mismatch 并跳过，绝不写会话
+///   - 候选 session id 与 pending expected id 不符 → 记 ambiguous 并跳过，绝不写会话
+///   - _pending_session_id 与行上 session_id 不一致时不 stamp captured——重开在途，旧会话不得被宣告为新席位的权威
+///   - 不发事件;transcript_missing 只进报告
+/// ---
 pub fn capture_missing_provider_sessions_once<F>(
     state: &mut Value,
     adapter_for: &mut F,
@@ -317,12 +393,9 @@ where
             // partial candidates (no session_id or no rollout_path). When
             // it returns false, the row stays unchanged; capture re-runs
             // on the next coordinator tick.
-            if let Some(applied) = apply_captured_session(agent_obj, &candidate.captured) {
+            if apply_captured_session(agent_obj, &candidate.captured) {
                 report.changed = true;
                 report.assigned.push(item.agent_id);
-                if let AppliedCapture::ContextFork(context_fork) = applied {
-                    report.context_forks.push(context_fork);
-                }
             }
             continue;
         }
@@ -517,6 +590,19 @@ fn classify_pending_capture_state(
     }
 }
 
+/// ---
+/// purpose: 列出「provider 本可 resume、但会话事实还不完整」的席位——即捕获通道该继续照看的那批
+/// params:
+///   state: 只读的 state JSON;无 agents 对象时返回空
+/// returns: 按 agent id 升序的清单
+/// contract:
+///   provides:
+///     - name: incomplete_resumable_agent_ids
+///       what: 只读判定，不修改 state
+/// boundary:
+///   - 用全局 get_adapter 取 adapter，不接受注入——测试要替身请走 capture 通道那两个函数
+///   - 不区分「从没捕获过」与「捕获过但四元组残缺」，两者都在清单里
+/// ---
 pub fn incomplete_resumable_agent_ids(state: &Value) -> Vec<String> {
     let Some(agents) = state.get("agents").and_then(Value::as_object) else {
         return Vec::new();
@@ -535,6 +621,28 @@ pub fn incomplete_resumable_agent_ids(state: &Value) -> Vec<String> {
     out
 }
 
+/// ---
+/// purpose: 会话四元组缺失时的第二条修复通道——倒序翻 event log，用该席位最近一条可信的 session.captured 记录把行补全
+/// params:
+///   workspace: event log 所在工作区
+///   agent_id: 目标席位;事件的 agent_id 或 worker_id 命中即算该席位
+///   previous: 修复前的 agent 行;provider 字段决定要不要套 claude leader-marker 过滤
+///   adapter: 用于二次确认候选会话确实可 resume
+///   auth_mode: 传给 session_is_resumable 的鉴权模式
+///   exclude_session_ids: 调用方给出的黑名单(例如刚被判为不可用的会话)
+/// returns: Some(补好四元组的新行) 表示找到可用记录;None 表示没找到，或先撞上 discard.session_tombstone 而主动放弃
+/// errors: 读 event log 的 Io 错误、以及 session_is_resumable 的 ProviderError
+/// contract:
+///   provides:
+///     - name: recover_resume_session_from_events
+///       what: 修复结果一定是完整四元组;captured_at 缺事件 ts 时退到当前时间，captured_via 固定 event_log_repair
+/// boundary:
+///   - 只读 event log 与 rollout 路径存在性，不扫 provider 存档、不调分配器
+///   - 不走分配器的 claimed-key 冲突检查，只看 exclude_session_ids 与 tombstone
+///   - rollout_path 存在性用 exists()——对目录型 backing(grok/cursor)只要目录在就为真
+///   - claude 家族额外过滤 leader-marker transcript;其它 provider 无等价归属过滤
+///   - 修复成功会清掉 attribution_ambiguous 标记
+/// ---
 pub fn recover_resume_session_from_events(
     workspace: &Path,
     agent_id: &str,
@@ -651,6 +759,19 @@ fn event_rollout_path(event: &Value) -> Option<PathBuf> {
         .map(PathBuf::from)
 }
 
+/// ---
+/// purpose: 在「会话不完整」清单上再筛出真正被用过的席位——有 first_send_at 才算交互过
+/// params:
+///   state: 只读的 state JSON
+/// returns: 按 agent id 升序的子集
+/// contract:
+///   provides:
+///     - name: incomplete_interacted_resumable_agent_ids
+///       what: incomplete_resumable_agent_ids 的过滤视图，只读
+/// boundary:
+///   - 交互判据只看 first_send_at 非空，不看 last_result_at / pane 输出
+///   - 从没派过活的席位不进清单——沉默席位不算捕获失败
+/// ---
 pub fn incomplete_interacted_resumable_agent_ids(state: &Value) -> Vec<String> {
     let mut out = incomplete_resumable_agent_ids(state)
         .into_iter()
@@ -1170,11 +1291,6 @@ fn candidate_key(owner: &PendingSessionCapture, candidate: &CapturedSessionCandi
         .join("|")
 }
 
-enum AppliedCapture {
-    Session,
-    ContextFork(crate::lifecycle::launch::ContextForkFinalized),
-}
-
 /// 0.4.6 tuple-atomic contract (audit §Capture 修改清单, line 111): writes
 /// the authoritative session tuple if and only if the candidate carries
 /// BOTH `session_id` and `rollout_path`. A partial candidate (e.g.
@@ -1185,16 +1301,12 @@ enum AppliedCapture {
 fn apply_captured_session(
     agent_obj: &mut serde_json::Map<String, Value>,
     captured: &CapturedSession,
-) -> Option<AppliedCapture> {
-    if agent_obj.get("capture_state").and_then(Value::as_str) == Some("pending_context_fork") {
-        return crate::lifecycle::finalize_pending_fork_capture(agent_obj, captured)
-            .map(AppliedCapture::ContextFork);
-    }
+) -> bool {
     let Some(session_id) = captured.session_id.as_ref() else {
-        return None;
+        return false;
     };
     let Some(rollout_path) = captured.rollout_path.as_ref() else {
-        return None;
+        return false;
     };
     agent_obj.insert(
         "session_id".to_string(),
@@ -1224,7 +1336,7 @@ fn apply_captured_session(
     // diagnose/status observability.
     agent_obj.remove("_pending_session_id");
     agent_obj.insert("capture_state".to_string(), serde_json::json!("captured"));
-    Some(AppliedCapture::Session)
+    true
 }
 
 fn claimed_provider_session_keys(
@@ -1410,6 +1522,20 @@ pub(crate) mod test_support {
     }
 
     impl CaptureCandidatesAdapter {
+        /// ---
+        /// purpose: 造一个可控的测试替身 adapter:指定 provider，并可让某个席位的候选扫描必定失败
+        /// params:
+        ///   provider: 替身自称的 provider
+        ///   fail_agent_id: 该席位的 capture_session_candidates 返回错误;None 表示都不失败
+        ///   error: 失败时携带的错误文本
+        /// returns: 未挂候选表的替身;候选表另经 with_candidates 注入
+        /// contract:
+        ///   provides:
+        ///     - name: new
+        ///       what: 纯构造，无 I/O
+        /// boundary:
+        ///   - 仅 cfg(test) 存在，不进产品二进制
+        /// ---
         pub(crate) fn new(provider: Provider, fail_agent_id: Option<&str>, error: &str) -> Self {
             Self {
                 provider,
@@ -1419,6 +1545,18 @@ pub(crate) mod test_support {
             }
         }
 
+        /// ---
+        /// purpose: 给测试替身挂一张 agent_id → 候选列表的表，用来构造分配器层面的交叉归属回归
+        /// params:
+        ///   candidates_by_agent: 按席位 id 索引的候选;未列入的席位仍返回空列表
+        /// returns: 挂好表的自身(builder 风格，消费 self)
+        /// contract:
+        ///   provides:
+        ///     - name: with_candidates
+        ///       what: 只改替身内部状态，不触发任何扫描
+        /// boundary:
+        ///   - 仅 cfg(test) 存在，不进产品二进制
+        /// ---
         pub(crate) fn with_candidates(
             mut self,
             candidates_by_agent: BTreeMap<String, Vec<CapturedSessionCandidate>>,
@@ -2653,7 +2791,7 @@ mod u1_tests {
             spawn_cwd: PathBuf::from("/tmp/cwd"),
         };
         let written = super::apply_captured_session(&mut agent, &captured);
-        assert!(written.is_some(), "apply must accept valid captured");
+        assert!(written, "apply must accept valid captured");
         assert!(
             agent.get("_pending_session_id").is_none(),
             "S1-CAPTURE-001: _pending_session_id must be removed after capture \

package/crates/team-agent/src/provider/session/context_fork/claude.rs

@@ -1,6 +1,43 @@
-//!
+//! ---
+//! purpose: claude 家族的 fork 验证——在预算内轮询「精确快照路径」与「provider 侧 projects 路径」两处，任一处出现可读的新 backing 即出证明
+//! contract:
+//!   provides:
+//!     - name: verify_claude_fork
+//!       what: 双路径轮询验证，成功给 ContextForkProof(captured_via=context_fork_verified)
+//!   requires:
+//!     - name: crate::provider::session_scan::claude::projects_dir_for_cwd
+//!       what: 第二条探测路径由 HOME + spawn_cwd 推导出 ~/.claude/projects 下的目录
+//!     - name: super::ContextBackingSnapshot
+//!       what: 判「文件变过」的基线
+//! boundary:
+//!   - 只服务 Provider::Claude / ClaudeCode
+//!   - 文件名必须精确等于 <expected_session_id>.jsonl，不做同目录最新文件回落
+//!   - 不解析会话正文语义，只验「首行可解析 JSON」与「sessionId 记录(若有)一致」
+//!   - 未在 deadline 内满足条件即 Timeout，不降级放行
+//! maturity: wired
+//! ---
 use super::*;
 
+/// ---
+/// purpose: 轮询等待 claude fork 的新 transcript 落盘并验明身份
+/// params:
+///   provider: 写进证明的 provider 标记(Claude 或 ClaudeCode)
+///   source_session_id: 源会话;新会话等于它即不出证明
+///   plan: 必须带 expected_session_id，否则立即拒绝
+///   before: spawn 前基线，用于判 stamp 变化
+///   expected_backing_path: 必需的精确快照路径;文件名不等于 <expected>.jsonl 即拒绝
+///   spawn_cwd: 用于推导第二条 provider 侧探测路径
+///   deadline: 轮询预算，每轮间隔 50ms
+/// returns: 证明中 backing_path 是命中的那一条路径，attribution_confidence 固定 "high"
+/// errors: Rejected(CaptureFailed) 当 plan 缺 expected id / 缺快照路径 / 文件名不匹配;Timeout 当预算内两条路径都没满足
+/// contract:
+///   provides:
+///     - name: verify_claude_fork
+///       what: 只读文件元数据与首行/sessionId 记录，不写任何文件
+/// boundary:
+///   - 两条路径的严格程度不同:快照路径用 is_none_or(无 sessionId 记录时视为匹配)，provider 路径用 is_some_and(必须读到 sessionId)
+///   - 不排除 .team/logs/events.jsonl 之外的无关写入方——硬绑定只有「文件名等于 expected uuid」这一条
+/// ---
 pub(super) fn verify_claude_fork(
     provider: Provider,
     source_session_id: &SessionId,

package/crates/team-agent/src/provider/session/context_fork/codex.rs

@@ -1,4 +1,25 @@
-//!
+//! ---
+//! purpose: codex 的 fork 两件事——把源 rollout 改写成新身份的快照物化出来(materialize)，再验证 CLI 确实认领了它(verify)
+//! contract:
+//!   provides:
+//!     - name: materialize_codex_fork
+//!       what: 读源 rollout 完整记录 → 改 session_meta.id 与 worker 身份 marker → no-clobber 硬链接发布 → 读回自证 → 把 plan 从 `codex fork` 改写成 `codex resume <新 id>`
+//!     - name: CodexForkMaterialization
+//!       what: 物化产物的 RAII 句柄:未 handoff 就 Drop 时删除目标文件
+//!     - name: verify_codex_fork
+//!       what: 有 expected id 时按精确路径+embedded 身份认领;无 expected id 时退到 legacy「唯一变过的新 rollout」路径
+//!   requires:
+//!     - name: crate::provider::session_scan
+//!       what: 认领新 rollout 靠一次性候选扫描，不自己解析目录
+//!     - name: crate::provider::adapter::ForkBackingMaterialization
+//!       what: 句柄实现的对外 trait(path/handoff)
+//! boundary:
+//!   - 改写只动 session_meta.payload.id 与恰好一处 worker 身份 marker;二者数量不是恰好各 1 就整体拒绝，绝不部分改写
+//!   - 发布用 create_new 临时文件 + hard_link，绝不覆盖已存在的目标路径
+//!   - 只服务 Provider::Codex
+//!   - 新 session id 是本地生成的 uuid-v7 形状串，不问 CLI 要
+//! maturity: wired
+//! ---
 use super::*;
 use std::collections::BTreeSet;
 use std::fs::{File, OpenOptions};
@@ -11,6 +32,16 @@ pub(crate) struct CodexForkMaterialization {
 }
 
 impl CodexForkMaterialization {
+    /// ---
+    /// purpose: 暴露已物化的目标 rollout 路径，供调用方拼 resume 参数与做 fork 验证
+    /// returns: 物化目标文件的绝对路径;句柄还活着时该路径必然存在
+    /// contract:
+    ///   provides:
+    ///     - name: path
+    ///       what: 只借出路径，不转移所有权、不影响 Drop 时的删除决定
+    /// boundary:
+    ///   - 拿到路径不等于拿到保留承诺——不调 handoff 就仍会在 Drop 时被删
+    /// ---
     pub(crate) fn path(&self) -> &Path {
         &self.path
     }
@@ -38,6 +69,25 @@ impl Drop for CodexForkMaterialization {
     }
 }
 
+/// ---
+/// purpose: 为 codex fork 物化一份改写了会话身份的新 rollout，并把命令计划改成对该新会话的精确 resume
+/// params:
+///   source_path: 源 rollout 文件;新文件发布在它的同一父目录
+///   source_session_id: 源会话 id;源快照的 session_meta.payload.id 必须与之相等，否则拒绝
+///   source_agent_id: 源席位 id，用于定位待替换的 worker 身份 marker
+///   target_agent_id: 目标席位 id，替换后的 marker 内容，并参与读回自证
+///   plan: 就地改写;要求形如 `codex fork ... <source_session_id>`，会被改成 `codex resume ... <新 id>` 并设上 expected_session_id
+/// returns: RAII 句柄——未 handoff 即 Drop 时删除新文件，避免留下半成品存档
+/// errors: Io(源无父目录/源无完整 JSONL 记录/源某行非法 JSON/session_meta 缺 payload.id/id 与源不符/session_meta 或 marker 命中数不是恰好各 1/发布失败/读回身份不符);Command(plan 形状不是可转换的 codex fork)
+/// contract:
+///   provides:
+///     - name: materialize_codex_fork
+///       what: 写盘发生在此;读回校验失败会先删目标文件再返回错误
+/// boundary:
+///   - 只截到源文件最后一个换行处，绝不把半条正在写入的记录带进新快照
+///   - 不改源文件
+///   - 不启动进程、不调 codex CLI——只准备好 backing 与 argv
+/// ---
 pub(crate) fn materialize_codex_fork(
     source_path: &Path,
     source_session_id: &SessionId,
@@ -283,6 +333,27 @@ fn codex_session_v7() -> String {
     )
 }
 
+/// ---
+/// purpose: 验证 codex 已经在物化出来的那条 rollout 上开出了新会话，且该会话的 embedded 身份就是目标席位
+/// params:
+///   source_session_id: 源会话;目标等于它即拒绝
+///   plan: 无 expected_session_id 时整体退到 legacy 路径(靠「唯一一条变过的新 rollout」认领)
+///   before: spawn 前基线;legacy 路径用它排除源会话所在文件与未变文件
+///   expected_backing_path: 有 expected id 时必需——候选路径必须逐字节等于它，不做同目录择新
+///   agent_id: 候选的 embedded worker id 必须等于它，且 positive_agent_id_match 必须为真
+///   spawn_cwd: 构造扫描上下文
+///   spawned_at: 扫描的时间边界
+///   deadline: 轮询预算，每轮间隔 50ms
+/// returns: ContextForkProof，captured_via="context_fork_verified"、attribution_confidence="high"
+/// errors: Rejected(CaptureFailed) 当目标等于源 / 缺物化目标路径;Rejected 亦透传扫描期的 ProviderError;Timeout 当预算内没有满足全部条件的候选
+/// contract:
+///   provides:
+///     - name: verify_codex_fork
+///       what: 只读;认领判据是路径精确相等 + session id 等于 expected + embedded 身份等于 agent_id 三条同时成立
+/// boundary:
+///   - 不写 backing、不改 plan
+///   - legacy 路径(无 expected id)不做身份比对，只要求「不是源会话、不是基线里未变的文件、且全场恰好一条」——多于一条即不认领
+/// ---
 pub(super) fn verify_codex_fork(
     source_session_id: &SessionId,
     plan: &CommandPlan,

package/crates/team-agent/src/provider/session/context_fork/outcome.rs

@@ -1,4 +1,24 @@
-//!
+//! ---
+//! purpose: 把 verify_context_fork 的 Result 翻译成三态结局(Verified/Pending/Rejected)，并给 pending 态一条推进到失败的判据
+//! contract:
+//!   provides:
+//!     - name: ContextForkOutcome
+//!       what: fork 三态:Verified(带证明) / Pending(带可交回捕获通道的扫描上下文) / Rejected(provider 错误)
+//!     - name: PendingContextFork
+//!       what: 超时未验证时保留的续查材料:源会话 id、目标席位、spawned_at、CaptureSessionContext
+//!     - name: observe_context_fork
+//!       what: 调 verify_context_fork 并把 Timeout 折成 Pending 而不是错误
+//!     - name: transition_pending_context_fork
+//!       what: 纯判据——pending_context_fork 是否该被推进成 transcript_missing
+//!   requires:
+//!     - name: crate::provider::session_scan::CaptureSessionContext
+//!       what: Pending 携带的续查上下文类型
+//! boundary:
+//!   - 不轮询、不读磁盘;所有 I/O 都在被调用的 verify_context_fork 里
+//!   - 不写 state、不发事件——只产出结局值，落盘由捕获通道做
+//!   - Pending 不是成功也不是失败，绝不折进另外两态
+//! maturity: wired
+//! ---
 use super::*;
 
 #[derive(Debug, Clone)]
@@ -21,6 +41,20 @@ pub(crate) enum ContextForkPendingFailure {
     TranscriptMissing,
 }
 
+/// ---
+/// purpose: 判定一个停在 pending_context_fork 的席位是否该被改判为 transcript_missing
+/// params:
+///   triggered: 该席位是否已出现过触发事件(有过交互/结果/pane 输出)
+///   grace_expired: 宽限窗口是否已过
+/// returns: 两者同时为真才给 Some(TranscriptMissing);否则 None = 继续 pending
+/// contract:
+///   provides:
+///     - name: transition_pending_context_fork
+///       what: 纯布尔判据，无 I/O、无时钟
+/// boundary:
+///   - 不自己计算 triggered / grace_expired——两个事实由调用方(capture.rs)从 agent 行算好后传入
+///   - 只表达「该改判」，不负责写 capture_state
+/// ---
 pub(crate) fn transition_pending_context_fork(
     triggered: bool,
     grace_expired: bool,
@@ -28,6 +62,28 @@ pub(crate) fn transition_pending_context_fork(
     (triggered && grace_expired).then_some(ContextForkPendingFailure::TranscriptMissing)
 }
 
+/// ---
+/// purpose: 跑一次 fork 验证并把结果收敛成三态，超时不当错误而是留成可续查的 Pending
+/// params:
+///   provider: 转交 verify_context_fork 分派
+///   source_session_id: 源会话 id，同时写进 Pending 供后续比对
+///   plan: expected_session_id 与 provider_projects_root 会被复制进 Pending 的扫描上下文
+///   before: spawn 前 backing 基线
+///   expected_backing_path: 精确快照路径，透传
+///   source_agent_id: 透传给 verify_context_fork(当前该参数不参与判定)
+///   agent_id: 目标席位 id;既用于 codex 身份比对，也写进 Pending.target_agent
+///   spawn_cwd: 目标席位工作目录，透传并写进 Pending 的扫描上下文
+///   spawned_at: 时间边界，透传并写进 Pending
+///   deadline: 轮询预算
+/// returns: Verified(proof) / Pending(续查材料) / Rejected(ProviderError)
+/// contract:
+///   provides:
+///     - name: observe_context_fork
+///       what: 只做结果翻译与 Pending 材料装配，不新增任何判定
+/// boundary:
+///   - Pending 里的 CaptureSessionContext 一律 pane_id=None、pane_pid=None——本函数不掌握 pane 事实
+///   - 不重试、不写状态;是否再验由捕获通道决定
+/// ---
 pub(crate) fn observe_context_fork(
     provider: Provider,
     source_session_id: &SessionId,

package/crates/team-agent/src/provider/session/context_fork.rs

@@ -1,4 +1,29 @@
-//!
+//! ---
+//! purpose: context-fork 的验证总闸——按 provider 分派「新会话 backing 确实生成了」的证明，拿不到证明就超时或拒绝，绝不假绿
+//! contract:
+//!   provides:
+//!     - name: ContextBackingSnapshot
+//!       what: spawn 前对 provider backing 根下 .jsonl 的 (len, mtime) 基线快照，用于判「变过」
+//!     - name: verify_context_fork
+//!       what: 按 provider 路由到 copilot/codex/claude 三条验证路径，成功给 ContextForkProof
+//!     - name: context_fork_convergence_deadline
+//!       what: 每个 provider 各自的收敛预算(claude 45s / codex 10s / 其余 5s)
+//!     - name: ContextForkProof
+//!       what: 已验证的 fork 证明:新旧 session id、backing 路径、captured_via、归属置信度
+//!     - name: ContextForkTermination
+//!       what: 两种失败:Timeout(未在预算内看到新 backing) 与 Rejected(provider 侧错误)
+//!   requires:
+//!     - name: crate::provider::session_scan
+//!       what: codex 分支复用一次性候选扫描来认领新 rollout
+//!     - name: crate::provider::CommandPlan
+//!       what: expected_session_id 与 provider_projects_root 两个关键输入都来自 plan
+//! boundary:
+//!   - 只回答「fork 有没有产生一个可读的、不等于源会话的新 backing」，不回答会话内容对不对
+//!   - 不创建/改写 backing(codex 的物化改写在 context_fork/codex.rs，不在本文件)
+//!   - 未证明即 Timeout/Rejected，绝不退化成「假定成功」
+//!   - grok / cursor / gemini / fake 没有可验证 backing，一律直接 Rejected
+//! maturity: wired
+//! ---
 use std::collections::BTreeMap;
 use std::path::{Path, PathBuf};
 use std::time::{Duration, SystemTime};
@@ -27,12 +52,25 @@ pub(crate) use outcome::{
     observe_context_fork, transition_pending_context_fork, ContextForkOutcome, PendingContextFork,
 };
 
+/// ---
+/// purpose: 给出该 provider 等待 fork backing 落盘的收敛预算
+/// params:
+///   provider: 目标 provider;全枚举穷举，无兜底臂
+/// returns: Claude/ClaudeCode 45s、Codex 10s、其余(Copilot/Grok/CursorAgent/GeminiCli/Fake) 5s
+/// contract:
+///   provides:
+///     - name: context_fork_convergence_deadline
+///       what: 纯查表，不读时钟、不读磁盘
+/// boundary:
+///   - 只给预算数值，不负责在预算内轮询;超时语义由 ContextForkOutcome::Pending 承接
+/// ---
 pub(crate) fn context_fork_convergence_deadline(provider: Provider) -> Duration {
     // Expiration is consumed by ContextForkOutcome::Pending(PendingContextFork).
     match provider {
         Provider::Claude | Provider::ClaudeCode => Duration::from_secs(45),
         Provider::Codex => Duration::from_secs(10),
-        Provider::Copilot | Provider::GeminiCli | Provider::Fake => Duration::from_secs(5),
+        Provider::Copilot | Provider::Grok | Provider::CursorAgent | Provider::Pi | Provider::GeminiCli
+        | Provider::Fake => Duration::from_secs(5),
     }
 }
 
@@ -59,6 +97,20 @@ struct FileStamp {
 }
 
 impl ContextBackingSnapshot {
+    /// ---
+    /// purpose: 在 fork spawn 之前对 provider backing 根做一次 .jsonl 基线快照，事后据此判断哪些文件「变过」
+    /// params:
+    ///   provider: 决定 backing 根的默认位置(plan 未给 provider_projects_root 时按 HOME 推导)
+    ///   plan: 优先取 plan.provider_projects_root;隔离根存在时不碰用户全局目录
+    /// returns: 根下递归到底的 path → (len, modified) 映射;根不可读时是空映射，不报错
+    /// contract:
+    ///   provides:
+    ///     - name: capture
+    ///       what: 只读元数据(len+mtime)，不打开文件正文
+    /// boundary:
+    ///   - 只收 .jsonl 后缀;copilot 的 session-store.db 不在快照内，其证明走 sqlite 查询另算
+    ///   - 目录读失败静默跳过——快照是「变没变」的参照物，不是完整性断言
+    /// ---
     pub(crate) fn capture(provider: Provider, plan: &CommandPlan) -> Self {
         let root = provider_backing_root(provider, plan);
         let files = jsonl_files(&root);
@@ -66,6 +118,28 @@ impl ContextBackingSnapshot {
     }
 }
 
+/// ---
+/// purpose: fork 后按 provider 分派验证，只有拿到「新会话 backing 可读且不等于源会话」的实证才返回证明
+/// params:
+///   provider: 决定走 copilot(sqlite 行存在) / codex(候选扫描认领) / claude(轮询双路径) 三条路之一
+///   source_session_id: 被 fork 的源会话 id;新会话等于它即判失败
+///   plan: 提供 expected_session_id 与隔离 backing 根
+///   before: spawn 前的 ContextBackingSnapshot 基线，用于判「文件变过」
+///   expected_backing_path: 精确快照路径。claude 必需，缺失即拒绝;codex 仅在 plan 带 expected id 时必需(无 expected id 走 legacy「唯一变过的新 rollout」认领，可为 None);两者都不做同目录猜测
+///   spawn_cwd: codex 分支据此构造扫描上下文;claude 分支据此推导 provider 侧 projects 目录
+///   spawned_at: codex 候选扫描的时间边界
+///   deadline: 轮询预算，来自 context_fork_convergence_deadline
+/// returns: ContextForkProof——新旧 session id、backing 路径、captured_via、attribution_confidence
+/// errors: Timeout 表示预算内没看到可验证的新 backing;Rejected 包装 ProviderError(缺 expected id、路径不匹配、无可验证 backing 的 provider)
+/// contract:
+///   provides:
+///     - name: verify_context_fork
+///       what: 分派 + 兜底拒绝;本函数自身不轮询，轮询在各 provider 分支内
+/// boundary:
+///   - 不修改 backing、不写 state、不发事件
+///   - _source_agent_id 当前不参与任何判定(仅 codex 用 agent_id 做 embedded 身份比对)
+///   - 未列入三条路径的 provider 一律 CaptureFailed，绝不返回「无法验证但放行」
+/// ---
 pub(crate) fn verify_context_fork(
     provider: Provider,
     source_session_id: &SessionId,
@@ -178,7 +252,8 @@ fn provider_backing_root(provider: Provider, plan: &CommandPlan) -> PathBuf {
         Provider::Claude | Provider::ClaudeCode => home.join(".claude").join("projects"),
         Provider::Codex => home.join(".codex").join("sessions"),
         Provider::Copilot => home.join(".copilot").join("session-state"),
-        Provider::GeminiCli | Provider::Fake => home,
+        Provider::Pi => PathBuf::new(),
+        Provider::Grok | Provider::CursorAgent | Provider::GeminiCli | Provider::Fake => home,
     }
 }
 

package/crates/team-agent/src/provider/session/mod.rs

@@ -1,3 +1,21 @@
+//! ---
+//! purpose: provider 会话域的命名空间——把「捕获 / resume 拒绝判定 / context-fork」三块聚合成一个出口
+//! contract:
+//!   provides:
+//!     - name: capture
+//!       what: pending id → 扫描候选 → 分配 → 写会话四元组的捕获通道(pub 子模块)
+//!     - name: resume
+//!       what: ResumeRefusalReason 闭合枚举与 RecoveryHint(pub 子模块)
+//!     - name: ContextForkProof
+//!       what: context-fork 验证通过后的证明结构，由私有 context_fork 子模块 re-export
+//!   requires:
+//!     - name: crate::provider::session_scan
+//!       what: 磁盘候选扫描不在本命名空间内实现，由 session_scan 提供
+//! boundary:
+//!   - 只做子模块聚合与 re-export，本文件不含任何逻辑
+//!   - 不决定何时重启/销毁席位——那是 lifecycle 的判断
+//! maturity: wired
+//! ---
 //!
 //! unit-6 (Stage 2) — provider session namespace.
 //!