@team-agent/installer 0.5.65 → 0.5.68

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::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,7 @@ 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::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.
 //!

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

@@ -1,3 +1,26 @@
+//! ---
+//! purpose: 把 restart resume 门的「为什么拒绝」从两个不透明字符串升级成闭合枚举，并携带操作者可用的恢复线索
+//! contract:
+//!   provides:
+//!     - name: ResumeRefusalReason
+//!       what: resume 拒绝原因闭合枚举(7 变体)，新原因必须改代码才能加
+//!     - name: wire
+//!       what: 枚举 → 历史 UnresumableWorker.reason 稳定串，供 JSON/日志沿用旧形状
+//!     - name: from_legacy
+//!       what: 历史字符串 → 枚举的逆映射，未识别串一律落进 Other{legacy_reason}
+//!     - name: RecoveryHint
+//!       what: 缺 backing 时给操作者的 provider/name/cwd 三元线索
+//!     - name: picker_hint
+//!       what: 把 RecoveryHint 渲染成一行人读文本
+//!   requires:
+//!     - name: std::path::PathBuf
+//!       what: checked_paths 与 spawn_cwd 的载体
+//! boundary:
+//!   - 只做「原因的分类与措辞」：不探测 backing 是否存在，不读磁盘，不发事件
+//!   - RecoveryHint 只呈现给人，绝不被自动 resume 消费(自动恢复需 Layer 3 多键过滤+backing 复验)
+//!   - 判定 resume 是否可行的调用点在 lifecycle/restart，不在本文件
+//! maturity: wired
+//! ---
 //!
 //! unit-5 (Stage 2) — closed `ResumeRefusalReason` enum and recovery hints.
 //!
