@team-agent/installer 0.5.66 → 0.5.68

package/crates/team-agent/src/provider/adapters/cursor_agent.rs

@@ -0,0 +1,86 @@
+//! ---
+//! purpose: Cursor agent CLI argv；role 走 .cursor/rules，MCP 走 mcp.json overlay
+//! contract:
+//!   provides:
+//!     - name: cursor_agent_base_command
+//!       what: 只组已实测文档化 flag；mcp_config 不入 argv，由 launch overlay 写盘
+//! boundary:
+//!   - 不调未文档化 flag（--system-prompt / --allowed-tools）
+//!   - 不写 grok 那种 cwd 独占闸
+//!   - 不打印代理值
+//! maturity: wired
+//! ---
+//!
+//! Cursor `agent` CLI（与 `cursor-agent` 同二进制）。主路径与
+//! `.team/scripts/cursor_seat.sh` 实测一致：
+//!   `--trust --sandbox disabled --workspace <物理路径> [--force] [--model]`
+//! Role 不入 argv，写 `<workspace>/.cursor/rules/*.mdc` + `alwaysApply: true`。
+//! MCP 无 `--mcp-config`；身份必须写进 `.cursor/mcp.json` 的 env 表
+//! （cursor 不把父进程 TEAM_AGENT_* 传给 MCP 子进程）。
+//!
+//! 隐藏 flag `--system-prompt` / `--allowed-tools` 实测存在但 help 未列，
+//! 随时可能消失。可以在注释里记录，代码里不许调。
+//! `--allowed-tools` 正反行为未验证，不写「支持工具白名单」。
+
+use crate::model::enums::AuthMode;
+use crate::provider::adapter::BasicProviderAdapter;
+use crate::provider::{McpConfig, ProviderError};
+
+pub(crate) fn cursor_agent_launch_command(
+    adapter: &BasicProviderAdapter,
+    auth_mode: AuthMode,
+    mcp_config: Option<&McpConfig>,
+    system_prompt: Option<&str>,
+    model: Option<&str>,
+    tools: &[&str],
+) -> Result<Vec<String>, ProviderError> {
+    cursor_agent_base_command(
+        adapter,
+        auth_mode,
+        mcp_config,
+        system_prompt,
+        model,
+        tools,
+        false,
+        None,
+    )
+}
+
+pub(crate) fn cursor_agent_base_command(
+    adapter: &BasicProviderAdapter,
+    auth_mode: AuthMode,
+    mcp_config: Option<&McpConfig>,
+    system_prompt: Option<&str>,
+    model: Option<&str>,
+    tools: &[&str],
+    managed_mcp_config: bool,
+    effort: Option<crate::model::enums::ProviderEffort>,
+) -> Result<Vec<String>, ProviderError> {
+    let mut argv = vec!["agent".to_string()];
+    // --trust 跳过 Workspace Trust 闸（已实测）。无此 flag 会停在 Do you trust。
+    argv.push("--trust".to_string());
+    if cursor_agent_dangerous_auto_approve(tools) {
+        argv.push("--force".to_string());
+    }
+    // 与 cursor_seat.sh 主路径一致。沙箱实际隔离面未再拆，但 flag 本身已实测。
+    argv.push("--sandbox".to_string());
+    argv.push("disabled".to_string());
+    if let Some(model) = model {
+        argv.push("--model".to_string());
+        argv.push(model.to_string());
+    }
+    // Cursor `--effort` flag 不存在；框架在调用方丢掉 effort。绝不发明 flag。
+    let _ = effort;
+    // system_prompt 不入 argv（help 无 --rules / --append-system-prompt）。
+    // launch 写 `<workspace>/.cursor/rules/team-agent-role-<agent_id>.mdc`。
+    // mcp_config 也不入 argv（无 --mcp-config）。launch 写 `.cursor/mcp.json`
+    // 并 `agent mcp enable team_orchestrator`。这里收下以免静默丢弃。
+    let _ = (adapter, auth_mode, mcp_config, managed_mcp_config, system_prompt);
+    argv.push("--workspace".to_string());
+    argv.push("{workspace}".to_string());
+    Ok(argv)
+}
+
+pub(crate) fn cursor_agent_dangerous_auto_approve(tools: &[&str]) -> bool {
+    tools.contains(&"dangerous_auto_approve")
+}

package/crates/team-agent/src/provider/adapters/grok.rs

