@team-agent/installer 0.5.66 → 0.5.68

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::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,11 @@ 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::Fake => {}
     }
     unsets
@@ -893,6 +963,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 +991,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::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 +1033,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 +1049,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 +1074,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),

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

@@ -1,3 +1,24 @@
+//! ---
+//! purpose: 对 compatible_api 席位做发车前的 profile 连通性冒烟
+//! contract:
+//!   provides:
+//!     - name: profile_smoke_checks_for_agents_with_profile_dir
+//!       what: 对一组 agent 逐个冒烟，可指定优先查找的 profile 目录
+//!     - name: profile_smoke_checks_for_agents
+//!       what: 对一组 agent 逐个冒烟，返回逐个结果
+//!     - name: smoke_check_agent_profile
+//!       what: 单 agent 冒烟，非 compatible_api 直接判 not_required
+//!     - name: format_profile_smoke_failures
+//!       what: 把失败结果排成一行可读文本
+//!   depends:
+//!     - crate::lifecycle::profile_launch
+//!     - crate::provider::wire
+//! boundary:
+//!   - 只读 profile 并发探测请求，不改 profile、不写 runtime state
+//!   - 不做重试与退避，超时即判失败
+//!   - 结果里不带密钥值
+//! maturity: wired
+//! ---
 use std::collections::BTreeMap;
 use std::io::Write as _;
 use std::path::Path;
@@ -13,6 +34,13 @@ use crate::provider::wire::provider_wire;
 
 pub(crate) const DEFAULT_PROFILE_SMOKE_TIMEOUT: Duration = Duration::from_secs(8);
 
