@team-agent/installer 0.5.65 → 0.5.68

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,
@@ -181,6 +238,31 @@ pub(crate) fn start_agent_at_paths(
         );
     }
     let agent_live = agent_live && (!has_collision || noop_pane.is_some());
+    // 0.5.66 bypass 单源 §2.6 — dangerously_skip_permissions drift 挡板:
+    // Noop 路径不 spawn,若声明面(角色 md / spec)与运行面(as-launched)不一致,
+    // 拒 Noop 报明,防"改了 md 却以为生效、进程仍带旧 bypass 跑着"的暗门。
+    let file_bypass = agent
+        .get("dangerously_skip_permissions")
+        .and_then(serde_json::Value::as_bool);
+    let launched_bypass = raw_agent
+        .get("as_launched_dangerously_skip_permissions")
+        .and_then(serde_json::Value::as_bool);
+    if !force && agent_live && check_bypass_drift(file_bypass, launched_bypass) {
+        // 0.5.66 bypass 单源 §2.7:Noop drift 拒也写审计事件。
+        let _ = crate::event_log::EventLog::new(workspace).write(
+            "worker.spawn_dangerously_skip_permissions_drift_denied",
+            serde_json::json!({
+                "agent_id": agent_id.as_str(),
+                "file_value": file_bypass,
+                "launched_value": launched_bypass,
+                "action": "noop_denied_require_remove_add_or_force",
+            }),
+        );
+        return Err(LifecycleError::RequirementUnmet(format!(
+            "dangerously_skip_permissions drift for agent {agent_id}: file={file_bypass:?} but running process launched with {launched_bypass:?}. \
+             Run `remove-agent {agent_id}` then `add-agent {agent_id}` to apply, or `restart --force {agent_id}` to accept fresh spawn."
+        )));
+    }
     if !force && agent_live {
         let old_binding = pane_binding_snapshot(&raw_agent);
         let refreshed_binding = noop_pane.as_ref().map(pane_binding_from_live);
@@ -257,7 +339,10 @@ pub(crate) fn start_agent_at_paths(
     };
     let into_existing_session =
         session_live_or_default(transport, &session_name, session_name_present(&state));
-    let safety = crate::lifecycle::launch::effective_runtime_config_for_worker_spawn()?;
+    let safety = crate::lifecycle::launch::effective_runtime_config_for_worker_spawn_json(
+        &agent,
+        provider,
+    )?;
     let layout_placement = if adaptive_layout {
         crate::lifecycle::launch::adaptive_existing_placement_for_agent(
             &state,
@@ -323,6 +408,30 @@ pub(crate) fn start_agent_at_paths(
         &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
@@ -736,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.
@@ -778,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
@@ -791,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
@@ -801,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 /
@@ -817,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(
@@ -843,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,
@@ -867,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,
@@ -1024,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
@@ -1078,6 +1230,12 @@ fn mark_agent_started(
     // lifecycle/topology fields so absence == UNKNOWN until the next
     // coordinator tick or pane fallback produces a post-spawn observation.
     clear_agent_runtime_activity_observation(agent);
+    // 0.5.66 bypass 单源 §2.6:fresh spawn 那一刻记录运行面 bypass 值,
+    // 供下一次 restart 的 Noop drift 挡板比较。
+    agent.insert(
+        "as_launched_dangerously_skip_permissions".to_string(),
+        serde_json::json!(safety.enabled),
+    );
     // S1-CAPTURE-001 (0.4.8, CR M3 provider-agnostic): on a Fresh /
     // FreshAfterMissingRollout start, the prior session's authoritative
     // capture tuple MUST be cleared before persist_command_plan_state
@@ -1193,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(
@@ -1228,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,
@@ -1609,7 +1783,6 @@ fn write_start_agent_start_event(
     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 safety = crate::lifecycle::launch::effective_runtime_config_for_worker_spawn()?;
     let command_agent = crate::lifecycle::worker_command_context::WorkerCommandAgent::from_json(
         agent,
         Some(agent_id.as_str()),
@@ -1620,7 +1793,6 @@ fn write_start_agent_start_event(
     let tools = crate::lifecycle::worker_command_context::resolved_tool_strings_for_command(
         &command_agent,
         provider,
-        &safety,
     )?;
     let resolved_tool_refs: Vec<&str> = tools.iter().map(String::as_str).collect();
     let mcp_config = adapter
@@ -1727,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.
@@ -1831,6 +2011,17 @@ fn write_reset_complete_event(
     Ok(())
 }
 
+/// 0.5.66 bypass 单源 §2.6:声明面(file)与运行面(as-launched)是否 drift。
+/// 缺 as-launched(从未 spawn)= 视为未启动,不 drift(首次 Noop 无进程可比)。
+fn check_bypass_drift(file: Option<bool>, launched: Option<bool>) -> bool {
+    match (file, launched) {
+        (Some(file), Some(launched)) => file != launched,
+        _ => false,
+    }
+}
+
+#[cfg(test)]
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -1907,4 +2098,23 @@ mod tests {
             "other-agent collision checks must also include tmux_socket"
         );
     }
+
+    // 0.5.66 bypass 单源 §4.1:Noop drift 检测——声明面与运行面不一致 → drift。
+    #[test]
+    fn test_restart_noop_denied_on_drift() {
+        // file=true, launched=false → drift(改了 md 升 bypass 但进程没带)。
+        assert!(check_bypass_drift(Some(true), Some(false)));
+        // file=false, launched=true → drift(改了 md 撤 bypass 但进程还带着)。
+        assert!(check_bypass_drift(Some(false), Some(true)));
+    }
+
+    // 0.5.66 bypass 单源 §4.1:无 drift 或从未 spawn(as-launched 缺)→ 不拒。
+    #[test]
+    fn test_restart_fresh_spawn_after_drift_uses_file_value() {
+        assert!(!check_bypass_drift(Some(true), Some(true)));
+        assert!(!check_bypass_drift(Some(false), Some(false)));
+        // 从未 spawn:as-launched 缺失 → 不 drift(首次 Noop 无进程可比)。
+        assert!(!check_bypass_drift(Some(true), None));
+        assert!(!check_bypass_drift(None, None));
+    }
 }