@team-agent/installer 0.5.66 → 0.5.69

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,13 @@ 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::Pi
+            | 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,
@@ -342,85 +399,97 @@ pub(crate) fn start_agent_at_paths(
         return Err(error);
     }
     let actual_spawn_window = spawn.spawn.window.as_str().to_string();
-    mark_agent_started(
-        &mut state,
-        agent_id,
-        &actual_spawn_window,
-        &spawn,
-        transport,
-        &safety,
-        start_mode,
-    )?;
-    // 0.5.66 bypass 单源 §2.7:启动即带 bypass → 审计留痕。
-    if safety.enabled {
-        let state_agent = state
-            .get("agents")
-            .and_then(|v| v.get(agent_id.as_str()));
-        let _ = crate::event_log::EventLog::new(workspace).write(
-            "worker.spawn_dangerously_skip_permissions",
-            serde_json::json!({
-                "agent_id": agent_id.as_str(),
-                "role": state_agent
-                    .and_then(|a| a.get("role"))
-                    .and_then(serde_json::Value::as_str)
-                    .unwrap_or_default(),
-                "provider": state_agent
-                    .and_then(|a| a.get("provider"))
-                    .and_then(serde_json::Value::as_str)
-                    .unwrap_or_default(),
-                "trigger": "start-agent",
-                "spec_source_path": crate::lifecycle::launch::agent_id_spec_source_path(
-                    workspace, agent_id.as_str(),
-                ),
-            }),
+    let post_spawn = (|| -> Result<bool, LifecycleError> {
+        mark_agent_started(
+            &mut state,
+            agent_id,
+            &actual_spawn_window,
+            &spawn,
+            transport,
+            &safety,
+            start_mode,
+        )?;
+        // 0.5.66 bypass 单源 §2.7:启动即带 bypass → 审计留痕。
+        if safety.enabled {
+            let state_agent = state.get("agents").and_then(|v| v.get(agent_id.as_str()));
+            let _ = crate::event_log::EventLog::new(workspace).write(
+                "worker.spawn_dangerously_skip_permissions",
+                serde_json::json!({
+                    "agent_id": agent_id.as_str(),
+                    "role": state_agent
+                        .and_then(|a| a.get("role"))
+                        .and_then(serde_json::Value::as_str)
+                        .unwrap_or_default(),
+                    "provider": state_agent
+                        .and_then(|a| a.get("provider"))
+                        .and_then(serde_json::Value::as_str)
+                        .unwrap_or_default(),
+                    "trigger": "start-agent",
+                    "spec_source_path": crate::lifecycle::launch::agent_id_spec_source_path(
+                        workspace, agent_id.as_str(),
+                    ),
+                }),
+            );
+        }
+        // **0.3.24 add-agent socket drift fix**: keep `state.tmux_endpoint` /
+        // `state.tmux_socket` synchronized with the transport actually used for the
+        // spawn. Without this, add-agent / fork-agent could spawn to a socket that
+        // never gets persisted, and the next coordinator tick would re-resolve to
+        // the workspace-hash socket and lose the new pane. Annotation runs inside
+        // the same `save_restart_projected_state` window — no parallel "annotate
+        // after spawn" race with coordinator and no double source of truth.
+        crate::lifecycle::launch::annotate_runtime_tmux_endpoint(&mut state, transport, workspace);
+        let team_key = restart_projection_team_key(&state, team);
+        // 0.5.32 (`.team/artifacts/restart-resumed-stale-activity-locate.md` §5):
+        // clear the matching `agent_health` observation on the new spawn cohort
+        // so five-line status summary and status --json do not surface a stale
+        // WORKING row from the pre-shutdown process. Best-effort: DB failure
+        // must not fail the start-agent path.
+        let _ = crate::db::agent_health_capture::clear_agent_health_observation(
+            workspace, &team_key, agent_id,
         );
-    }
-    // **0.3.24 add-agent socket drift fix**: keep `state.tmux_endpoint` /
-    // `state.tmux_socket` synchronized with the transport actually used for the
-    // spawn. Without this, add-agent / fork-agent could spawn to a socket that
-    // never gets persisted, and the next coordinator tick would re-resolve to
-    // the workspace-hash socket and lose the new pane. Annotation runs inside
-    // the same `save_restart_projected_state` window — no parallel "annotate
-    // after spawn" race with coordinator and no double source of truth.
-    crate::lifecycle::launch::annotate_runtime_tmux_endpoint(&mut state, transport, workspace);
-    let team_key = restart_projection_team_key(&state, team);
-    // 0.5.32 (`.team/artifacts/restart-resumed-stale-activity-locate.md` §5):
-    // clear the matching `agent_health` observation on the new spawn cohort
-    // so five-line status summary and status --json do not surface a stale
-    // WORKING row from the pre-shutdown process. Best-effort: DB failure
-    // must not fail the start-agent path.
-    let _ = crate::db::agent_health_capture::clear_agent_health_observation(
-        workspace, &team_key, agent_id,
-    );
-    let skip_capture_backfill = if matches!(
-        start_mode,
-        StartMode::Fresh | StartMode::FreshAfterMissingRollout
-    ) {
-        vec![agent_id.as_str()]
-    } else {
-        Vec::new()
+        let skip_capture_backfill = if matches!(
+            start_mode,
+            StartMode::Fresh | StartMode::FreshAfterMissingRollout
+        ) {
+            vec![agent_id.as_str()]
+        } else {
+            Vec::new()
+        };
+        save_restart_projected_state_with_capture_backfill_skip(
+            workspace,
+            &mut state,
+            &team_key,
+            &skip_capture_backfill,
+            &[agent_id.as_str()],
+        )?;
+        write_start_agent_start_event(
+            workspace,
+            agent_id,
+            &agent,
+            provider,
+            &spawn.plan,
+            start_mode,
+            &session_name,
+            &actual_spawn_window,
+            spawn_session_id,
+            tmux_start_mode_for_spawn(&spawn, into_existing_session),
+        )?;
+        replay_worker_target_missing_messages(workspace, agent_id, &team_key, &state, transport)?;
+        Ok(start_coordinator_for_workspace(workspace, Some(&team_key))?.ok)
+    })();
+    let coordinator_started = match post_spawn {
+        Ok(started) => started,
+        Err(error) => {
+            if let Err(rollback_error) = transport.kill_pane(&spawn.spawn.pane_id) {
+                return Err(LifecycleError::RequirementUnmet(format!(
+                    "{error}; failed to roll back spawned pane {}: {rollback_error}",
+                    spawn.spawn.pane_id.as_str()
+                )));
+            }
+            return Err(error);
+        }
     };
-    save_restart_projected_state_with_capture_backfill_skip(
-        workspace,
-        &mut state,
-        &team_key,
-        &skip_capture_backfill,
-        &[agent_id.as_str()],
-    )?;
-    write_start_agent_start_event(
-        workspace,
-        agent_id,
-        &agent,
-        provider,
-        start_mode,
-        &session_name,
-        &actual_spawn_window,
-        spawn_session_id,
-        tmux_start_mode_for_spawn(&spawn, into_existing_session),
-    )?;
-    replay_worker_target_missing_messages(workspace, agent_id, &team_key, &state, transport)?;
-    let coordinator = start_coordinator_for_workspace(workspace, Some(&team_key))?;
-    let coordinator_started = coordinator.ok;
     Ok(StartAgentOutcome::Running {
         env: AgentActionEnvelope {
             agent_id: agent_id.clone(),
@@ -788,6 +857,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 +906,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 +923,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 +937,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 +957,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 +989,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 +1019,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 +1181,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 +1363,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 +1406,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,
@@ -1656,95 +1784,13 @@ fn write_start_agent_start_event(
     agent_id: &AgentId,
     agent: &serde_json::Value,
     provider: crate::provider::Provider,
+    plan: &crate::provider::CommandPlan,
     start_mode: StartMode,
     session_name: &SessionName,
     window: &str,
     session_id: Option<&SessionId>,
     tmux_start_mode: &'static str,
 ) -> Result<(), LifecycleError> {
-    let auth_mode = agent_auth_mode(agent);
-    let model = agent.get("model").and_then(|v| v.as_str());
-    let adapter = crate::provider::get_adapter(provider);
-    // Contract C / F6.4: event log must record the same context-aware argv that the
-    // actual spawn used — so the role/tools/MCP context appears in `start_agent.agent_start`.
-    let command_agent = crate::lifecycle::worker_command_context::WorkerCommandAgent::from_json(
-        agent,
-        Some(agent_id.as_str()),
-        provider,
-    )?;
-    let system_prompt =
-        crate::lifecycle::worker_command_context::compile_worker_system_prompt(&command_agent)?;
-    let tools = crate::lifecycle::worker_command_context::resolved_tool_strings_for_command(
-        &command_agent,
-        provider,
-    )?;
-    let resolved_tool_refs: Vec<&str> = tools.iter().map(String::as_str).collect();
-    let mcp_config = adapter
-        .mcp_config(auth_mode)
-        .map_err(|e| LifecycleError::Provider(e.to_string()))?;
-    let team_id = agent.get("owner_team_id").and_then(|v| v.as_str());
-    let mcp_config = crate::lifecycle::launch::resolve_mcp_config(
-        mcp_config,
-        workspace,
-        agent_id.as_str(),
-        team_id.unwrap_or(""),
-    );
-    let mcp_config_path = crate::lifecycle::launch::write_worker_mcp_config(
-        workspace,
-        agent_id.as_str(),
-        &mcp_config,
-    )?;
-    let profile_launch =
-        crate::lifecycle::profile_launch::prepare_provider_profile_launch_from_json(
-            workspace,
-            agent_id.as_str(),
-            agent,
-            Some(&mcp_config),
-        )?;
-    let command_model = profile_launch.command_overrides.model.as_deref().or(model);
-    // 0.4.x provider effort MVP: start_agent path preserves effort from the
-    // persisted agent JSON.
-    let start_agent_effort =
-        crate::lifecycle::launch::provider_effort_for_spawn_json(&agent, provider);
-    if let Some(event_value) = crate::lifecycle::launch::provider_effort_event_if_dropped_json(
-        &agent,
-        provider,
-        agent_id.as_str(),
-    ) {
-        let _ = crate::event_log::EventLog::new(workspace)
-            .write("provider.effort_unsupported", event_value);
-    }
-    let context = crate::provider::ProviderCommandContext {
-        auth_mode,
-        mcp_config: Some(&mcp_config),
-        system_prompt: Some(system_prompt.as_str()),
-        model: command_model,
-        tools: &resolved_tool_refs,
-        profile_launch: Some(&profile_launch),
-        agent_id_hint: Some(agent_id.as_str()),
-        effort: start_agent_effort,
-    };
-    let mut plan = match session_id {
-        Some(session_id) => adapter
-            .build_resume_command_plan(Some(session_id), context)
-            .map_err(|e| LifecycleError::Provider(e.to_string()))?,
-        None => adapter
-            .build_command_plan(context)
-            .map_err(|e| LifecycleError::Provider(e.to_string()))?,
-    };
-    if !plan.managed_mcp_config && !profile_launch.managed_mcp_config {
-        crate::lifecycle::launch::point_native_mcp_config_at_file(
-            &mut plan.argv,
-            provider,
-            &mcp_config_path,
-        );
-    }
-    crate::lifecycle::launch::fill_spawn_placeholders_full(
-        &mut plan.argv,
-        workspace,
-        agent_id.as_str(),
-        team_id,
-    );
     crate::event_log::EventLog::new(workspace)
         .write(
             "start_agent.agent_start",
@@ -1783,6 +1829,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.