+/// ---
+/// purpose: 用默认 profile 目录对一组 agent 逐个冒烟
+/// params:
+///   agents: spec 里的 agent 节点列表
+///   timeout: 单次探测的超时
+/// returns: 与入参同序的逐 agent 结果 JSON
+/// ---
 pub(crate) fn profile_smoke_checks_for_agents(
     workspace: &Path,
     agents: &[YamlValue],
@@ -21,6 +49,12 @@ pub(crate) fn profile_smoke_checks_for_agents(
     profile_smoke_checks_for_agents_with_profile_dir(workspace, agents, None, timeout)
 }
 
+/// ---
+/// purpose: 用指定 profile 目录对一组 agent 逐个冒烟
+/// params:
+///   profile_dir: 优先查找的 profile 目录，None 表示只用默认查找顺序
+/// returns: 与入参同序的逐 agent 结果 JSON
+/// ---
 pub(crate) fn profile_smoke_checks_for_agents_with_profile_dir(
     workspace: &Path,
     agents: &[YamlValue],
@@ -33,6 +67,13 @@ pub(crate) fn profile_smoke_checks_for_agents_with_profile_dir(
         .collect()
 }
 
+/// ---
+/// purpose: 单个 agent 的 profile 冒烟
+/// params:
+///   agent: 单个 agent 节点，缺 provider 按 codex、缺 auth_mode 按 subscription
+///   timeout: 单次 HTTP 探测的超时
+/// returns: 结果 JSON。非 compatible_api 记 not_required，profile 里关掉冒烟记 skipped_by_profile，其余走真实请求
+/// ---
 pub(crate) fn smoke_check_agent_profile(
     workspace: &Path,
     agent: &YamlValue,
@@ -108,6 +149,10 @@ pub(crate) fn smoke_check_agent_profile(
     result
 }
 
+/// ---
+/// purpose: 把失败结果拼成一行人类可读的摘要
+/// returns: 以分号分隔的 agent 与原因，缺字段时退化成 agent 与 failed
+/// ---
 pub(crate) fn format_profile_smoke_failures(failures: &[Value]) -> String {
     failures
         .iter()
@@ -187,7 +232,12 @@ impl SmokeTarget {
             }
             // C-7-1 cr verdict: copilot 一期 subscription-only,无 BYOK HTTP smoke
             // 入口;同 GeminiCli/Fake 走 unsupported_provider_smoke_skipped。
-            Provider::Copilot | Provider::GeminiCli | Provider::Fake => {
+            // 0.5.67: grok/cursor_agent 同走 skipped (一期 subscription 已登录态)。
+            Provider::Copilot
+            | Provider::Grok
+            | Provider::CursorAgent
+            | Provider::GeminiCli
+            | Provider::Fake => {
                 Err("unsupported_provider_smoke_skipped")
             }
         }

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

@@ -1,9 +1,52 @@
+//! ---
+//! purpose: 单席位的起、停与重置，全部在 workspace 级生命周期锁下串行
+//! contract:
+//!   provides:
+//!     - name: start_agent
+//!       what: 起或复活一席，按四象限定出 resume 或 fresh
+//!     - name: stop_agent
+//!       what: 停一席，按 pane、同角色残留 pane、窗口三级收敛并取排空证据
+//!     - name: reset_agent
+//!       what: 必须显式丢弃会话，停席后换血再起
+//!     - name: start_agent_at_paths
+//!       what: 起席的实体实现，owner 门、暂停判定、启动模式决策与落 state
+//!     - name: drain_old_pane_and_pid
+//!       what: 有界轮询等旧 pane 与旧进程消失，产出可核的证据载荷
+//!   depends:
+//!     - crate::lifecycle::lock
+//!     - crate::lifecycle::restart::selection
+//!     - crate::lifecycle::restart::remove
+//!     - crate::lifecycle::restart::team_state
+//!     - crate::lifecycle::launch
+//!     - crate::state::projection
+//!     - crate::state::persist
+//!     - crate::platform::process
+//!     - crate::lifecycle::profile_launch
+//!     - crate::lifecycle::worker_command_context
+//!     - crate::event_log::EventLog
+//! boundary:
+//!   - 每个对外入口先取 workspace 级生命周期锁，本文件不做无锁写
+//!   - owner 门先于未知席位报错，权限判定不被存在性判定绕过
+//!   - reset 未显式丢弃会话时直接拒绝，不擅自换血
+//!   - 排空是有界等待，等不到只如实记录，不无限阻塞
+//! maturity: wired
+//! ---
 use super::common::*;
 use super::selection::decide_start_mode;
 use super::team_state::write_team_state;
 use super::*;
 use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest};
 
+/// ---
+/// purpose: 起或复活一席的对外入口
+/// params:
+///   force: 窗口已存在时也重起
+///   open_display: 是否开显示
+///   allow_fresh: resume 依据缺失时允许改跑全新会话
+/// returns: Running、Noop 或 Paused
+/// errors: 选不到 team 返回 TeamSelect，owner 门不过返回 OwnerRefused，席位不存在返回 RequirementUnmet
+/// contract_id: lifecycle.start_agent.entry
+/// ---
 /// `start_agent(workspace, agent_id, force, open_display, allow_fresh, team)`
 /// (`lifecycle/start.py:72`)。`_runtime_lock("start-agent")` 下串行:resume-or-fresh
 /// 决策、resume 窗口退出回退 fresh、起后投递 pending message、起 coordinator。
@@ -39,6 +82,12 @@ pub fn start_agent(
     )
 }
 
+/// ---
+/// purpose: 带注入 transport 的起席入口；未指定 team 且解析失败时退回把入参 workspace 当作两个路径
+/// returns: Running、Noop 或 Paused
+/// errors: 指定了 team 而解析失败时透传该错误，其余同 start_agent
+/// contract_id: lifecycle.start_agent.entry
+/// ---
 /// `start_agent` with an injected transport — wires the single-worker resume/fresh spawn +
 /// start_coordinator (rt-host-a sweep: was a stub returning RequirementUnmet at the spawn boundary).
 #[allow(clippy::too_many_arguments)]
@@ -80,6 +129,14 @@ pub(crate) fn start_agent_with_transport(
     )
 }
 
+/// ---
+/// purpose: 起席的实体实现，读团队作用域 state、过 owner 门、定启动模式、spawn 并标记已起
+/// params:
+///   spec_workspace: spec 所在目录，用于补回席位的命令上下文
+///   open_display: 当前实现未直接使用，仅参与自适应布局判定
+/// returns: 席位暂停时直接返回 Paused，其余按启动模式返回 Running 或 Noop
+/// errors: 读 state 失败返回 StatePersist，owner 门不过返回 OwnerRefused，席位不存在返回 RequirementUnmet
+/// ---
 #[allow(clippy::too_many_arguments)]
 pub(crate) fn start_agent_at_paths(
     workspace: &Path,
@@ -788,6 +845,13 @@ fn tmux_start_mode_for_spawn(
 // 0.4.6 Stage 1: reset/start clean-boundary helpers
 // ═══════════════════════════════════════════════════════════════════════
 
+/// ---
+/// purpose: 有界轮询等待旧 pane 不可达且旧进程退出
+/// params:
+///   old_pane: 旧 pane，None 视作已死
+///   old_pid: 旧进程号，None 视作已退出
+/// returns: 证据载荷，含两者是否确认消失与实际等待毫秒数；到上限仍未消失也照实返回
+/// ---
 /// Bounded polling: wait for the old pane to become unreachable AND, when
 /// possible, for the old pane_pid to exit. Returns a JSON evidence blob
 /// recording the observed transition for events.
@@ -830,6 +894,10 @@ pub(super) fn drain_old_pane_and_pid(
     })
 }
 
+/// ---
+/// purpose: 尽力探测某进程号是否还活着
+/// returns: 由平台层给出的判定
+/// ---
 /// Best-effort liveness probe for a pid.
 ///
 /// 0.5.x Windows portability Batch 3: routes through
@@ -843,6 +911,10 @@ pub(super) fn pid_is_alive(pid: u32) -> bool {
     crate::platform::process::pid_is_alive(pid)
 }
 
+/// ---
+/// purpose: 从 state 里读该席位的 pane 进程号
+/// returns: 存在且是无符号整数时返回它，否则 None
+/// ---
 /// Read state.agents[agent_id].pane_pid (u32) from the runtime state.
 pub(super) fn state_pane_pid(state: &serde_json::Value, agent_id: &AgentId) -> Option<u32> {
     state
@@ -853,6 +925,10 @@ pub(super) fn state_pane_pid(state: &serde_json::Value, agent_id: &AgentId) -> O
         .map(|p| p as u32)
 }
 
+/// ---
+/// purpose: 算出该席位下一次的 spawn 世代号
+/// returns: 当前值加一，缺失时按 0 起算；世代号用于把捕获与事件归因到本次进程
+/// ---
 /// Read + increment state.agents[agent_id].spawn_epoch. The epoch is a
 /// monotonic counter persisted with the agent row that uniquely tags each
 /// fresh-start / reset / restart cycle. Subsequent capture / event /
@@ -869,6 +945,12 @@ pub(super) fn next_spawn_epoch(state: &serde_json::Value, agent_id: &AgentId) ->
     current.saturating_add(1)
 }
 
