@team-agent/installer 0.5.66 → 0.5.69

package/crates/team-agent/src/lifecycle/launch.rs

@@ -1,3 +1,13 @@
+//! ---
+//! purpose: 冷启、add/clone/fork 入口拼装
+//! contract:
+//!   provides:
+//!     - name: fork_agent
+//!       what: 成员分身入口，grok 走窗口内命令
+//! boundary:
+//!   - 不读 provider 会话落盘
+//! maturity: wired
+//! ---
 //!
 //! lifecycle::launch —— 冷启 / quick-start / 危险审批探测 + add/fork / plan 起步与推进。
 
@@ -18,6 +28,16 @@ use super::*;
 
 // ── lifecycle::launch —— 冷启 / quick-start / 危险审批探测 ──────────────────
 
+/// ---
+/// purpose: 冷启全队的默认入口，按 spec 所在目录绑定 per-team tmux socket 后转 launch_with_transport
+/// params:
+///   spec_path: 已编译 spec 的路径，其父目录即 team 目录
+///   dry_run: 只出路由与权限，不 spawn 也不落盘
+///   auto_approve: 当前为 no-op
+///   skip_profile_smoke: 当前为 no-op
+/// returns: LaunchReport
+/// errors: 透传 launch_with_transport 的错误
+/// ---
 ///
 /// `launch(spec_path, dry_run, auto_approve, skip_profile_smoke)`(`launch/core.py:29`)。
 /// 冷启全队:路由 tasks、resolve 权限/危险审批门、session 冲突检查(冲突 →
@@ -42,6 +62,13 @@ pub fn launch(
     )
 }
 
+/// ---
+/// purpose: 由 spec 路径推出 workspace，再转 launch_with_transport_in_workspace
+/// params:
+///   transport: 已绑定 team socket 的 transport
+/// returns: LaunchReport
+/// errors: 透传 launch_with_transport_in_workspace 的错误
+/// ---
 pub(crate) fn launch_with_transport(
     spec_path: &Path,
     dry_run: bool,
@@ -61,6 +88,17 @@ pub(crate) fn launch_with_transport(
     )
 }
 
