@team-agent/installer 0.5.65 → 0.5.68

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

@@ -1,7 +1,29 @@
+//! ---
+//! purpose: plan 的停止与状态读取
+//! contract:
+//!   provides:
+//!     - name: halt_plan
+//!       what: 读出 plan 状态并返回 Halted 结论
+//!     - name: plan_status
+//!       what: 读出 plan 的持久化状态
+//!   depends:
+//!     - crate::lifecycle::helpers
+//! boundary:
+//!   - 只读状态文件，本文件不改写 plan 状态
+//!   - 不向席位投递任何消息
+//! maturity: wired
+//! ---
 use super::*;
 
 // ── lifecycle::orchestrator —— plan 多 stage 状态机(halt / status)──────────
 
+/// ---
+/// purpose: 对指定 plan 返回 Halted 结论
+/// params:
+///   reason: 当前实现未使用
+/// returns: Halted，理由恒为 already_terminal；注意它不写盘，磁盘上的 status 不变
+/// errors: 状态文件不存在或解析失败时返回 InvalidPlan
+/// ---
 /// `halt_plan(workspace, plan_id, reason)`(`orchestrator/__init__.py:152`)。停 plan;
 /// 非 running → 幂等返回。
 pub(crate) fn halt_plan(
@@ -25,6 +47,11 @@ pub(crate) fn halt_plan(
     })
 }
 