@@ -0,0 +1,157 @@
+//!
+//! purpose: Grok CLI argv + permission deny 映射；MCP 不走 CLI flag
+//! contract: launch 写 `<cwd>/.grok/config.toml`；未登录 / 目录未信任必须拒绝启动。
+//!   角色缺 model 必须拒绝启动（禁止内建 / team / CLI 任何隐式默认）。
+//!   未知工具映射记成 Unsupported，不发明 deny 名
+//! mcp_injection: dir_scoped —— 每席必须独立工作目录；同 cwd 多席会静默串台，故拒绝。
+//!   对照 claude/codex 是 argv 作用域（`--mcp-config`），同目录多席没有这个问题。
+//!   本版 exclusive 检查不读 per-agent cwd，一个 workspace 只支持一个 grok 席。
+//!   这是 Provider::Grok 的能力边界，不是框架对所有 provider 的限制。
+//! boundary: 只服务 Provider::Grok。不改 claude/codex/copilot 路径
+//!
+//! Grok CLI provider-local command builders + permission helpers.
+//!
+//! Mirrors `adapters/claude.rs` (0.5.67 provider-adapter step). Pure
+//! flag-name adaptation over the claude skeleton — no new abstraction
+//! layers, no public-API changes outside the provider dispatch.
+//!
+//! Grok CLI flag map (亲核 attest 0.5.67 + grok-full-help.txt):
+//!   bypass  → `--always-approve`  ("Auto-approve all tool executions")
+//!   system  → `--rules <RULES>`   ("Extra rules to append to the system prompt")
+//!   model   → `-m, --model <MODEL>`
+//!   session → `-s, --session-id <SESSION_ID>` (fresh spawn)
+//!   resume  → `-r, --resume [<ID_OR_TITLE>]` / `-c, --continue`
+//!   fork    → `--fork-session` (with --resume)
+//!   effort  → `--effort <level>` (alias of `--reasoning-effort`)
+//!             grok accepts low|medium|high|xhigh; CLI rejects `max`
+//!   deny    → `--disallowed-tools` (compat alias `--disallowedTools`)
+//!   cwd     → `--cwd <CWD>` / `-w, --worktree [<WORKTREE>]`
+//!
+//! No native `--mcp-config` flag on the Grok CLI (`grok mcp` is a subcommand)
+//! → `native_mcp_config: false`; MCP reaches the worker via launch-path
+//! `<cwd>/.grok/config.toml` (`apply_grok_mcp_overlay`).
+
+use crate::model::enums::AuthMode;
+use crate::provider::adapter::{next_session_token, BasicProviderAdapter};
+use crate::provider::{McpConfig, ProviderError};
+
+pub(crate) fn grok_launch_command(
+    adapter: &BasicProviderAdapter,
+    auth_mode: AuthMode,
+    mcp_config: Option<&McpConfig>,
+    system_prompt: Option<&str>,
+    model: Option<&str>,
+    tools: &[&str],
+) -> Result<Vec<String>, ProviderError> {
+    let mut argv = grok_base_command(
+        adapter,
+        auth_mode,
+        mcp_config,
+        system_prompt,
+        model,
+        tools,
+        false,
+        None,
+    )?;
+    argv.push("--session-id".to_string());
+    argv.push(next_session_token());
+    Ok(argv)
+}
+
+pub(crate) fn grok_base_command(
+    adapter: &BasicProviderAdapter,
+    auth_mode: AuthMode,
+    mcp_config: Option<&McpConfig>,
+    system_prompt: Option<&str>,
+    model: Option<&str>,
+    tools: &[&str],
+    managed_mcp_config: bool,
+    effort: Option<crate::model::enums::ProviderEffort>,
+) -> Result<Vec<String>, ProviderError> {
+    let mut argv = vec!["grok".to_string()];
+    if grok_dangerous_auto_approve(tools) {
+        argv.push("--always-approve".to_string());
+    }
+    let model = match model.map(str::trim).filter(|value| !value.is_empty()) {
+        Some(model) => model,
+        None => {
+            return Err(ProviderError::Command(
+                "grok launch requires an explicit model. \
+Without an explicit model the framework fills a built-in default (grok-4 for grok), \
+so the seat silently gets a model and context window that are not in the role file, \
+while argv still looks normal. The role file must name the model itself; \
+built-in defaults, team-level defaults, and the Grok CLI global default are all implicit sources. \
+Set the role front-matter field, for example:\n\
+model: grok-4.6"
+                    .to_string(),
+            ));
+        }
+    };
+    argv.push("--model".to_string());
+    argv.push(model.to_string());
+    if let Some(effort) = effort {
+        // Grok accepts `--effort` as alias for `--reasoning-effort`.
+        argv.push("--effort".to_string());
+        argv.push(effort.as_str().to_string());
+    }
+    if let Some(prompt) = system_prompt {
+        argv.push("--rules".to_string());
+        argv.push(prompt.to_string());
+    }
+    // Grok CLI has no `--mcp-config` flag — the claude inline-MCP block is
+    // intentionally absent. Launch writes `<cwd>/.grok/config.toml`.
+    let _ = (adapter, auth_mode, mcp_config, managed_mcp_config);
+    for tool in grok_disallowed_tools(tools) {
+        argv.push("--disallowedTools".to_string());
+        argv.push(tool.to_string());
+    }
+    Ok(argv)
+}
+
+pub(crate) fn grok_dangerous_auto_approve(tools: &[&str]) -> bool {
+    tools.contains(&"dangerous_auto_approve")
+}
+
+pub(crate) fn grok_disallowed_tools(tools: &[&str]) -> Vec<&'static str> {
+    let mut disallowed = Vec::new();
+    for tool in [
+        "execute_bash",
+        "fs_read",
+        "fs_write",
+        "fs_list",
+        "network",
+        "git_diff",
+        "mcp_team",
+        "provider_builtin",
+    ] {
+        if tools.contains(&tool) {
+            continue;
+        }
+        match grok_tool_mapping(tool) {
+            GrokToolMapping::Deny(names) => disallowed.extend(names),
+            GrokToolMapping::Unsupported | GrokToolMapping::Bypass => {}
+        }
+    }
+    disallowed
+}
+
+/// Canonical tool → grok CLI deny names. Unknown tools stay Unsupported
+/// (no invented `--disallowedTools` token).
+pub(crate) fn grok_tool_mapping(tool: &str) -> GrokToolMapping {
+    match tool {
+        "execute_bash" => GrokToolMapping::Deny(&["Bash"]),
+        "fs_read" => GrokToolMapping::Deny(&["Read"]),
+        "fs_write" => GrokToolMapping::Deny(&["Edit", "Write", "MultiEdit", "NotebookEdit"]),
+        "fs_list" => GrokToolMapping::Deny(&["Glob", "Grep"]),
+        "dangerous_auto_approve" => GrokToolMapping::Bypass,
+        "network" | "git_diff" | "mcp_team" | "provider_builtin" => GrokToolMapping::Unsupported,
+        _ => GrokToolMapping::Unsupported,
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum GrokToolMapping {
+    Deny(&'static [&'static str]),
+    Bypass,
+    Unsupported,
+}

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

@@ -28,3 +28,5 @@ pub(crate) mod codex;
 pub(crate) mod copilot;
 pub(crate) mod copilot_fork;
 pub(crate) mod fake;
+pub(crate) mod grok;
+pub(crate) mod cursor_agent;

package/crates/team-agent/src/provider/bypass_flags.rs

@@ -8,6 +8,8 @@
 //!   - claude/claude_code → `--dangerously-skip-permissions`
 //!   - codex → `--dangerously-bypass-approvals-and-sandbox`
 //!   - copilot → `--allow-all`(0.3.27 P1 E54 symptom 2 起)
+//!   - grok → `--always-approve`
+//!   - cursor_agent → `--force`
 //!
 //! 未定义(返回 None)的 provider:调用侧必须 fail-loud(见
 //! `resolved_tool_strings_for_command`),不得静默 fallback。
@@ -20,14 +22,23 @@ pub(crate) fn provider_bypass_flag(provider: Provider) -> Option<&'static str> {
         Provider::Claude | Provider::ClaudeCode => Some("--dangerously-skip-permissions"),
         Provider::Codex => Some("--dangerously-bypass-approvals-and-sandbox"),
         Provider::Copilot => Some("--allow-all"),
+        Provider::Grok => Some("--always-approve"),
+        Provider::CursorAgent => Some("--force"),
         // TODO: 查 gemini_cli 的等价 bypass 参数;未定义前 fail-loud。
         Provider::GeminiCli => None,
         Provider::Fake => None,
     }
 }
 