+/// ---
+/// purpose: 冷启全队的实体实现，编译 spec、检查 session 冲突、按序 spawn、落 state、出报告
+/// params:
+///   workspace: run workspace 根，事件与 state 都落在这里
+///   spec_path: 已编译 spec 的路径
+///   dry_run: 为真时不 spawn 不落盘，started 为空
+///   auto_approve: 未使用
+///   skip_profile_smoke: 未使用
+/// returns: LaunchReport，其中 leader_receiver_attached 恒 false、session_capture_incomplete_agents 恒空
+/// errors: spec 不存在或解析失败返回 Compile，tmux session 已存在返回 SessionConflict，spawn 与落 state 的错误透传
+/// ---
 pub fn launch_with_transport_in_workspace(
     workspace: &Path,
     spec_path: &Path,
@@ -71,8 +109,8 @@ pub fn launch_with_transport_in_workspace(
 ) -> Result<LaunchReport, LifecycleError> {
     let _ = skip_profile_smoke;
     let _ = auto_approve; // 0.5.66: bypass 单源后无 runtime.dangerous_auto_approve,`--yes` 为 no-op。
-    // 0.5.38 (`.team/artifacts/startup-latency-locate.md` §5): launch.phase
-    // timer with monotonic `elapsed_ms` for latency triage.
+                          // 0.5.38 (`.team/artifacts/startup-latency-locate.md` §5): launch.phase
+                          // timer with monotonic `elapsed_ms` for latency triage.
     let phase_timer = crate::lifecycle::restart::RestartPhaseTimer::start();
     if !spec_path.exists() {
         return Err(LifecycleError::Compile(format!(
@@ -107,13 +145,7 @@ pub fn launch_with_transport_in_workspace(
         Vec::new()
     } else {
         phase_timer.emit(workspace, "launch.phase", "spawn_all");
-        let started = spawn_agents(
-            workspace,
-            spec_path,
-            &spec,
-            &session_name,
-            transport,
-        )?;
+        let started = spawn_agents(workspace, spec_path, &spec, &session_name, transport)?;
         persist_spawn_agent_state(
             workspace,
             spec_path,
@@ -224,8 +256,8 @@ mod plan;
 pub(crate) use plan::{handle_report_result, start_plan};
 
 pub mod spawn;
-pub(super) use spawn::*;
 pub(crate) use spawn::agent_id_spec_source_path;
+pub(super) use spawn::*;
 
 mod layout;
 pub(super) use layout::*;
@@ -260,20 +292,46 @@ pub(crate) use agent_state::{
     persist_effective_approval_policy_from_agent,
 };
 
+mod grok_per_seat;
+pub(crate) use grok_per_seat::{
+    is_per_seat_env_key, non_per_seat_env_in_tables, per_seat_keys_in_toml,
+    strip_per_seat_keys_from_toml,
+};
+
 mod mcp_config;
+pub use mcp_config::apply_grok_mcp_overlay;
 pub(super) use mcp_config::*;
 pub(crate) use mcp_config::{
-    point_native_mcp_config_at_file, resolve_mcp_config, write_worker_mcp_config,
+    ensure_grok_login_and_folder_trust, grok_shared_cwd_error, point_native_mcp_config_at_file,
+    reconcile_grok_toml_per_seat_keys, resolve_mcp_config, write_worker_mcp_config,
     write_worker_mcp_config_for_provider,
 };
 
+pub(crate) mod pi_mcp;
+
+mod cursor_mcp_iso;
+pub use cursor_mcp_iso::{
+    cursor_mcp_isolation_enabled, cursor_mcp_json_path, cursor_mcp_project_dir,
+    materialize_cursor_mcp_project,
+};
+mod cursor_mcp;
+pub use cursor_mcp::{
+    apply_cursor_mcp_overlay, apply_cursor_spawn_workspace_pointers,
+    apply_cursor_workspace_physical_path, cursor_mcp_enable_argv, enable_cursor_workspace_mcp,
+    physical_workspace_path, refuse_second_cursor_occupant,
+};
+
+mod cursor_create_chat;
+
 mod worker_env;
 pub(super) use worker_env::*;
 pub(crate) use worker_env::{
-    apply_copilot_instructions_overlay, apply_mcp_auto_approval_env, apply_profile_launch_env,
+    apply_copilot_instructions_overlay, apply_cursor_agent_rules_overlay,
+    apply_mcp_auto_approval_env, apply_profile_launch_env, auth_mode_env_value,
     fill_spawn_placeholders, fill_spawn_placeholders_full, inherited_env_with_team_overrides,
     persist_command_plan_state, spawn_timestamp,
 };
+pub use worker_env::{apply_cursor_subscription_proxy_env, CursorProxyPresence};
 
 mod identity;
 pub(super) use identity::*;
@@ -300,7 +358,7 @@ pub(crate) use quick_start_transport::{
 };
 
 pub mod readiness;
-pub(crate) use readiness::launched_team_receiver_is_attached;
+pub use readiness::launched_team_receiver_is_attached;
 pub(super) use readiness::*;
 
 mod add_agent;
@@ -313,19 +371,12 @@ pub(crate) use add_agent_state::inject_agent_into_spec;
 pub(super) use add_agent_state::*;
 
 mod fork_agent;
-pub use fork_agent::fork_agent_with_transport;
 pub(super) use fork_agent::*;
+pub use fork_agent::{fork_agent_with_transport, in_window_fork, in_window_fork_command};
 
 mod fork_entry;
 pub use fork_entry::fork_agent;
 
-mod fork_state;
-pub(super) use fork_state::*;
-
-mod fork_finalize;
-pub(super) use fork_finalize::*;
-pub(crate) use fork_finalize::{finalize_pending_fork_capture, ContextForkFinalized};
-
 mod role_source;
 pub(super) use role_source::*;
 
@@ -337,9 +388,7 @@ pub(super) use ownership::*;
 pub(crate) use ownership::{ensure_owner_allowed, ensure_owner_allowed_for_state, state_path};
 
 pub mod spec_state;
-pub(crate) use spec_state::{
-    override_spec_session_name, override_spec_workspace, spec_agent_id_set, write_spec_atomic,
-};
+pub use spec_state::worker_session_name_pub;
 pub(crate) use spec_state::{
     effective_runtime_config_for_worker_spawn, effective_runtime_config_for_worker_spawn_json,
 };
@@ -350,7 +399,9 @@ use spec_state::{
     spec_agent_values, spec_agents, spec_default_assignee, spec_routes, spec_session_name,
     spec_tasks_json, team_workspace, yaml_value_to_json,
 };
-pub use spec_state::worker_session_name_pub;
+pub(crate) use spec_state::{
+    override_spec_session_name, override_spec_workspace, spec_agent_id_set, write_spec_atomic,
+};
 
 #[cfg(test)]
 mod tests {
@@ -361,10 +412,8 @@ mod tests {
     // leader argv 带 bypass flag + 无角色声明 true → 写 warning 事件。
     #[test]
     fn test_leader_flag_present_but_no_role_true_writes_warning_event() {
-        let ws = std::env::temp_dir().join(format!(
-            "ta-bypass-warning-test-{}",
-            std::process::id()
-        ));
+        let ws =
+            std::env::temp_dir().join(format!("ta-bypass-warning-test-{}", std::process::id()));
         let _ = std::fs::remove_dir_all(&ws);
         std::fs::create_dir_all(&ws).unwrap();
         let spec = yaml::loads(
@@ -415,4 +464,33 @@ mod tests {
         );
         let _ = std::fs::remove_dir_all(&ws);
     }
+
+    #[test]
+    fn team_agent_force_flag_does_not_look_like_bypass() {
+        let ws =
+            std::env::temp_dir().join(format!("ta-bypass-force-not-bypass-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&ws);
+        std::fs::create_dir_all(&ws).unwrap();
+        let spec = yaml::loads(
+            "version: 1\nteam: {}\nleader: {}\nagents:\n  - id: a\n    role: r\n    provider: fake\n    dangerously_skip_permissions: false\n",
+        )
+        .unwrap();
+        let argv = vec![
+            "team-agent".to_string(),
+            "remove-agent".to_string(),
+            "x".to_string(),
+            "--confirm".to_string(),
+            "--force".to_string(),
+        ];
+        emit_dangerous_flag_no_role_declared_warning_with_argv(&ws, &spec, &argv);
+        let events = crate::event_log::EventLog::new(&ws).tail(0).unwrap();
+        assert!(
+            !events.iter().any(|event| {
+                event.get("event").and_then(serde_json::Value::as_str)
+                    == Some("dangerously_flag_present_but_no_role_declared")
+            }),
+            "team-agent --force must not emit bypass warning; events={events:?}"
+        );
+        let _ = std::fs::remove_dir_all(&ws);
+    }
 }

package/crates/team-agent/src/lifecycle/lock.rs

@@ -1,3 +1,22 @@
+//! ---
+//! purpose: workspace 级 agent-lifecycle 互斥锁，让同一 workspace 的席位增删起停串行
+//! contract:
+//!   provides:
+//!     - name: acquire_agent_lifecycle_lock
+//!       what: 轮询抢锁，成功返回持有到 Drop 的 guard，超时返回 LifecycleLockTimeout
+//!     - name: agent_lifecycle_lock_path
+//!       what: 给出该 workspace 的锁文件路径
+//!   depends:
+//!     - crate::platform::file_lock
+//!     - crate::event_log::EventLog
+//!     - crate::model::paths
+//! boundary:
+//!   - 不锁 pane 输入通道，那是 pane_input_lock
+//!   - 不做跨 workspace 互斥，锁作用域就是一个 workspace
+//!   - 拿不到锁只超时报错，不强抢也不清理他人锁文件
+//!   - 锁文件内容只作观测用，不作为持有权判据
+//! maturity: wired
+//! ---
 use std::io::{Seek, Write};
 use std::path::{Path, PathBuf};
 use std::time::{Duration, Instant};
@@ -17,10 +36,16 @@ pub(crate) struct LifecycleLockRequest<'a> {
 }
 
 pub(crate) struct LifecycleLockGuard {
-    #[allow(dead_code)]
     file: std::fs::File,
 }
 
+/// ---
+/// purpose: 抢 workspace 级 agent-lifecycle 锁，默认 30 秒超时、5 秒起写 lock_held_long 事件
+/// params:
+///   request: 携带 workspace、操作名与可选 team/agent，仅用于锁元数据与事件
+/// returns: 持有锁的 guard，Drop 时解锁
+/// errors: 建目录或打开锁文件失败返回 StatePersist，等待超时返回 LifecycleLockTimeout
+/// ---
 pub(crate) fn acquire_agent_lifecycle_lock(
     request: LifecycleLockRequest<'_>,
 ) -> Result<LifecycleLockGuard, LifecycleError> {
@@ -35,6 +60,14 @@ pub(crate) fn acquire_agent_lifecycle_lock(
     )
 }
 
+/// ---
+/// purpose: 以显式超时与告警阈值抢同一把锁，仅测试构建可见
+/// params:
+///   timeout: 放弃等待的上限
+///   held_long: 超过它写一次 lock_held_long 事件
+/// returns: 持有锁的 guard
+/// errors: 同 acquire_agent_lifecycle_lock
+/// ---
 #[cfg(test)]
 pub(crate) fn acquire_agent_lifecycle_lock_for_test(
     request: LifecycleLockRequest<'_>,
@@ -55,6 +88,10 @@ pub(crate) struct LifecycleLockDeadlineOverrideGuard {
     previous: Option<(Duration, Duration)>,
 }
 
+/// ---
+/// purpose: 线程内改写默认锁超时与告警阈值，仅测试构建可见
+/// returns: guard，Drop 时恢复上一次的取值
+/// ---
 #[cfg(test)]
 pub(crate) fn override_agent_lifecycle_lock_deadlines_for_test(
     timeout: Duration,
@@ -145,6 +182,10 @@ fn acquire_agent_lifecycle_lock_with_deadlines(
     }
 }
 
+/// ---
+/// purpose: 给出该 workspace 的 agent-lifecycle 锁文件路径
+/// returns: runtime 目录下的 agent-lifecycle.lock
+/// ---
 pub(crate) fn agent_lifecycle_lock_path(workspace: &Path) -> PathBuf {
     crate::model::paths::runtime_dir(workspace).join(format!("{AGENT_LIFECYCLE_LOCK_NAME}.lock"))
 }

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

@@ -1,3 +1,13 @@
+//! ---
+//! purpose: team 进程级生命周期编排（起停加减 clone/fork）
+//! contract:
+//!   provides:
+//!     - name: launch
+//!       what: 冷启与成员生命周期入口
+//! boundary:
+//!   - 不拥有物理注入，只调用 transport
+//! maturity: wired
+//! ---
 //!
 //! step 13 · lifecycle — team 进程级生命周期编排器(ROUND-0.5 骨架)。
 //!
@@ -46,6 +56,7 @@ pub mod display;
 pub mod helpers;
 pub mod launch;
 pub(crate) mod lock;
+pub(crate) mod pane_input_lock;
 pub(crate) mod profile_launch;
 pub(crate) mod profile_smoke;
 pub mod restart;

package/crates/team-agent/src/lifecycle/pane_input_lock.rs

@@ -0,0 +1,161 @@
+//! ---
+//! purpose: pane 输入通道互斥锁，让同一 pane 上的写入串行化
+//! contract:
+//!   provides:
+//!     - name: acquire_or_proceed
+//!       what: 取到锁则持有到 Drop；超时或锁不可用则告警后放行，不无限等待
+//!   depends:
+//!     - crate::platform::file_lock
+//!     - crate::event_log::EventLog
+//! boundary:
+//!   - 不锁席位生命周期（那是 lock.rs）
+//!   - 不重粘文本、不加自动兜底重投；重试只重按回车由既有 inject 路径负责
+//!   - 不在投递层发明临时持有态
+//! maturity: wired
+//! ---
+
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+use crate::event_log::EventLog;
+use crate::model::paths::runtime_dir;
+
+/// Hard upper bound for waiting on the pane input lock. Constant, not a magic number in a loop.
+pub(crate) const PANE_INPUT_LOCK_TIMEOUT: Duration = Duration::from_millis(200);
+
+pub(crate) const PANE_INPUT_LOCK_NAME: &str = "pane-input";
+
+/// Event / stderr token. A5 greps this exact string.
+pub(crate) const PANE_INPUT_LOCK_TIMEOUT_EVENT: &str = "pane_input_lock.timeout";
+
+pub(crate) struct PaneInputLockRequest<'a> {
+    pub workspace: Option<&'a Path>,
+    pub target_key: &'a str,
+    pub operation: &'static str,
+}
+
+pub(crate) struct PaneInputLockGuard {
+    file: Option<std::fs::File>,
+}
+
+/// ---
+/// purpose: 取 pane 输入锁；拿不到或超时则告警后放行，绝不无限等待
+/// params:
+///   request: 携带可选 workspace、目标 pane 键与操作名
+/// returns: Some 表示已持锁，None 表示无 workspace 可锁或已超时放行
+/// ---
+/// Acquire the pane lock or proceed after the hard timeout.
+///
+/// On timeout / lock I/O failure: emit [`PANE_INPUT_LOCK_TIMEOUT_EVENT`] (stderr + events.jsonl)
+/// and return `None` so the caller still writes. Relief messages must not wait forever.
+pub(crate) fn acquire_or_proceed(request: PaneInputLockRequest<'_>) -> Option<PaneInputLockGuard> {
+    let timeout = PANE_INPUT_LOCK_TIMEOUT;
+    let Some(workspace) = request.workspace else {
+        // No workspace (some unit backends): nothing to lock against. Not an alarm.
+        return None;
+    };
+    acquire_file_lock(workspace, &request, timeout)
+}
+
+fn acquire_file_lock(
+    workspace: &Path,
+    request: &PaneInputLockRequest<'_>,
+    timeout: Duration,
+) -> Option<PaneInputLockGuard> {
+    let path = pane_input_lock_path(workspace, request.target_key);
+    if let Some(parent) = path.parent() {
+        if std::fs::create_dir_all(parent).is_err() {
+            emit_timeout_alarm(request, timeout, Duration::ZERO, "lock_dir");
+            return None;
+        }
+    }
+    let file = match std::fs::OpenOptions::new()
+        .create(true)
+        .read(true)
+        .write(true)
+        .truncate(false)
+        .open(&path)
+    {
+        Ok(file) => file,
+        Err(_) => {
+            emit_timeout_alarm(request, timeout, Duration::ZERO, "lock_open");
+            return None;
+        }
+    };
+    let started = Instant::now();
+    loop {
+        match crate::platform::file_lock::try_lock_once_nonblocking(&file) {
+            Ok(true) => {
+                return Some(PaneInputLockGuard { file: Some(file) });
+            }
+            Ok(false) => {}
+            Err(_) => {
+                emit_timeout_alarm(request, timeout, started.elapsed(), "lock_io");
+                return None;
+            }
+        }
+        let elapsed = started.elapsed();
+        if elapsed >= timeout {
+            emit_timeout_alarm(request, timeout, elapsed, "timeout");
+            return None;
+        }
+        std::thread::sleep(std::cmp::min(
+            Duration::from_millis(10),
+            timeout.saturating_sub(elapsed),
+        ));
+    }
+}
+
+fn pane_input_lock_path(workspace: &Path, target_key: &str) -> PathBuf {
+    let safe: String = target_key
+        .chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() {
+                c
+            } else {
+                '_'
+            }
+        })
+        .collect();
+    runtime_dir(workspace)
+        .join(PANE_INPUT_LOCK_NAME)
+        .join(format!("{safe}.lock"))
+}
+
+fn emit_timeout_alarm(
+    request: &PaneInputLockRequest<'_>,
+    timeout: Duration,
+    waited: Duration,
+    reason: &str,
+) {
+    // A5 watches this exact token on stderr. Commenting this line must turn A5 red.
+    eprintln!(
+        "{PANE_INPUT_LOCK_TIMEOUT_EVENT} target={} operation={} waited_ms={} timeout_ms={} reason={reason} proceeding",
+        request.target_key,
+        request.operation,
+        waited.as_millis(),
+        timeout.as_millis()
+    );
+    if let Some(workspace) = request.workspace {
+        let _ = EventLog::new(workspace).write(
+            PANE_INPUT_LOCK_TIMEOUT_EVENT,
+            serde_json::json!({
+                "lock_name": PANE_INPUT_LOCK_NAME,
+                "target": request.target_key,
+                "operation": request.operation,
+                "waited_ms": waited.as_millis() as u64,
+                "timeout_ms": timeout.as_millis() as u64,
+                "reason": reason,
+                "disposition": "proceed",
+            }),
+        );
+    }
+}
+
+impl Drop for PaneInputLockGuard {
+    fn drop(&mut self) {
+        if let Some(file) = self.file.take() {
+            let _ = crate::platform::file_lock::unlock(&file);
+        }
+    }
+}

package/crates/team-agent/src/lifecycle/profile_launch.rs

@@ -1,3 +1,29 @@
+//! ---
+//! purpose: 由 agent 的 profile 声明推出 provider 启动所需的环境覆盖、环境清除与命令覆写
+//! contract:
+//!   provides:
+//!     - name: prepare_provider_profile_launch
+//!       what: 从 YAML agent 节点算出 ProviderProfileLaunch
+//!     - name: prepare_provider_profile_launch_from_json
+//!       what: 从 runtime state 的 JSON agent 节点算出同一结果
+//!     - name: load_profile
+//!       what: 按查找顺序找到 profile env 文件并解析成键值
+//!     - name: provider_env_unsets
+//!       what: 该 provider 与 auth_mode 下必须清除的环境变量集，worker 与 leader 共用这一份
+//!     - name: profile_proxy_mode
+//!       what: 读出 profile 的代理模式，缺省 inherit
+//!     - name: parse_auth_mode
+//!       what: 把 auth_mode 字符串解析成枚举，未知值返回 None
+//!   depends:
+//!     - crate::provider
+//!     - crate::model::enums
+//!     - std::fs
+//! boundary:
+//!   - 只读 profile 文件，不改写也不创建 profile
+//!   - 不把密钥值写进事件或错误消息
+//!   - provider 的环境清除集只此一份，leader 侧不得另建
+//! maturity: wired
+//! ---
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 
@@ -37,6 +63,15 @@ struct AgentProfileInput {
     model_source: Option<String>,
 }
 
+/// ---
+/// purpose: 从 YAML agent 节点准备 provider 启动参数，profile 目录用默认查找顺序
+/// params:
+///   agent_id: agent 节点没写 id 时的兜底 id
+///   mcp_config: 需要托管 MCP 配置时传入，否则 None
+/// returns: 环境覆盖、环境清除、命令覆写与 claude 配置目录
+/// errors: profile 找不到、必填键缺失或写 runtime env 文件失败时返回 LifecycleError
+/// contract_id: lifecycle.profile_launch.prepare
+/// ---
 pub(crate) fn prepare_provider_profile_launch(
     workspace: &Path,
     agent_id: &str,
@@ -46,6 +81,14 @@ pub(crate) fn prepare_provider_profile_launch(
     prepare_provider_profile_launch_with_profile_dir(workspace, agent_id, agent, None, mcp_config)
 }
 
+/// ---
+/// purpose: 同上，但允许指定优先查找的 profile 目录
+/// params:
+///   profile_dir: 优先查找目录；agent 节点里的 _profile_dir 优先于它
+/// returns: 环境覆盖、环境清除、命令覆写与 claude 配置目录
+/// errors: 同 prepare_provider_profile_launch
+/// contract_id: lifecycle.profile_launch.prepare
+/// ---
 pub(crate) fn prepare_provider_profile_launch_with_profile_dir(
     workspace: &Path,
     agent_id: &str,
@@ -94,6 +137,12 @@ pub(crate) fn prepare_provider_profile_launch_with_profile_dir(
     prepare_profile_launch(workspace, input, mcp_config)
 }
 
+/// ---
+/// purpose: 从 runtime state 的 JSON agent 节点准备 provider 启动参数
+/// returns: 环境覆盖、环境清除、命令覆写与 claude 配置目录
+/// errors: 同 prepare_provider_profile_launch
+/// contract_id: lifecycle.profile_launch.prepare
+/// ---
 pub(crate) fn prepare_provider_profile_launch_from_json(
     workspace: &Path,
     agent_id: &str,
@@ -199,6 +248,14 @@ fn prepare_profile_launch(
     })
 }
 
+/// ---
+/// purpose: 按查找目录顺序定位 profile env 文件并解析成键值表
+/// params:
+///   name: profile 名，先找 name.env 再找 name.example.env
+///   profile_dir: 优先查找目录，None 表示只用默认顺序
+/// returns: 命中的文件路径与解析出的键值
+/// errors: 所有目录都没命中返回 RequirementUnmet，读文件失败返回 StatePersist
+/// ---
 pub(crate) fn load_profile(
     workspace: &Path,
     name: &str,
@@ -424,11 +481,19 @@ fn provider_env_exports(
                 }
             }
         }
+        // grok/cursor_agent 一期无 profile exports（subscription 已登录态）。
+        // Cursor 订阅席的代理透传不在这里：profile 只服务 compatible-api。
+        // 订阅路径见 apply_cursor_subscription_proxy_env（只记有无，不记值）。
+        Provider::Grok | Provider::CursorAgent | Provider::Pi => {}
         Provider::Fake => {}
     }
     exports
 }
 
+/// ---
+/// purpose: 给出该 provider 与 auth_mode 下必须从子进程环境里清掉的变量名集
+/// returns: 变量名集合；claude 系清掉会让子进程并入父会话的那组标识
+/// ---
 /// 0.4.x (CR C-1): exposed as `pub(crate)` so the leader launcher
 /// (leader/start.rs) can reuse the SAME Claude/Codex/Copilot env-unset set
 /// used by worker spawn. Single source of truth — adding a new provider env
@@ -497,6 +562,12 @@ pub(crate) fn provider_env_unsets(provider: Provider, auth_mode: AuthMode) -> BT
         // C-7-1 cr verdict: 一期 subscription-only(已登录态),exports/unsets 空;
         // BYOK(COPILOT_PROVIDER_*)二期立项时单独 cr verdict 再开。
         Provider::Copilot => {}
+        // grok 无 env 需 unset。cursor 订阅席必须保留代理键（TUI 连云要用）；
+        // `--print` 路径会因 https:// 方案撞 GLOBAL_AGENT，但主路径是 TUI。
+        // 禁止在这里 unset 代理。
+        Provider::Grok => {}
+        Provider::CursorAgent => {}
+        Provider::Pi => {}
         Provider::Fake => {}
     }
     unsets
@@ -893,6 +964,12 @@ fn compatible_api_network_exports(
         .collect()
 }
 
+/// ---
+/// purpose: 读出 profile 声明的代理模式
+/// params:
+///   values: 已解析的 profile 键值，先看 PROXY_MODE 再看 NETWORK_MODE
+/// returns: 小写去空白后的模式串，两个键都没有时为 inherit
+/// ---
 pub(crate) fn profile_proxy_mode(values: &BTreeMap<String, String>) -> String {
     values
         .get("PROXY_MODE")
@@ -915,10 +992,18 @@ fn required_profile_keys(provider: Provider, auth_mode: AuthMode) -> &'static [&
         // C-7-1 cr verdict: copilot 一期 subscription-only,无 BYOK required key 集合;
         // 二期 BYOK 立项时填(向后兼容字段保留)。
         Provider::Copilot => &[],
+        // 0.5.67: grok/cursor_agent 一期无 BYOK required key 集合 (同 copilot 精神)。
+        Provider::Grok | Provider::CursorAgent | Provider::Pi => &[],
         Provider::Fake => &[],
     }
 }
 
+/// ---
+/// purpose: 取 profile 里某个规范键，取不到时按该键的已知别名回退
+/// params:
+///   key: 规范键名，API_KEY BASE_URL MODEL 各有一组别名，其余键不回退
+/// returns: 命中的非空值
+/// ---
 pub(crate) fn profile_value_or_alternate<'a>(
     values: &'a BTreeMap<String, String>,
     key: &str,
@@ -949,6 +1034,10 @@ pub(crate) fn profile_value_or_alternate<'a>(
         })
 }
 
+/// ---
+/// purpose: 在两个显式给定的键之间取第一个非空值
+/// returns: 命中的非空值，两个都空则 None
+/// ---
 pub(crate) fn value_or_alternate<'a>(
     values: &'a BTreeMap<String, String>,
     primary: &str,
@@ -961,6 +1050,10 @@ pub(crate) fn value_or_alternate<'a>(
         .map(String::as_str)
 }
 
+/// ---
+/// purpose: 取 profile 里声明的模型名
+/// returns: MODEL 的非空值，没有时取 ANTHROPIC_MODEL
+/// ---
 pub(crate) fn profile_model(values: &BTreeMap<String, String>) -> Option<&str> {
     values
         .get("MODEL")
@@ -982,6 +1075,12 @@ fn effective_profile_or_agent_model<'a>(
 
 pub(crate) use crate::provider::wire::parse_provider;
 
+/// ---
+/// purpose: 把 auth_mode 字符串解析成枚举
+/// params:
+///   raw: 只接受 subscription、official_api、compatible_api
+/// returns: 对应枚举；未知取值返回 None，由调用方决定兜底
+/// ---
 pub(crate) fn parse_auth_mode(raw: &str) -> Option<AuthMode> {
     match raw {
         "subscription" => Some(AuthMode::Subscription),