@@ -47,6 +70,16 @@ impl RecoveryHint {
     /// Build a human-readable picker hint (one line). Layer 2 surfaces
     /// this in the CLI refusal message and in the
     /// `session.recovery.candidate_hint` event payload.
+    /// ---
+    /// purpose: 把 provider/name/cwd 三元线索拼成一行人读文本，供 CLI 拒绝信息与事件载荷使用
+    /// returns: 四种措辞之一，按 name/cwd 各自是否存在退化;两者都缺时退到 "<provider> session"
+    /// contract:
+    ///   provides:
+    ///     - name: picker_hint
+    ///       what: 纯格式化，不查磁盘、不校验 cwd 是否还在
+    /// boundary:
+    ///   - 输出只给人看，不做机器解析的契约，调用方不得据此自动 resume
+    /// ---
     pub fn picker_hint(&self) -> String {
         match (&self.provider_session_name_hint, &self.spawn_cwd) {
             (Some(name), Some(cwd)) => format!(
@@ -118,6 +151,17 @@ impl ResumeRefusalReason {
     /// `UnresumableWorker.reason` values. Use this when emitting JSON or
     /// log fields so downstream consumers see the same strings they
     /// always have.
+    /// ---
+    /// purpose: 把结构化拒绝原因压回历史 UnresumableWorker.reason 稳定串
+    /// returns: 六个 canonical 串之一;Other 一律折回 "session_unresumable"——未 taxonomize 的新失败类型对外与历史大杂烩不可区分
+    /// contract:
+    ///   provides:
+    ///     - name: wire
+    ///       what: 枚举 → 稳定串的全函数映射，不丢字段但丢细节
+    /// boundary:
+    ///   - 不携带 checked_paths / recovery_hint / drift 的 expected-actual 等负载，只给分类名
+    ///   - 与 from_legacy 只在五个 canonical 串上互逆;SessionDrift 有 wire 串但 from_legacy 无对应臂，"session_drift" 会落进 Other，该变体不可往返
+    /// ---
     pub fn wire(&self) -> &'static str {
         match self {
             ResumeRefusalReason::NoSessionId => "no_persisted_session_id",
@@ -136,6 +180,19 @@ impl ResumeRefusalReason {
 
     /// Lift a legacy free-form `reason` string into the structured enum.
     /// Round-trip-safe with `wire()` for the canonical names.
+    /// ---
+    /// purpose: 把历史自由串抬升成结构化枚举，保证旧持久化数据不丢分类
+    /// params:
+    ///   reason: 历史 UnresumableWorker.reason 串;不在识别表内的任意值都合法
+    /// returns: 匹配到的变体(负载字段一律填空，因为串里没有这些事实);未匹配则 Other{legacy_reason=原串}
+    /// contract:
+    ///   provides:
+    ///     - name: from_legacy
+    ///       what: 全函数、不失败、不 panic 的逆映射
+    /// boundary:
+    ///   - 不还原 checked_paths / recovery_hint / provider 名等负载——它们在串里本就不存在
+    ///   - 识别表缺 "session_drift" 臂，该串会落到 Other 而非 SessionDrift
+    /// ---
     pub fn from_legacy(reason: &str) -> Self {
         match reason {
             "no_persisted_session_id" => ResumeRefusalReason::NoSessionId,

package/crates/team-agent/src/provider/session_scan/claude.rs

@@ -1,4 +1,33 @@
-//!
+//! ---
+//! purpose: claude 家族的会话归属过滤——按 expected id 直达 ~/.claude/projects/<编码 cwd>/<sid>.jsonl 读头验身份，并为通用扫描提供 leader-transcript 与 cwd 字段两道排除判据
+//! contract:
+//!   provides:
+//!     - name: projects_dir_for_cwd
+//!       what: 由 HOME + spawn_cwd 推出 claude 的 projects 目录(非字母数字字符一律替成 '-')
+//!     - name: encode_projects_dir
+//!       what: claude 的目录名编码规则本身
+//!     - name: scan_expected_session
+//!       what: 有 pending id 时的直达捕获:读头 64KB，验 sessionId 一致 + 有 user/assistant 记录 + 无 leader marker + 有 cwd 字段，四条全过才出候选
+//!     - name: rollout_path_has_leader_marker
+//!       what: 判某条 transcript 是不是 leader 的(customTitle/agentName == "claude leader")
+//!     - name: records_have_leader_marker
+//!       what: 上一条的记录级判据
+//!     - name: has_cwd_field
+//!       what: 记录里有没有 cwd 字段——claude transcript 的最低可信度门槛
+//!     - name: apply_expected_session_filter
+//!       what: 通用扫描结果的收窄:expected 命中则独取，未命中则只留身份/路径阳性的
+//!   requires:
+//!     - name: super::common
+//!       what: 读头、解析记录、embedded 身份、时间窗过滤都复用 common
+//!     - name: crate::provider::helpers::find_session_id
+//!       what: 从记录里取 sessionId 的统一入口
+//! boundary:
+//!   - 只服务 Provider::Claude / ClaudeCode;rollout_path_has_leader_marker 对其它 provider 恒 false
+//!   - 不写盘、不改 state、不发事件
+//!   - 直达路径不做同 cwd「最新文件」回落——有 pending id 就只认那一个文件名
+//!   - leader transcript 一律排除，防止 worker 席位绑上 leader 的会话
+//! maturity: wired
+//! ---
 use std::path::{Path, PathBuf};
 
 use crate::provider::helpers::find_session_id;
@@ -7,6 +36,20 @@ use crate::provider::Provider;
 
 use super::{CaptureSessionContext, CapturedSessionCandidate};
 
+/// ---
+/// purpose: 由 HOME 与席位 cwd 推出 claude 存放该工作目录 transcript 的 projects 子目录
+/// params:
+///   home: HOME 根;调用方决定是真实 HOME 还是隔离根
+///   spawn_cwd: 席位工作目录;先 canonicalize，失败则原样使用
+/// returns: <home>/.claude/projects/<编码后的 cwd>;编码结果为空串时 None
+/// contract:
+///   provides:
+///     - name: projects_dir_for_cwd
+///       what: 只拼路径，不创建目录、不判存在性
+/// boundary:
+///   - 不枚举目录内容、不读任何文件
+///   - canonicalize 失败不报错,退回原路径——编码结果因此可能与 claude 实际用的目录不同
+/// ---
 pub(crate) fn projects_dir_for_cwd(home: &Path, spawn_cwd: &Path) -> Option<PathBuf> {
     let canonical = std::fs::canonicalize(spawn_cwd).unwrap_or_else(|_| spawn_cwd.to_path_buf());
     let encoded = encode_projects_dir(&canonical.to_string_lossy());
@@ -16,6 +59,19 @@ pub(crate) fn projects_dir_for_cwd(home: &Path, spawn_cwd: &Path) -> Option<Path
     Some(home.join(".claude").join("projects").join(encoded))
 }
 
+/// ---
+/// purpose: 复刻 claude 的 projects 目录名编码:非 ASCII 字母数字的字符一律替成单个 '-'
+/// params:
+///   path: 待编码的路径文本
+/// returns: 等长的编码串;输入为空则空串
+/// contract:
+///   provides:
+///     - name: encode_projects_dir
+///       what: 纯字符映射，逐字符一对一，不折叠连续分隔符
+/// boundary:
+///   - 有损且不可逆:不同路径可以编出同一个目录名
+///   - 不做长度截断、不做大小写归一
+/// ---
 pub(super) fn encode_projects_dir(path: &str) -> String {
     let mut out = String::with_capacity(path.len());
     for c in path.chars() {
@@ -28,6 +84,21 @@ pub(super) fn encode_projects_dir(path: &str) -> String {
     out
 }
 
+/// ---
+/// purpose: 有 pending id 时直达那一个 transcript 文件，读头验明身份后给出唯一候选
+/// params:
+///   context: 需要 expected_session_id;projects 根优先取 provider_projects_root，否则退到 HOME/.claude/projects;spawn_cwd 决定编码后的子目录
+/// returns: 四道校验全过则一条 FsWatch/High 候选(带 embedded 身份与是否与本席位一致);任一条不过则空向量
+/// contract:
+///   provides:
+///     - name: scan_expected_session
+///       what: 只读该文件头 64KB;不遍历目录、不比较 mtime
+/// boundary:
+///   - 无 expected_session_id / 无法确定 projects 根 / 编码为空 / 文件读不出来 → 空向量
+///   - 四道校验:sessionId 与 expected 相等、存在 user 或 assistant 记录、不含 leader marker、至少一条记录有 cwd 字段
+///   - embedded 身份与本席位不符时仍返回候选(positive_agent_id_match=false)，是否拒绝交给上游分配器判定
+///   - agent_path_match 恒 false:直达路径下文件名就是 uuid，不含席位名
+/// ---
 pub(super) fn scan_expected_session(
     context: &CaptureSessionContext,
 ) -> Vec<CapturedSessionCandidate> {
@@ -87,6 +158,20 @@ pub(super) fn scan_expected_session(
     }]
 }
 
+/// ---
+/// purpose: 判断一条 transcript 是不是 leader 的会话，供捕获与 event-log 修复两条通道共用排除
+/// params:
+///   provider: 非 Claude/ClaudeCode 一律直接判否
+///   rollout_path: 待判定的 transcript 路径
+/// returns: 读得到头且头部记录里出现 leader marker 才为 true
+/// contract:
+///   provides:
+///     - name: rollout_path_has_leader_marker
+///       what: 只读头 64KB
+/// boundary:
+///   - 文件打不开、解析不出记录一律返回 false —— 判据是 fail-open 的:读不到不等于不是 leader
+///   - marker 只在头窗口内查;超出 64KB 之后才出现的 marker 看不见
+/// ---
 pub(crate) fn rollout_path_has_leader_marker(provider: Provider, rollout_path: &Path) -> bool {
     if !matches!(provider, Provider::Claude | Provider::ClaudeCode) {
         return false;
@@ -99,6 +184,18 @@ pub(crate) fn rollout_path_has_leader_marker(provider: Provider, rollout_path: &
     records_have_leader_marker(&records)
 }
 
+/// ---
+/// purpose: 在已解析的记录里找 leader 身份 marker
+/// params:
+///   records: 已解析的 transcript 记录切片
+/// returns: 任一记录的 customTitle 或 agentName 小写后等于 "claude leader" 即 true
+/// contract:
+///   provides:
+///     - name: records_have_leader_marker
+///       what: 纯内存判定，无 I/O
+/// boundary:
+///   - 判据是精确串相等(仅大小写不敏感)，不做包含匹配、不认其它别名
+/// ---
 pub(super) fn records_have_leader_marker(records: &[serde_json::Value]) -> bool {
     records.iter().any(|record| {
         let custom_title = record
@@ -114,10 +211,37 @@ pub(super) fn records_have_leader_marker(records: &[serde_json::Value]) -> bool
     })
 }
 
+/// ---
+/// purpose: 判断一条 claude 记录是否带 cwd 字段——用作 transcript 是否够格当候选的最低门槛
+/// params:
+///   record: 单条已解析记录
+/// returns: common::record_cwd 能取到值即 true
+/// contract:
+///   provides:
+///     - name: has_cwd_field
+///       what: 只判字段有无，不比较 cwd 是否等于席位 cwd
+/// boundary:
+///   - 不做路径等价判定;是否同 cwd 由调用方另行判断
+/// ---
 pub(super) fn has_cwd_field(record: &serde_json::Value) -> bool {
     super::common::record_cwd(record).is_some()
 }
 
+/// ---
+/// purpose: 用 pending id 收窄通用扫描的结果，把「可能是它」压成「就是它」或「至少身份阳性」
+/// params:
+///   context: 有 expected_session_id 才做收窄;否则退到时间窗过滤
+///   out: 待收窄的候选列表，按值传入
+/// returns: expected 命中则只留那一条;未命中则只留 positive_agent_id_match 或 agent_path_match 为真的;无 expected 则原表经唯一时间窗过滤后返回
+/// errors: 当前实现不产生 Err;返回 Result 是为与其它 provider 过滤器同形
+/// contract:
+///   provides:
+///     - name: apply_expected_session_filter
+///       what: 纯过滤，不读盘(时间窗分支会取候选文件 mtime)
+/// boundary:
+///   - 未命中 expected 时不返回空而是返回身份阳性子集——弱于「必须命中」，允许分配器再判
+///   - 不排序;expected 优先排序由 common::sort_expected_first_if_needed 另做
+/// ---
 pub(super) fn apply_expected_session_filter(
     context: &CaptureSessionContext,
     mut out: Vec<CapturedSessionCandidate>,

package/crates/team-agent/src/provider/session_scan/codex.rs

@@ -1,10 +1,61 @@
-//!
+//! ---
+//! purpose: codex rollout 的时间与归属过滤——用「创建时间」而非 mtime 判新旧，用 rollout 头里的 cwd 判是不是本席位的
+//! contract:
+//!   provides:
+//!     - name: parse_spawned_at
+//!       what: RFC3339 文本 → SystemTime，解析不了给 None(调用方据此 fail-closed 清空候选)
+//!     - name: truncate_to_uuid_precision
+//!       what: 把时间截到毫秒，与 uuid-v7 里能表达的精度对齐，避免亚毫秒误差把自己的会话判成"太旧"
+//!     - name: rollout_created_at
+//!       what: 三级取创建时间:uuid-v7 时间戳 → 头记录 created_at → 文件名里的时间戳
+//!     - name: apply_expected_session_filter
+//!       what: 有 pending id 时只留 session id 精确相等的候选
+//!     - name: retain_spawn_cwd
+//!       what: 只留 rollout 头记录里 cwd 与席位 spawn_cwd 等价的候选
+//!   requires:
+//!     - name: super::common
+//!       what: 读头、解析记录、record_cwd、paths_equivalent 均复用 common
+//!     - name: chrono
+//!       what: RFC3339 解析
+//! boundary:
+//!   - 只服务 Provider::Codex
+//!   - 一律只读:不写盘、不改 plan、不改 state
+//!   - 创建时间刻意不取文件 mtime——邻席活动会抬升 mtime，把别人的会话冒充成新的
+//!   - 头窗口之外的记录读不到;三级取值全失败时 rollout_created_at 给 None，调用方按"不通过"处理
+//! maturity: wired
+//! ---
+/// ---
+/// purpose: 把持久化在 state 上的 spawned_at 文本解析成时间点
+/// params:
+///   raw: RFC3339 时间串
+/// returns: 解析成功给 UTC SystemTime;失败给 None
+/// contract:
+///   provides:
+///     - name: parse_spawned_at
+///       what: 纯解析，无 I/O、不读系统时钟
+/// boundary:
+///   - 只认 RFC3339;不接受 epoch 秒、不做宽松格式回落
+///   - 返回 None 的处置由调用方定:common::apply_spawned_at_filter 选择清空候选(fail-closed)
+/// ---
 pub(super) fn parse_spawned_at(raw: &str) -> Option<std::time::SystemTime> {
     chrono::DateTime::parse_from_rfc3339(raw)
         .ok()
         .map(|dt| std::time::SystemTime::from(dt.with_timezone(&chrono::Utc)))
 }
 
+/// ---
+/// purpose: 把时间点截到毫秒，与 uuid-v7 能表达的精度对齐
+/// params:
+///   timestamp: 待截断的时间点
+/// returns: 同一毫秒的起点;早于 UNIX 纪元或毫秒数溢出 u64 时 None
+/// contract:
+///   provides:
+///     - name: truncate_to_uuid_precision
+///       what: 纯算术，无 I/O
+/// boundary:
+///   - 只向下截断，绝不向上取整——否则会把自己刚开的会话判成"早于 spawn"
+///   - 只在「Codex 且有 expected id」的比较里使用，不是通用时间归一
+/// ---
 pub(super) fn truncate_to_uuid_precision(
     timestamp: std::time::SystemTime,
 ) -> Option<std::time::SystemTime> {
@@ -16,12 +67,40 @@ pub(super) fn truncate_to_uuid_precision(
     ))
 }
 
+/// ---
+/// purpose: 取 codex rollout 的创建时间，作为「这条存档是不是本次 spawn 之后产生的」的判据
+/// params:
+///   path: rollout 文件路径
+/// returns: 三级依次尝试:文件名尾部 uuid-v7 的时间戳 → 头记录里的 created_at → 文件名中的时间戳;全失败给 None
+/// contract:
+///   provides:
+///     - name: rollout_created_at
+///       what: 只读文件名与头 64KB
+/// boundary:
+///   - 刻意不取文件 mtime:mtime 会被后续追加与邻席活动抬升，不是创建时间
+///   - uuid 分支要求版本位为 '7';非 v7 的 uuid 直接落到下一级
+///   - 返回 None 时调用方按"不满足时间窗"处理，不做放行
+/// ---
 pub(super) fn rollout_created_at(path: &std::path::Path) -> Option<std::time::SystemTime> {
     created_at_from_rollout_uuid(path)
         .or_else(|| created_at_from_rollout_head(path))
         .or_else(|| created_at_from_rollout_filename(path))
 }
 
+/// ---
+/// purpose: 有 pending id 时把候选收窄到 session id 精确相等的那些
+/// params:
+///   context: 无 expected_session_id 时原样返回，不做任何过滤
+///   out: 候选列表，按值传入并就地 retain
+/// returns: 过滤后的候选;无一条命中则空向量
+/// contract:
+///   provides:
+///     - name: apply_expected_session_filter
+///       what: 纯内存过滤，无 I/O
+/// boundary:
+///   - 判据是 session id 全等;session_id 为 None 的候选一律剔除
+///   - 与 claude 同名函数语义不同:此处未命中即空，不退到"身份阳性子集"
+/// ---
 pub(super) fn apply_expected_session_filter(
     context: &super::CaptureSessionContext,
     mut out: Vec<super::CapturedSessionCandidate>,
@@ -39,6 +118,20 @@ pub(super) fn apply_expected_session_filter(
     out
 }
 
+/// ---
+/// purpose: 只保留 rollout 头里记着的 cwd 与本席位 spawn_cwd 等价的候选，挡掉其它工作目录的会话
+/// params:
+///   context: 提供 spawn_cwd 基准
+///   out: 就地过滤的候选列表
+/// contract:
+///   provides:
+///     - name: retain_spawn_cwd
+///       what: 逐个候选读头 64KB 后比对 cwd
+/// boundary:
+///   - 无 rollout_path、读不出头、头里一条 cwd 都没有 → 剔除(fail-closed)
+///   - 等价判定走 common::paths_equivalent，它把「记录 cwd 的父目录等于 spawn_cwd」也算等价
+///   - 只看头窗口内的记录;窗口之外的 cwd 记录看不见
+/// ---
 pub(super) fn retain_spawn_cwd(
     context: &super::CaptureSessionContext,
     out: &mut Vec<super::CapturedSessionCandidate>,