-/// 0.5.66 §3.2 跨 workspace 兼容警示用:扫 argv tokens 找已知 bypass flag。
-/// **只做检测,不做行为决策**(0.6.0 删)。
+/// 0.5.66 §3.2 跨 workspace 兼容警示用:扫 **team-agent 进程自己的** argv tokens
+/// 找已知 bypass flag。**只做检测,不做行为决策**(0.6.0 删)。
+///
+/// 不认 `--force`:那是 team-agent 自己的 CLI 旗(`init --force` /
+/// `remove-agent --confirm --force` / `restart --force`),与 cursor worker
+/// 的 `--force` 撞名。本函数看不到「当前在看哪个 provider 的 argv」,
+/// 认 `--force` 会把既有非 grok/cursor 路径误判成 bypass。
+/// cursor worker 的 bypass 仍走 [`provider_bypass_flag`],不走这条检测面。
+/// `--always-approve` 可以认:team-agent 自己没有这个旗。
 ///
 /// TODO(0.6.0): remove
 pub(crate) fn detect_bypass_flag_in_argv(argv_tokens: &[String]) -> Option<&'static str> {
@@ -43,6 +54,9 @@ pub(crate) fn detect_bypass_flag_in_argv(argv_tokens: &[String]) -> Option<&'sta
         if token == "--allow-all" || token == "--yolo" {
             return Some("--allow-all");
         }
