@team-agent/installer 0.5.65 → 0.5.68

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

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

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

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

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

@@ -1,3 +1,24 @@
+//! ---
+//! purpose: coordinator 的共享数据面——协议常量、Pid/WorkspacePath newtype、健康与启停的穷尽状态 enum、metadata/schema/report 结构、以及跨子系统注入用的 trait 占位
+//! contract:
+//!   provides:
+//!     - name: as_str
+//!       what: 把 binary-identity relation 与 metadata mismatch reason 映射成稳定 wire 字符串
+//!     - name: as_path
+//!       what: 从 WorkspacePath newtype 取回底层路径
+//!   depends:
+//!     - crate::model::enums
+//!     - crate::model::ids
+//!     - crate::provider
+//!     - crate::message_store
+//!     - crate::event_log
+//! boundary:
+//!   - 只定义形状，不含任何判定、I/O 或事件写入
+//!   - as_str 的返回值是对外稳定契约：已发布的字符串只可新增不可改写
+//!   - ProviderRegistry / MarkerStore 只是注入点，实现体不在本模块
+//! maturity: wired
+//! ---
+//!
 //! coordinator 共享数据面:常量 / newtype / 穷尽 enum / metadata / schema health /
 //! report 结构 / abnormal-track 数据型 / WatchCursor / cross-dep 占位。
 