+/// ---
+/// purpose: 停一席的对外入口
+/// returns: 停止报告
+/// errors: 选不到 team 返回 TeamSelect，席位不存在返回 RequirementUnmet
+/// contract_id: lifecycle.stop_agent.entry
+/// ---
 /// `stop_agent(workspace, agent_id, team)`(`lifecycle/operations.py:62`)。
 /// owner-gate → kill window → **同时关显示** → 写 state。
 pub fn stop_agent(
@@ -895,6 +977,12 @@ pub fn stop_agent(
     )
 }
 
+/// ---
+/// purpose: 带注入 transport 的停席入口
+/// returns: 停止报告
+/// errors: 同 stop_agent
+/// contract_id: lifecycle.stop_agent.entry
+/// ---
 pub(crate) fn stop_agent_with_transport(
     workspace: &Path,
     agent_id: &AgentId,
@@ -919,6 +1007,11 @@ pub(crate) fn stop_agent_with_transport(
     )
 }
 
+/// ---
+/// purpose: 停席的实体实现，解析席位、收敛杀 pane 与窗口、取排空证据后落 state
+/// returns: 停止报告；注意报告里的显示已关闭字段恒为真，不反映实际关显示结果
+/// errors: 席位解析不到实体返回 RequirementUnmet，写 state 失败返回 StatePersist
+/// ---
 pub(super) fn stop_agent_at_paths(
     workspace: &Path,
     spec_workspace: &Path,
@@ -1076,6 +1169,13 @@ pub(super) fn stop_agent_at_paths(
     })
 }
 
+/// ---
+/// purpose: 取团队作用域的投影 state，把选择拒绝转成带原因的错误
+/// params:
+///   team: 目标团队，None 时按唯一性选
+/// returns: 投影后的 state
+/// errors: 目标歧义或选不出时返回 TeamSelect 并在消息里带原因与细节，读取失败返回 StatePersist
+/// ---
 /// golden `resolve_team_scoped_state` (state.py:243): returns the team-scoped projected state, or
 /// surfaces the refusal dict (`team_target_ambiguous` / `team_target_unresolved`) as a typed error
 /// BEFORE the owner gate / unknown-worker raise (operations.py:64-66). The lifecycle return types are
@@ -1251,6 +1351,14 @@ fn mark_agent_started(
     Ok(())
 }
 
+/// ---
+/// purpose: 重置一席的对外入口
+/// params:
+///   discard_session: 必须为真，否则直接返回拒绝
+/// returns: 重置结果，未显式丢弃会话时返回 Refused
+/// errors: 选不到 team 返回 TeamSelect，其余透传实体实现
+/// contract_id: lifecycle.reset_agent.entry
+/// ---
 /// `reset_agent(workspace, agent_id, discard_session, open_display, team)`
 /// (`lifecycle/operations.py:102`)。discard + 重起;**未传 discard_session → 拒绝**。
 pub fn reset_agent(
@@ -1286,6 +1394,14 @@ pub fn reset_agent(
     )
 }
 
+/// ---
+/// purpose: 带注入 transport 的重置入口
+/// params:
+///   discard_session: 必须为真，否则直接返回拒绝
+/// returns: 重置结果
+/// errors: 同 reset_agent
+/// contract_id: lifecycle.reset_agent.entry
+/// ---
 pub(crate) fn reset_agent_with_transport(
     workspace: &Path,
     agent_id: &AgentId,
@@ -1783,6 +1899,14 @@ fn write_stop_complete_event(
     Ok(())
 }
 
+/// ---
+/// purpose: 写一条停席排空证据事件
+/// params:
+///   target: 被停的目标描述
+///   drain: 排空证据载荷，其字段被并进事件顶层
+/// returns: 成功返回空值
+/// errors: 事件写入失败时返回 StatePersist
+/// ---
 /// 0.4.6 Stage 1: drain evidence for the old pane+pid after stop. Fires
 /// during reset/stop so operators can see whether the prior worker really
 /// went away or stuck around inside the resp budget.