+        if token == "--always-approve" {
+            return Some("--always-approve");
+        }
     }
     None
 }
@@ -77,4 +91,34 @@ mod tests {
         assert_eq!(provider_bypass_flag(Provider::GeminiCli), None);
         assert_eq!(provider_bypass_flag(Provider::Fake), None);
     }
+
+    #[test]
+    fn grok_and_cursor_bypass_flags() {
+        assert_eq!(
+            provider_bypass_flag(Provider::Grok),
+            Some("--always-approve")
+        );
+        assert_eq!(
+            provider_bypass_flag(Provider::CursorAgent),
+            Some("--force")
+        );
+    }
+
+    #[test]
+    fn detect_bypass_flag_ignores_team_agent_force() {
+        let argv = [
+            "team-agent".to_string(),
+            "remove-agent".to_string(),
+            "x".to_string(),
+            "--confirm".to_string(),
+            "--force".to_string(),
+        ];
+        assert_eq!(
+            detect_bypass_flag_in_argv(&argv),
+            None,
+            "detect_bypass_flag_in_argv scans team-agent process argv, not worker argv; \
+             `remove-agent --force` must not look like a provider bypass flag; got {:?}",
+            detect_bypass_flag_in_argv(&argv)
+        );
+    }
 }

package/crates/team-agent/src/provider/classify.rs

@@ -215,7 +215,8 @@ fn latest_explicit_error_fact_for_record(
         Provider::Claude | Provider::ClaudeCode => claude_latest_explicit_error_fact(record),
         // C-3-5 cr verdict: copilot N35 通知不依赖 turn-state 分类;一期 Unknown,
         // 与 GeminiCli/Fake 同精神。二期接 sqlite turns 表后再回填。
-        Provider::Copilot | Provider::GeminiCli | Provider::Fake => None,
+        Provider::Copilot | Provider::Grok | Provider::CursorAgent | Provider::GeminiCli
+        | Provider::Fake => None,
     }
 }
 
@@ -378,7 +379,8 @@ fn extract_lifecycle_facts(
             Provider::Codex => codex_lifecycle_fact(record),
             // C-3-1 cr verdict: copilot lifecycle facts 一期不导出(classify→None,
             // Unknown);二期读 sqlite turns 表(turn_index/assistant_response)。
-            Provider::Copilot | Provider::GeminiCli | Provider::Fake => None,
+            Provider::Copilot | Provider::Grok | Provider::CursorAgent | Provider::GeminiCli
+            | Provider::Fake => None,
         })
         .collect()
 }

package/crates/team-agent/src/provider/faults.rs

@@ -46,7 +46,8 @@ fn fault_fact(provider: Provider, record: &serde_json::Value) -> Option<FaultFac
     match provider {
         Provider::Claude | Provider::ClaudeCode => claude_fault_fact(record),
         Provider::Codex => codex_fault_fact(record),
-        Provider::Copilot | Provider::GeminiCli | Provider::Fake => None,
+        Provider::Copilot | Provider::Grok | Provider::CursorAgent | Provider::GeminiCli
+        | Provider::Fake => None,
     }
 }
 

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

@@ -1,3 +1,13 @@
+//! ---
+//! purpose: provider 命令构造与会话观察入口
+//! contract:
+//!   provides:
+//!     - name: adapter
+//!       what: 按 Provider 分发 launch/capability
+//! boundary:
+//!   - 不把 observation 写成 ownership
+//! maturity: wired
+//! ---
 //!
 //! step 8 · provider — type + trait SKELETON (ROUND-0).
 //!
@@ -44,6 +54,7 @@ pub mod faults;
 pub mod session;
 pub mod session_scan;
 pub mod startup_prompt;
+pub mod submit_now;
 pub mod types;
 /// 0.4.x: provider wire-format helpers — single source of truth for
 /// `Provider` ↔ string conversions (replaces 7 hand-rolled match copies).

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 \