@@ -42,9 +63,19 @@ pub const ROTATION_MARKER: &str =
 pub struct Pid(pub u32);
 
 impl Pid {
+    /// ---
+    /// purpose: 把裸 OS pid 包成 newtype，杜绝与其他 int id 混传
+    /// params:
+    ///   pid: OS 进程号，不做存活或有效性校验
+    /// returns: 承载该 pid 的 newtype
+    /// ---
     pub fn new(pid: u32) -> Self {
         Self(pid)
     }
+    /// ---
+    /// purpose: 取回底层裸 pid，供需要 OS 接口的调用方使用
+    /// returns: 构造时传入的 pid 原值
+    /// ---
     pub fn get(self) -> u32 {
         self.0
     }
@@ -62,9 +93,19 @@ impl std::fmt::Display for Pid {
 pub struct WorkspacePath(pub PathBuf);
 
 impl WorkspacePath {
+    /// ---
+    /// purpose: 把一个路径包成 workspace newtype，作为 tick/health/start/stop 的统一 key
+    /// params:
+    ///   p: workspace 根路径。调用方负责先 resolve；本构造不做规范化也不校验存在性
+    /// returns: 承载该路径的 newtype
+    /// ---
     pub fn new(p: impl Into<PathBuf>) -> Self {
         Self(p.into())
     }
+    /// ---
+    /// purpose: 借出底层路径，供文件系统与子进程参数使用
+    /// returns: 构造时传入的路径原值的借用
+    /// ---
     pub fn as_path(&self) -> &Path {
         &self.0
     }
@@ -200,6 +241,10 @@ pub enum CoordinatorBinaryIdentityRelation {
 }
 
 impl CoordinatorBinaryIdentityRelation {
+    /// ---
+    /// purpose: 把「调用方二进制相对 daemon 二进制」的关系映射成稳定 wire 字符串
+    /// returns: 五个稳定串之一（same / caller_newer_than_daemon / daemon_newer_than_caller / same_version_path_mismatch / unknown）；这些值进事件与 status 输出，已发布的不可改写
+    /// ---
     pub fn as_str(self) -> &'static str {
         match self {
             Self::Same => "same",
@@ -225,6 +270,10 @@ pub enum CoordinatorMetadataMismatchReason {
 }
 
 impl CoordinatorMetadataMismatchReason {
+    /// ---
+    /// purpose: 把 coordinator metadata 被拒的原因映射成稳定 wire 字符串
+    /// returns: 七个稳定串之一（metadata_missing / pid_mismatch / protocol_version_mismatch / message_store_schema_version_mismatch / binary_identity_missing / binary_version_mismatch / binary_path_mismatch）；进 HealthReport 与事件，已发布的不可改写
+    /// ---
     pub fn as_str(self) -> &'static str {
         match self {
             Self::MetadataMissing => "metadata_missing",

package/crates/team-agent/src/db/message_store.rs

@@ -548,19 +548,26 @@ impl MessageStore {
 
     /// `claim_for_delivery` (`core.py:190-205`): atomic single-winner claim. Flips an
     /// eligible row (status ∈ pending/accepted/queued_until_idle/queued_until_start/
-    /// queued_stopped/queued_pane_missing) to `target_resolved`, `delivery_attempts +=
-    /// 1`. Returns `true` iff THIS update matched exactly one row.
+    /// queued_stopped/queued_pane_missing, **or** `target_resolved` with a non-null
+    /// error — the retry/error-bypass path) to `target_resolved`, clears `error`,
+    /// `delivery_attempts += 1`. Returns `true` iff THIS update matched exactly one
+    /// row. Clearing `error` is the CAS: a concurrent retry cannot also match
+    /// `error is not null`.
     pub fn claim_for_delivery(&self, message_id: &str) -> Result<bool, MessageStoreError> {
         let conn = crate::db::schema::open_db(&self.path)?;
         let rows = conn.execute(
             "update messages
              set status = 'target_resolved',
                  delivery_attempts = delivery_attempts + 1,
+                 error = null,
                  updated_at = ?2
              where message_id = ?1
-               and status in (
-                   'pending', 'accepted', 'queued_until_idle', 'queued_until_start',
-                   'queued_stopped', 'queued_pane_missing', ?3
+               and (
+                   status in (
+                       'pending', 'accepted', 'queued_until_idle', 'queued_until_start',
+                       'queued_stopped', 'queued_pane_missing', ?3
+                   )
+                   or (status = 'target_resolved' and error is not null)
                )",
             params![
                 message_id,
@@ -1138,6 +1145,33 @@ mod tests {
         assert_eq!(status_of(&read(&s), &mid), "failed");
     }
 
+    #[test]
+    fn claim_for_delivery_error_retry_is_atomic_single_winner() {
+        let s = store();
+        let mid = s
+            .create_message(Some("t"), "s", "r", "c", None, true, None)
+            .unwrap();
+        s.mark(&mid, "target_resolved", Some("probe_failed"))
+            .unwrap();
+        assert_eq!(
+            col_str(&read(&s), &mid, "error").as_deref(),
+            Some("probe_failed")
+        );
+        assert!(
+            s.claim_for_delivery(&mid).unwrap(),
+            "target_resolved+error must enter the claim gate, not a non-CAS bypass"
+        );
+        let c = read(&s);
+        assert_eq!(status_of(&c, &mid), "target_resolved");
+        assert_eq!(col_str(&c, &mid, "error"), None);
+        assert_eq!(col_i64(&c, &mid, "delivery_attempts"), 1);
+        assert!(
+            !s.claim_for_delivery(&mid).unwrap(),
+            "cleared error must lose the second claim"
+        );
+        assert_eq!(col_i64(&read(&s), &mid, "delivery_attempts"), 1);
+    }
+
     #[test]
     fn claim_for_delivery_never_claims_stored_only_presentation() {
         let s = store();

package/crates/team-agent/src/layout/worker_env.rs

@@ -72,7 +72,8 @@ const WORKER_IDENTITY_PREFIXES: &[&str] = &["CLAUDE_CODE_"];
 ///   * All POSIX-valid shell identifier keys from `parent_env` EXCEPT
 ///     those matching `STRIP_PREFIXES` / `STRIP_EXACT`.
 ///   * Overlay: `TEAM_AGENT_WORKSPACE`, `TEAM_AGENT_ID`,
-///     `TEAM_AGENT_AGENT_ID`, `TEAM_AGENT_OWNER_TEAM_ID` (when present).
+///     `TEAM_AGENT_AGENT_ID`, `TEAM_AGENT_OWNER_TEAM_ID` (when present),
+///     `TEAM_AGENT_AUTH_MODE` (when present).
 ///
 /// POSIX-validity filter: shell variable names must match
 /// `[A-Za-z_][A-Za-z0-9_]*`. Cargo's integration-test runner exports keys
@@ -83,6 +84,7 @@ pub fn worker_spawn_env<I>(
     workspace: &Path,
     agent_id: &str,
     team_id: Option<&str>,
+    auth_mode: Option<&str>,
 ) -> BTreeMap<String, String>
 where
     I: IntoIterator<Item = (String, String)>,
@@ -106,6 +108,9 @@ where
     if let Some(tid) = team_id.filter(|s| !s.is_empty()) {
         env.insert("TEAM_AGENT_OWNER_TEAM_ID".to_string(), tid.to_string());
     }
+    if let Some(auth) = auth_mode.filter(|s| !s.is_empty()) {
+        env.insert("TEAM_AGENT_AUTH_MODE".to_string(), auth.to_string());
+    }
     env
 }
 
@@ -223,6 +228,7 @@ mod tests {
             Path::new("/ws"),
             "developer",
             Some("alpha"),
+            None,
         );
         for stripped in [
             "TEAM_AGENT_LEADER_PROVIDER",
@@ -248,6 +254,7 @@ mod tests {
             Path::new("/ws"),
             "developer",
             Some("alpha"),
+            Some("subscription"),
         );
         assert_eq!(
             env.get("TEAM_AGENT_ID").map(String::as_str),
@@ -265,11 +272,21 @@ mod tests {
             env.get("TEAM_AGENT_OWNER_TEAM_ID").map(String::as_str),
             Some("alpha")
         );
+        assert_eq!(
+            env.get("TEAM_AGENT_AUTH_MODE").map(String::as_str),
+            Some("subscription")
+        );
     }
 
     #[test]
     fn worker_spawn_env_inherits_parent_env_minus_strip_list() {
-        let env = worker_spawn_env(make_parent_env(&[]), Path::new("/ws"), "developer", None);
+        let env = worker_spawn_env(
+            make_parent_env(&[]),
+            Path::new("/ws"),
+            "developer",
+            None,
+            None,
+        );
         // Inherit-then-strip: every parent key passes through EXCEPT the
         // strip list. PATH-like + provider creds + random user vars all
         // present.
@@ -292,7 +309,7 @@ mod tests {
     #[test]
     fn worker_spawn_env_drops_posix_invalid_keys() {
         let parent = make_parent_env(&[("CARGO_BIN_EXE_team-agent", "/bin/x")]);
-        let env = worker_spawn_env(parent, Path::new("/ws"), "developer", None);
+        let env = worker_spawn_env(parent, Path::new("/ws"), "developer", None, None);
         assert!(!env.contains_key("CARGO_BIN_EXE_team-agent"));
     }
 

package/crates/team-agent/src/layout/worker_window_helpers.rs

@@ -17,6 +17,8 @@ pub fn provider_window_name(provider: Provider) -> &'static str {
         Provider::Codex => "codex",
         Provider::Copilot => "copilot",
         Provider::GeminiCli => "gemini",
+        Provider::Grok => "grok",
+        Provider::CursorAgent => "agent",
         Provider::Fake => "fake",
     }
 }

package/crates/team-agent/src/leader/provider_attribution.rs

@@ -17,6 +17,11 @@ const COMMAND_GRAMMAR_PROVIDER_COMMANDS: &[(&str, Provider)] = &[
     ("codex", Provider::Codex),
     ("copilot", Provider::Copilot),
     ("gemini", Provider::GeminiCli),
+    ("grok", Provider::Grok),
+    // NOTE: Cursor `agent` binary is NOT added here — command-text attribution
+    // is a substring contains() match in table order; `"agent"` would also
+    // match the framework's own `team-agent` binary and mis-attribute leader
+    // panes. CursorAgent panes need env/argv-based attribution (TODO 0.5.67).
     ("fake", Provider::Fake),
 ];
 
@@ -91,11 +96,37 @@ fn provider_from_pid_env(pid: u32) -> Option<Provider> {
 
 fn provider_from_command_text(text: &str) -> Option<Provider> {
     let lower = text.to_ascii_lowercase();
+    if cursor_agent_command_text(&lower) {
+        return Some(Provider::CursorAgent);
+    }
     COMMAND_GRAMMAR_PROVIDER_COMMANDS
         .iter()
         .find_map(|(needle, provider)| lower.contains(needle).then_some(*provider))
 }
 
+/// Cursor 二进制名为 `agent`，不能做 substring contains（会误伤 `team-agent`）。
+/// 认精确 token `cursor-agent` / `…/agent`，且必须带 `--sandbox` 或 `--trust`。
+fn cursor_agent_command_text(lower: &str) -> bool {
+    let tokens: Vec<&str> = lower.split_whitespace().collect();
+    if tokens.iter().any(|tok| {
+        *tok == "team-agent"
+            || tok.ends_with("/team-agent")
+            || tok.ends_with("\\team-agent")
+    }) {
+        return false;
+    }
+    let is_cursor_bin = tokens.iter().any(|tok| {
+        *tok == "cursor-agent"
+            || *tok == "agent"
+            || tok.ends_with("/cursor-agent")
+            || tok.ends_with("/agent")
+            || tok.ends_with("\\cursor-agent")
+            || tok.ends_with("\\agent")
+    });
+    let has_cursor_flag = tokens.iter().any(|tok| *tok == "--sandbox" || *tok == "--trust");
+    is_cursor_bin && has_cursor_flag
+}
+
 fn provider_from_env_text(text: &str) -> Option<Provider> {
     text.split(|ch: char| ch == '\0' || ch.is_ascii_whitespace())
         .find_map(|part| part.strip_prefix("TEAM_AGENT_LEADER_PROVIDER="))
@@ -180,6 +211,28 @@ mod tests {
         );
     }
 
+    #[test]
+    fn cursor_agent_basename_with_trust_is_attributed() {
+        assert_eq!(
+            attribute_command_provider("cursor-agent --trust --sandbox disabled --workspace /ws"),
+            Some(Provider::CursorAgent)
+        );
+        assert_eq!(
+            attribute_command_provider("agent --trust --sandbox disabled --workspace /ws"),
+            Some(Provider::CursorAgent)
+        );
+    }
+
+    #[test]
+    fn team_agent_binary_is_not_cursor() {
+        assert_ne!(
+            attribute_command_provider("team-agent --trust claude"),
+            Some(Provider::CursorAgent)
+        );
+        assert_eq!(attribute_command_provider("team-agent status"), None);
+        assert_eq!(attribute_command_provider("agent"), None);
+    }
+
     #[test]
     fn pane_env_provider_wins_over_command() {
         let mut pane = pane("codex", None);