+/// ---
+/// purpose: 读出 plan 的持久化状态
+/// returns: 反序列化出的 PlanState
+/// errors: 状态文件不存在或解析失败时返回 InvalidPlan
+/// ---
 /// `plan_status(workspace, plan_id)`(`orchestrator/__init__.py:177`)。读 plan 持久态。
 pub(crate) fn plan_status(workspace: &Path, plan_id: &PlanId) -> Result<PlanState, LifecycleError> {
     let path = plan_state_path(workspace, plan_id);

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

@@ -1,3 +1,18 @@
+//! ---
+//! purpose: restart 拆除 worker session 之前的身份守卫，防止误杀 leader 会话
+//! contract:
+//!   provides:
+//!     - name: SessionPreflight
+//!       what: 守卫结论，通过或指出 worker session 名其实是 leader 会话名
+//!     - name: check_session_preflight
+//!       what: 纯函数检查 state 里的 session 名字段
+//!   depends:
+//!     - crate::layout::RuntimeSessions
+//! boundary:
+//!   - 纯计算，不做 IO 也不改 state
+//!   - 只判这一种异常，其他 session 异常不在本守卫范围
+//! maturity: wired
+//! ---
 //! unit-3 (Stage 1) — restart preflight session-identity guard.
 //!
 //! Single check that runs BEFORE the worker-session teardown in
@@ -27,12 +42,22 @@ pub enum SessionPreflight {
 }
 
 impl SessionPreflight {
+/// ---
+/// purpose: 判断守卫是否放行
+/// returns: 结论为 Ok 时为 true
+/// ---
     /// True when the preflight passed and the caller may proceed.
     pub fn is_ok(&self) -> bool {
         matches!(self, SessionPreflight::Ok)
     }
 }
 
+/// ---
+/// purpose: 检查 state 里的 session 名，决定接下来的 worker session 拆除是否安全
+/// params:
+///   state: runtime state
+/// returns: 发现 worker session 名带 leader 前缀时返回拒绝结论并附名字与原因，否则 Ok
+/// ---
 /// Inspect `state.json` and decide whether the upcoming worker-session
 /// kill is safe. Pure: no I/O, no mutation.
 pub fn check_session_preflight(state: &serde_json::Value) -> SessionPreflight {

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

@@ -1,3 +1,33 @@
+//! ---
+//! purpose: 整队重建，先算 resume 计划与拒绝结论，再做破坏性拆除与重起
+//! contract:
+//!   provides:
+//!     - name: restart
+//!       what: 整队重建入口，解析 team 与它实际使用的 transport 后执行
+//!     - name: restart_with_transport_with_session_convergence_deadline
+//!       what: 重建的实体实现，含入口门、spec 重建、计划分类、四种拒绝与重起
+//!     - name: RestartPhaseTimer
+//!       what: 阶段计时器，把 restart 与 launch 的分段耗时写成事件
+//!     - name: restart_candidates
+//!       what: 列出本 workspace 可重启的团队
+//!     - name: select_restart_state
+//!       what: 按 team 参数或唯一性选出重启目标
+//!   depends:
+//!     - crate::lifecycle::lock
+//!     - crate::lifecycle::display
+//!     - crate::lifecycle::restart::selection
+//!     - crate::lifecycle::restart::preflight
+//!     - crate::lifecycle::restart::remove
+//!     - crate::state::selector
+//!     - crate::state::projection
+//!     - crate::state::persist
+//!     - crate::event_log::EventLog
+//! boundary:
+//!   - 四种拒绝一律先于任何 teardown 产出，拒绝时现场不变
+//!   - 每个非 paused 席位必发一条 resume 决策事件
+//!   - 只有计划里不含 Resumed 时才并行起席，串行臂的会话消失检测没有并发等价物
+//! maturity: wired
+//! ---
 use super::common::*;
 use super::selection::classify_restart_plan_with_resume_validation;
 use super::*;
@@ -17,16 +47,31 @@ pub(crate) struct RestartPhaseTimer {
 }
 
 impl RestartPhaseTimer {
+/// ---
+/// purpose: 起一个阶段计时器
+/// returns: 以当前单调时钟为起点的计时器
+/// ---
     pub(crate) fn start() -> Self {
         Self {
             started_at: std::time::Instant::now(),
         }
     }
 
+/// ---
+/// purpose: 取从起点到现在的毫秒数
+/// returns: 毫秒数，溢出时取上限值
+/// ---
     pub(crate) fn elapsed_ms(&self) -> u64 {
         u64::try_from(self.started_at.elapsed().as_millis()).unwrap_or(u64::MAX)
     }
 
+/// ---
+/// purpose: 写一条带阶段名与已用毫秒数的事件
+/// params:
+///   kind: 事件名，restart.phase 或 launch.phase
+///   phase: 阶段名
+/// returns: 写事件失败被吞掉，不影响主流程
+/// ---
     pub(crate) fn emit(&self, workspace: &Path, kind: &'static str, phase: &'static str) {
         let event_log = crate::event_log::EventLog::new(workspace);
         let _ = event_log.write(
@@ -41,6 +86,15 @@ impl RestartPhaseTimer {
 
 // ── lifecycle::restart —— 整队 Route B resume-or-fresh 重建 ──────────────────
 
+/// ---
+/// purpose: 整队重建的对外入口
+/// params:
+///   allow_fresh: 允许把不可 resume 的席位改跑全新会话
+///   team: 指定团队，None 时按唯一性选
+/// returns: 重建报告，含成功与失败席位，或四种拒绝之一
+/// errors: 选不到 team 返回 TeamSelect，路径归一失败返回 StatePersist
+/// contract_id: lifecycle.rebuild.restart_entry
+/// ---
 /// `restart(workspace, allow_fresh, team)`(`restart/orchestration.py:26`)。整队重建:
 /// **先**算 resume 决策(Route B)+ `first_send_at` 严格校验(corrupt → hard refuse),
 /// **再**做破坏性 teardown(关显示、建 session)、起后 leader rebind、adaptive 显示重建。
@@ -53,6 +107,14 @@ pub fn restart(
     restart_with_session_convergence_deadline(workspace, allow_fresh, team, None)
 }
 
+/// ---
+/// purpose: 带会话收敛等待上限的整队重建入口
+/// params:
+///   session_converge_deadline_ms: 等待会话收敛的上限，None 用默认
+/// returns: 重建报告
+/// errors: 同 restart
+/// contract_id: lifecycle.rebuild.restart_entry
+/// ---
 pub fn restart_with_session_convergence_deadline(
     workspace: &Path,
     allow_fresh: bool,
@@ -106,6 +168,12 @@ fn resolve_restart_context(
     })
 }
 
+/// ---
+/// purpose: 带注入 transport 的整队重建入口
+/// returns: 重建报告
+/// errors: 透传实体实现的错误
+/// contract_id: lifecycle.rebuild.restart_entry
+/// ---
 /// `restart` with an injected transport (tests: recording mock; prod: real TmuxBackend). The Route-B
 /// resume/fresh worker spawn + start_coordinator are wired here over `transport`. (rt-host-a sweep:
 /// was a stub returning RequirementUnmet at the spawn boundary — never spawned/resumed/started coordinator.)
@@ -118,6 +186,13 @@ pub(crate) fn restart_with_transport(
     restart_with_transport_with_readiness_deadline(workspace, allow_fresh, team, transport, None)
 }
 
+/// ---
+/// purpose: 带就绪等待上限的重建入口
+/// params:
+///   readiness_deadline_ms: 等待就绪的上限
+/// returns: 重建报告；注意本入口把 RefusedResumeNotReady 重映射成 RefusedResumeAtomicity 并把原因记为会话捕获未收敛，两种拒绝在此入口不可分辨
+/// errors: 透传实体实现的错误
+/// ---
 pub(crate) fn restart_with_transport_with_readiness_deadline(
     workspace: &Path,
     allow_fresh: bool,
@@ -158,6 +233,14 @@ pub(crate) fn restart_with_transport_with_readiness_deadline(
     }
 }
 
+/// ---
+/// purpose: 整队重建的实体实现
+/// params:
+///   session_converge_deadline_ms: 会话收敛等待上限
+///   readiness_deadline_ms: 就绪等待上限
+/// returns: 重建报告，或计划分类给出的拒绝结论
+/// errors: 归一路径失败返回 StatePersist；无本地 team 上下文或 spec 缺失返回 TeamSelect
+/// ---
 pub(crate) fn restart_with_transport_with_session_convergence_deadline(
     workspace: &Path,
     allow_fresh: bool,
@@ -270,7 +353,6 @@ fn restart_with_selected_team_and_transport(
     let spec_workspace = runtime_spec.parent().ok_or_else(|| {
         LifecycleError::TeamSelect("active team spec workspace not found".to_string())
     })?;
-    let safety = crate::lifecycle::launch::effective_runtime_config(&spec)?;
     // Bug 1 (0.4.2 P0): the rebuilt spec is the single source of truth for the
     // active roster. Any agent in state.agents that is NOT in the rebuilt
     // spec is a stale leftover (role doc was deleted between sessions) and
@@ -526,7 +608,6 @@ fn restart_with_selected_team_and_transport(
             &selected.team_key,
             &session_name,
             transport,
-            &safety,
             tmux_endpoint_source,
             &state,
         )
@@ -551,12 +632,25 @@ fn restart_with_selected_team_and_transport(
         if let Some(parallel_result) = parallel_result {
             match parallel_result {
                 Ok(pspawn) => {
+                    let raw_agent = state
+                        .get("agents")
+                        .and_then(|v| v.get(decision.agent_id.as_str()))
+                        .cloned()
+                        .unwrap_or(serde_json::Value::Null);
+                    let rehydrated = rehydrate_agent_command_context_from_spec(
+                        spec_workspace,
+                        &decision.agent_id,
+                        &raw_agent,
+                    );
+                    let launched_bypass = matches!(
+                        rehydrated.get("dangerously_skip_permissions"),
+                        Some(serde_json::Value::Bool(true))
+                    );
                     apply_marked_respawn(
                         &selected.run_workspace,
                         &selected.team_key,
                         &mut state,
                         transport,
-                        &safety,
                         &phase_timer,
                         decision,
                         &pspawn.spawn,
@@ -565,6 +659,7 @@ fn restart_with_selected_team_and_transport(
                         &mut successful_agents,
                         &mut failed_agents,
                         &mut fatal_resume_failure,
+                        launched_bypass,
                     );
                 }
                 Err(error) => {
@@ -709,7 +804,7 @@ fn restart_with_selected_team_and_transport(
             session_id,
             session_live,
             transport,
-            Some(&safety),
+            None,
             layout_placement.as_ref(),
             None,
             tmux_endpoint_source,
@@ -737,6 +832,10 @@ fn restart_with_selected_team_and_transport(
             }
         };
         let verify_start = std::time::Instant::now();
+        let launched_bypass = matches!(
+            agent.get("dangerously_skip_permissions"),
+            Some(serde_json::Value::Bool(true))
+        );
         if let Err(error) = verify_spawned_agent_live(&decision.agent_id, &spawn, transport)
             .and_then(|_| {
                 mark_agent_respawned(
@@ -745,7 +844,7 @@ fn restart_with_selected_team_and_transport(
                     decision.restart_mode,
                     &spawn,
                     transport,
-                    &safety,
+                    launched_bypass,
                 )
             })
         {
@@ -787,7 +886,16 @@ fn restart_with_selected_team_and_transport(
             .and_then(|agents| agents.get_mut(decision.agent_id.as_str()))
             .and_then(serde_json::Value::as_object_mut)
         {
-            persist_effective_approval_policy_for_restart(agent, &safety);
+            // 0.5.66 bypass 单源:policy 从 agent 行字段派生。
+            let agent_provider = agent
+                .get("provider")
+                .and_then(serde_json::Value::as_str)
+                .and_then(crate::provider::wire::parse_canonical_provider)
+                .unwrap_or(crate::model::enums::Provider::Codex);
+            crate::lifecycle::launch::persist_effective_approval_policy_from_agent(
+                agent,
+                agent_provider,
+            );
         }
         // 0.5.32 (`.team/artifacts/restart-resumed-stale-activity-locate.md` §5):
         // pair the state-side activity clear with a DB `agent_health` clear so
@@ -1958,7 +2066,7 @@ fn mark_agent_respawned(
     restart_mode: StartMode,
     spawn: &SpawnedAgentWindow,
     transport: &dyn crate::transport::Transport,
-    safety: &DangerousApproval,
+    launched_bypass: bool,
 ) -> Result<(), LifecycleError> {
     let Some(agent) = state
         .get_mut("agents")
@@ -2081,7 +2189,18 @@ fn mark_agent_respawned(
         }
     }
     crate::lifecycle::launch::persist_command_plan_state(agent, &spawn.plan, &spawn.profile_launch);
-    persist_effective_approval_policy_for_restart(agent, safety);
+    // 0.5.66 bypass 单源:policy 从 agent 行字段派生,不再用全队 `DangerousApproval`。
+    let agent_provider = agent
+        .get("provider")
+        .and_then(serde_json::Value::as_str)
+        .and_then(crate::provider::wire::parse_canonical_provider)
+        .unwrap_or(crate::model::enums::Provider::Codex);
+    crate::lifecycle::launch::persist_effective_approval_policy_from_agent(agent, agent_provider);
+    // 0.5.66 bypass 单源 §2.6:fresh spawn(restart)记录运行面 bypass 值。
+    agent.insert(
+        "as_launched_dangerously_skip_permissions".to_string(),
+        serde_json::json!(launched_bypass),
+    );
     if let Some(placement) = spawn.layout_placement.as_ref() {
         agent.insert(
             "layout_window".to_string(),
@@ -2510,7 +2629,6 @@ fn run_bounded_parallel_worker_spawns(
     team_key: &str,
     session_name: &SessionName,
     transport: &(dyn crate::transport::Transport),
-    safety: &DangerousApproval,
     tmux_endpoint_source: Option<&str>,
     state: &serde_json::Value,
 ) -> Vec<Option<Result<ParallelSpawnResult, String>>> {
@@ -2589,7 +2707,7 @@ fn run_bounded_parallel_worker_spawns(
         first_input.session_id.as_ref(),
         first_session_live,
         transport,
-        Some(safety),
+        None,
         first_input.layout_placement.as_ref(),
         None,
         tmux_endpoint_source,
@@ -2673,7 +2791,7 @@ fn run_bounded_parallel_worker_spawns(
                     input.session_id.as_ref(),
                     /* into_existing_session */ true,
                     transport,
-                    Some(safety),
+                    None,
                     input.layout_placement.as_ref(),
                     None,
                     tmux_endpoint_source,
@@ -2716,7 +2834,6 @@ fn apply_marked_respawn(
     team_key: &str,
     state: &mut serde_json::Value,
     transport: &(dyn crate::transport::Transport),
-    safety: &DangerousApproval,
     phase_timer: &RestartPhaseTimer,
     decision: &RestartedAgent,
     spawn: &SpawnedAgentWindow,
@@ -2725,6 +2842,7 @@ fn apply_marked_respawn(
     successful_agents: &mut Vec<RestartedAgent>,
     failed_agents: &mut Vec<RestartFailedAgent>,
     fatal_resume_failure: &mut bool,
+    launched_bypass: bool,
 ) {
     let verify_start = std::time::Instant::now();
     if let Err(error) =
@@ -2735,7 +2853,7 @@ fn apply_marked_respawn(
                 decision.restart_mode,
                 spawn,
                 transport,
-                safety,
+                launched_bypass,
             )
         })
     {
@@ -2776,7 +2894,16 @@ fn apply_marked_respawn(
         .and_then(|agents| agents.get_mut(decision.agent_id.as_str()))
         .and_then(serde_json::Value::as_object_mut)
     {
-        persist_effective_approval_policy_for_restart(agent, safety);
+        // 0.5.66 bypass 单源:policy 从 agent 行字段派生。
+        let agent_provider = agent
+            .get("provider")
+            .and_then(serde_json::Value::as_str)
+            .and_then(crate::provider::wire::parse_canonical_provider)
+            .unwrap_or(crate::model::enums::Provider::Codex);
+        crate::lifecycle::launch::persist_effective_approval_policy_from_agent(
+            agent,
+            agent_provider,
+        );
     }
     let _ = crate::db::agent_health_capture::clear_agent_health_observation(
         run_workspace,
@@ -2785,6 +2912,13 @@ fn apply_marked_respawn(
     );
 }
 
+/// ---
+/// purpose: 写一条 per-worker 的启动分段耗时事件
+/// params:
+///   source: 事件来源，launch 或 restart
+///   command_plan_ms: 命令拼装耗时，调用方给不出真实值时可能是占位 0
+/// returns: 写事件失败被吞掉
+/// ---
 /// 0.5.38 Step 1 (`.team/artifacts/startup-latency-locate.md` §5): per-worker
 /// timing tag so operators can pinpoint whether wall time is spent in
 /// command plan compilation, transport spawn, pane verification, or the
@@ -2821,6 +2955,10 @@ pub(crate) fn write_worker_spawn_timing_event(
     );
 }
 
+/// ---
+/// purpose: 从 state 里取某席位的 provider wire 名
+/// returns: 取到的名字，缺失时为 fake
+/// ---
 pub(crate) fn provider_wire_from_state<'a>(
     state: &'a serde_json::Value,
     agent_id: &str,
@@ -3068,6 +3206,11 @@ fn write_restart_resume_decision_event(
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))
 }
 
+/// ---
+/// purpose: 列出本 workspace 里可重启的团队
+/// returns: 每个团队一条候选；没有活团队但顶层 state 有可重启形状时返回它自己
+/// errors: 读 runtime state 失败时返回 StatePersist
+/// ---
 /// `restart_candidates(workspace)`(`restart/selection.py:12`)。从 snapshot + active
 /// state 收集可重启 team。
 pub(crate) fn restart_candidates(workspace: &Path) -> Result<Vec<RestartCandidate>, LifecycleError> {
@@ -3090,6 +3233,13 @@ pub(crate) fn restart_candidates(workspace: &Path) -> Result<Vec<RestartCandidat
         .collect())
 }
 
+/// ---
+/// purpose: 选出本次重启的目标团队
+/// params:
+///   team: 指定团队名，None 时按唯一性选
+/// returns: 选中的候选
+/// errors: 选不出或选中的 state 不具备可重启形状时返回 TeamSelect
+/// ---
 /// `select_restart_state(workspace, team)`(`restart/selection.py:49`)。按 `--team` 或
 /// 唯一性选一个;歧义/未找到 → `TeamSelect`。
 pub(crate) fn select_restart_state(
@@ -3728,7 +3878,7 @@ tasks:
             StartMode::Resumed,
             &spawn,
             &RespawnEpochTransport,
-            &disabled_safety(),
+            false,
         )
         .expect("mark respawned");