@team-agent/installer 0.5.65 → 0.5.68

package/crates/team-agent/src/compiler/tests.rs

@@ -105,6 +105,7 @@ role: Implementation Engineer
 provider: codex
 model: gpt-5.5
 auth_mode: subscription
+dangerously_skip_permissions: false
 tools:
   - fs_read
   - fs_write
@@ -189,7 +190,7 @@ fn front_matter_non_object_errors() {
 // separators=(",",":"))` with the workspace path templated to __WS__.
 // (team-agent-public v0.2.11, /tmp/probe_compiler.py.)
 
-const BASE_NOPROFILE_JSON: &str = r#"{"version":1,"team":{"name":"doc-team","mode":"supervisor_worker","objective":"Compile role docs.","workspace":"__WS__"},"leader":{"id":"leader","role":"leader","provider":"codex","model":"gpt-5.5","tools":["fs_read","fs_list","mcp_team"],"context_policy":{"keep_user_thread":true,"receive_worker_outputs":"business_messages_and_short_summaries","max_worker_result_tokens":2000}},"agents":[{"id":"implementer","role":"Implementation Engineer","provider":"codex","model":"gpt-5.5","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Implement bounded tasks and report result_envelope_v1.","file":null},"tools":["fs_read","fs_write","execute_bash","mcp_team"],"permission_mode":"restricted","communication_mode":"leader_centric","preferred_for":["implementer","Implementation Engineer"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}}],"routing":{"default_assignee":"implementer","rules":[{"id":"route-implementer","match":{"assignee":["implementer"]},"assign_to":"implementer","priority":10}]},"communication":{"protocol":"mcp_inbox","topology":"leader_centered","worker_to_worker":true,"ack_timeout_sec":60,"result_format":"result_envelope_v1","message_store":{"sqlite":".team/runtime/team.db","mirror_files":".team/messages"}},"runtime":{"backend":"tmux","display_backend":"adaptive","session_name":"team-doc-team","auto_launch":true,"require_user_approval_before_launch":true,"max_active_agents":1,"startup_order":["implementer"],"dangerous_auto_approve":false,"fast":false,"tick_interval_sec":2,"push_min_interval_sec":60,"stuck_timeout_sec":300},"context":{"state_file":"team_state.md","artifact_dir":".team/artifacts","log_dir":".team/logs","summarization":{"worker_full_logs":"retain_outside_leader_context","state_update":"after_each_result"}},"tasks":[{"id":"task_initial","title":"Initial document-driven team task","type":"implementation","assignee":"implementer","deps":[],"acceptance":["Worker reports valid result_envelope_v1"],"status":"pending","requires_tools":["mcp_team"],"files":[],"risk":"low"}]}"#;
+const BASE_NOPROFILE_JSON: &str = r#"{"version":1,"team":{"name":"doc-team","mode":"supervisor_worker","objective":"Compile role docs.","workspace":"__WS__"},"leader":{"id":"leader","role":"leader","provider":"codex","model":"gpt-5.5","tools":["fs_read","fs_list","mcp_team"],"context_policy":{"keep_user_thread":true,"receive_worker_outputs":"business_messages_and_short_summaries","max_worker_result_tokens":2000}},"agents":[{"id":"implementer","role":"Implementation Engineer","provider":"codex","model":"gpt-5.5","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Implement bounded tasks and report result_envelope_v1.","file":null},"tools":["fs_read","fs_write","execute_bash","mcp_team"],"dangerously_skip_permissions":false,"communication_mode":"leader_centric","preferred_for":["implementer","Implementation Engineer"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}}],"routing":{"default_assignee":"implementer","rules":[{"id":"route-implementer","match":{"assignee":["implementer"]},"assign_to":"implementer","priority":10}]},"communication":{"protocol":"mcp_inbox","topology":"leader_centered","worker_to_worker":true,"ack_timeout_sec":60,"result_format":"result_envelope_v1","message_store":{"sqlite":".team/runtime/team.db","mirror_files":".team/messages"}},"runtime":{"backend":"tmux","display_backend":"adaptive","session_name":"team-doc-team","auto_launch":true,"require_user_approval_before_launch":true,"max_active_agents":1,"startup_order":["implementer"],"fast":false,"tick_interval_sec":2,"push_min_interval_sec":60,"stuck_timeout_sec":300},"context":{"state_file":"team_state.md","artifact_dir":".team/artifacts","log_dir":".team/logs","summarization":{"worker_full_logs":"retain_outside_leader_context","state_update":"after_each_result"}},"tasks":[{"id":"task_initial","title":"Initial document-driven team task","type":"implementation","assignee":"implementer","deps":[],"acceptance":["Worker reports valid result_envelope_v1"],"status":"pending","requires_tools":["mcp_team"],"files":[],"risk":"low"}]}"#;
 
 #[test]
 fn compile_base_noprofile_matches_python_dict_order_and_values() {
@@ -254,12 +255,13 @@ provider: codex
 tools:
   - fs_read
   - mcp_team
+dangerously_skip_permissions: false
 ---
 
 Implement bounded tasks.
 ";
 
-const RUNTIME_DEFAULTS_JSON: &str = r#"{"version":1,"team":{"name":"doc-team","mode":"supervisor_worker","objective":"Compile role docs.","workspace":"__WS__"},"leader":{"id":"leader","role":"leader","provider":"codex","model":null,"tools":["fs_read","fs_list","mcp_team"],"context_policy":{"keep_user_thread":true,"receive_worker_outputs":"business_messages_and_short_summaries","max_worker_result_tokens":2000}},"agents":[{"id":"implementer","role":"Implementation Engineer","provider":"codex","model":"gpt-5.4","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Implement bounded tasks.","file":null},"tools":["fs_read","mcp_team"],"permission_mode":"restricted","communication_mode":"leader_centric","preferred_for":["implementer","Implementation Engineer"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}}],"routing":{"default_assignee":"implementer","rules":[{"id":"route-implementer","match":{"assignee":["implementer"]},"assign_to":"implementer","priority":10}]},"communication":{"protocol":"mcp_inbox","topology":"leader_centered","worker_to_worker":true,"ack_timeout_sec":60,"result_format":"result_envelope_v1","message_store":{"sqlite":".team/runtime/team.db","mirror_files":".team/messages"}},"runtime":{"backend":"tmux","display_backend":"ghostty_window","session_name":"team-doc-team","auto_launch":true,"require_user_approval_before_launch":true,"max_active_agents":1,"startup_order":["implementer"],"dangerous_auto_approve":true,"fast":true,"tick_interval_sec":1,"push_min_interval_sec":3,"stuck_timeout_sec":5},"context":{"state_file":"team_state.md","artifact_dir":".team/artifacts","log_dir":".team/logs","summarization":{"worker_full_logs":"retain_outside_leader_context","state_update":"after_each_result"}},"tasks":[{"id":"task_initial","title":"Initial document-driven team task","type":"implementation","assignee":"implementer","deps":[],"acceptance":["Worker reports valid result_envelope_v1"],"status":"pending","requires_tools":["mcp_team"],"files":[],"risk":"low"}]}"#;
+const RUNTIME_DEFAULTS_JSON: &str = r#"{"version":1,"team":{"name":"doc-team","mode":"supervisor_worker","objective":"Compile role docs.","workspace":"__WS__"},"leader":{"id":"leader","role":"leader","provider":"codex","model":null,"tools":["fs_read","fs_list","mcp_team"],"context_policy":{"keep_user_thread":true,"receive_worker_outputs":"business_messages_and_short_summaries","max_worker_result_tokens":2000}},"agents":[{"id":"implementer","role":"Implementation Engineer","provider":"codex","model":"gpt-5.4","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Implement bounded tasks.","file":null},"tools":["fs_read","mcp_team"],"dangerously_skip_permissions":false,"communication_mode":"leader_centric","preferred_for":["implementer","Implementation Engineer"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}}],"routing":{"default_assignee":"implementer","rules":[{"id":"route-implementer","match":{"assignee":["implementer"]},"assign_to":"implementer","priority":10}]},"communication":{"protocol":"mcp_inbox","topology":"leader_centered","worker_to_worker":true,"ack_timeout_sec":60,"result_format":"result_envelope_v1","message_store":{"sqlite":".team/runtime/team.db","mirror_files":".team/messages"}},"runtime":{"backend":"tmux","display_backend":"ghostty_window","session_name":"team-doc-team","auto_launch":true,"require_user_approval_before_launch":true,"max_active_agents":1,"startup_order":["implementer"],"fast":true,"tick_interval_sec":1,"push_min_interval_sec":3,"stuck_timeout_sec":5},"context":{"state_file":"team_state.md","artifact_dir":".team/artifacts","log_dir":".team/logs","summarization":{"worker_full_logs":"retain_outside_leader_context","state_update":"after_each_result"}},"tasks":[{"id":"task_initial","title":"Initial document-driven team task","type":"implementation","assignee":"implementer","deps":[],"acceptance":["Worker reports valid result_envelope_v1"],"status":"pending","requires_tools":["mcp_team"],"files":[],"risk":"low"}]}"#;
 
 #[test]
 fn compile_runtime_front_matter_defaults_match_python() {
@@ -294,12 +296,13 @@ role: Editor and Defender
 provider: claude_code
 tools:
   - mcp_team
+dangerously_skip_permissions: false
 ---
 
 Edit and defend the argument.
 ";
 
-const ALIAS_JSON: &str = r#"{"version":1,"team":{"name":"debate-team","mode":"supervisor_worker","objective":"Compile thin role docs.","workspace":"__WS__"},"leader":{"id":"leader","role":"leader","provider":"codex","model":null,"tools":["fs_read","fs_list","mcp_team"],"context_policy":{"keep_user_thread":true,"receive_worker_outputs":"business_messages_and_short_summaries","max_worker_result_tokens":2000}},"agents":[{"id":"editor","role":"Editor and Defender","provider":"claude_code","model":"claude-sonnet-4-6","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Edit and defend the argument.","file":null},"tools":["mcp_team"],"permission_mode":"restricted","communication_mode":"leader_centric","preferred_for":["editor","Editor and Defender"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}}],"routing":{"default_assignee":"editor","rules":[{"id":"route-editor","match":{"assignee":["editor"]},"assign_to":"editor","priority":10}]},"communication":{"protocol":"mcp_inbox","topology":"leader_centered","worker_to_worker":true,"ack_timeout_sec":60,"result_format":"result_envelope_v1","message_store":{"sqlite":".team/runtime/team.db","mirror_files":".team/messages"}},"runtime":{"backend":"tmux","display_backend":"none","session_name":"team-debate-team","auto_launch":true,"require_user_approval_before_launch":true,"max_active_agents":1,"startup_order":["editor"],"dangerous_auto_approve":false,"fast":false,"tick_interval_sec":2,"push_min_interval_sec":60,"stuck_timeout_sec":300},"context":{"state_file":"team_state.md","artifact_dir":".team/artifacts","log_dir":".team/logs","summarization":{"worker_full_logs":"retain_outside_leader_context","state_update":"after_each_result"}},"tasks":[{"id":"task_initial","title":"Initial document-driven team task","type":"implementation","assignee":"editor","deps":[],"acceptance":["Worker reports valid result_envelope_v1"],"status":"pending","requires_tools":["mcp_team"],"files":[],"risk":"low"}]}"#;
+const ALIAS_JSON: &str = r#"{"version":1,"team":{"name":"debate-team","mode":"supervisor_worker","objective":"Compile thin role docs.","workspace":"__WS__"},"leader":{"id":"leader","role":"leader","provider":"codex","model":null,"tools":["fs_read","fs_list","mcp_team"],"context_policy":{"keep_user_thread":true,"receive_worker_outputs":"business_messages_and_short_summaries","max_worker_result_tokens":2000}},"agents":[{"id":"editor","role":"Editor and Defender","provider":"claude_code","model":"claude-sonnet-4-6","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Edit and defend the argument.","file":null},"tools":["mcp_team"],"dangerously_skip_permissions":false,"communication_mode":"leader_centric","preferred_for":["editor","Editor and Defender"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}}],"routing":{"default_assignee":"editor","rules":[{"id":"route-editor","match":{"assignee":["editor"]},"assign_to":"editor","priority":10}]},"communication":{"protocol":"mcp_inbox","topology":"leader_centered","worker_to_worker":true,"ack_timeout_sec":60,"result_format":"result_envelope_v1","message_store":{"sqlite":".team/runtime/team.db","mirror_files":".team/messages"}},"runtime":{"backend":"tmux","display_backend":"none","session_name":"team-debate-team","auto_launch":true,"require_user_approval_before_launch":true,"max_active_agents":1,"startup_order":["editor"],"fast":false,"tick_interval_sec":2,"push_min_interval_sec":60,"stuck_timeout_sec":300},"context":{"state_file":"team_state.md","artifact_dir":".team/artifacts","log_dir":".team/logs","summarization":{"worker_full_logs":"retain_outside_leader_context","state_update":"after_each_result"}},"tasks":[{"id":"task_initial","title":"Initial document-driven team task","type":"implementation","assignee":"editor","deps":[],"acceptance":["Worker reports valid result_envelope_v1"],"status":"pending","requires_tools":["mcp_team"],"files":[],"risk":"low"}]}"#;
 
 #[test]
 fn compile_provider_models_claude_code_falls_back_to_claude_alias() {
@@ -325,6 +328,7 @@ name: implementer
 role: Implementation Engineer
 provider: codex
 auth_mode: subscription
+dangerously_skip_permissions: false
 tools:
   - mcp_team
 ---
@@ -332,7 +336,7 @@ tools:
 Implement bounded tasks.
 ";
 
-const BUILTIN_JSON: &str = r#"{"version":1,"team":{"name":"default-model-team","mode":"supervisor_worker","objective":"Compile role docs without model fields.","workspace":"__WS__"},"leader":{"id":"leader","role":"leader","provider":"codex","model":null,"tools":["fs_read","fs_list","mcp_team"],"context_policy":{"keep_user_thread":true,"receive_worker_outputs":"business_messages_and_short_summaries","max_worker_result_tokens":2000}},"agents":[{"id":"implementer","role":"Implementation Engineer","provider":"codex","model":"gpt-5.5","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Implement bounded tasks.","file":null},"tools":["mcp_team"],"permission_mode":"restricted","communication_mode":"leader_centric","preferred_for":["implementer","Implementation Engineer"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}}],"routing":{"default_assignee":"implementer","rules":[{"id":"route-implementer","match":{"assignee":["implementer"]},"assign_to":"implementer","priority":10}]},"communication":{"protocol":"mcp_inbox","topology":"leader_centered","worker_to_worker":true,"ack_timeout_sec":60,"result_format":"result_envelope_v1","message_store":{"sqlite":".team/runtime/team.db","mirror_files":".team/messages"}},"runtime":{"backend":"tmux","display_backend":"none","session_name":"team-default-model-team","auto_launch":true,"require_user_approval_before_launch":true,"max_active_agents":1,"startup_order":["implementer"],"dangerous_auto_approve":false,"fast":false,"tick_interval_sec":2,"push_min_interval_sec":60,"stuck_timeout_sec":300},"context":{"state_file":"team_state.md","artifact_dir":".team/artifacts","log_dir":".team/logs","summarization":{"worker_full_logs":"retain_outside_leader_context","state_update":"after_each_result"}},"tasks":[{"id":"task_initial","title":"Initial document-driven team task","type":"implementation","assignee":"implementer","deps":[],"acceptance":["Worker reports valid result_envelope_v1"],"status":"pending","requires_tools":["mcp_team"],"files":[],"risk":"low"}]}"#;
+const BUILTIN_JSON: &str = r#"{"version":1,"team":{"name":"default-model-team","mode":"supervisor_worker","objective":"Compile role docs without model fields.","workspace":"__WS__"},"leader":{"id":"leader","role":"leader","provider":"codex","model":null,"tools":["fs_read","fs_list","mcp_team"],"context_policy":{"keep_user_thread":true,"receive_worker_outputs":"business_messages_and_short_summaries","max_worker_result_tokens":2000}},"agents":[{"id":"implementer","role":"Implementation Engineer","provider":"codex","model":"gpt-5.5","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Implement bounded tasks.","file":null},"tools":["mcp_team"],"dangerously_skip_permissions":false,"communication_mode":"leader_centric","preferred_for":["implementer","Implementation Engineer"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}}],"routing":{"default_assignee":"implementer","rules":[{"id":"route-implementer","match":{"assignee":["implementer"]},"assign_to":"implementer","priority":10}]},"communication":{"protocol":"mcp_inbox","topology":"leader_centered","worker_to_worker":true,"ack_timeout_sec":60,"result_format":"result_envelope_v1","message_store":{"sqlite":".team/runtime/team.db","mirror_files":".team/messages"}},"runtime":{"backend":"tmux","display_backend":"none","session_name":"team-default-model-team","auto_launch":true,"require_user_approval_before_launch":true,"max_active_agents":1,"startup_order":["implementer"],"fast":false,"tick_interval_sec":2,"push_min_interval_sec":60,"stuck_timeout_sec":300},"context":{"state_file":"team_state.md","artifact_dir":".team/artifacts","log_dir":".team/logs","summarization":{"worker_full_logs":"retain_outside_leader_context","state_update":"after_each_result"}},"tasks":[{"id":"task_initial","title":"Initial document-driven team task","type":"implementation","assignee":"implementer","deps":[],"acceptance":["Worker reports valid result_envelope_v1"],"status":"pending","requires_tools":["mcp_team"],"files":[],"risk":"low"}]}"#;
 
 #[test]
 fn compile_subscription_without_model_uses_builtin_provider_default() {
@@ -351,6 +355,7 @@ role: Alpha Worker
 provider: codex
 model: gpt-5.5
 auth_mode: subscription
+dangerously_skip_permissions: false
 tools:
   - mcp_team
 ---
@@ -365,6 +370,7 @@ role: Bravo Worker
 provider: codex
 model: gpt-5.5
 auth_mode: subscription
+dangerously_skip_permissions: false
 tools:
   - mcp_team
 ---
@@ -372,7 +378,7 @@ tools:
 Bravo body.
 ";
 
-const TWO_AGENTS_JSON: &str = r#"{"version":1,"team":{"name":"doc-team","mode":"supervisor_worker","objective":"Compile role docs.","workspace":"__WS__"},"leader":{"id":"leader","role":"leader","provider":"codex","model":"gpt-5.5","tools":["fs_read","fs_list","mcp_team"],"context_policy":{"keep_user_thread":true,"receive_worker_outputs":"business_messages_and_short_summaries","max_worker_result_tokens":2000}},"agents":[{"id":"alpha","role":"Alpha Worker","provider":"codex","model":"gpt-5.5","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Alpha body.","file":null},"tools":["mcp_team"],"permission_mode":"restricted","communication_mode":"leader_centric","preferred_for":["alpha","Alpha Worker"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}},{"id":"bravo","role":"Bravo Worker","provider":"codex","model":"gpt-5.5","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Bravo body.","file":null},"tools":["mcp_team"],"permission_mode":"restricted","communication_mode":"leader_centric","preferred_for":["bravo","Bravo Worker"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}}],"routing":{"default_assignee":"alpha","rules":[{"id":"route-alpha","match":{"assignee":["alpha"]},"assign_to":"alpha","priority":10},{"id":"route-bravo","match":{"assignee":["bravo"]},"assign_to":"bravo","priority":10}]},"communication":{"protocol":"mcp_inbox","topology":"leader_centered","worker_to_worker":true,"ack_timeout_sec":60,"result_format":"result_envelope_v1","message_store":{"sqlite":".team/runtime/team.db","mirror_files":".team/messages"}},"runtime":{"backend":"tmux","display_backend":"adaptive","session_name":"team-doc-team","auto_launch":true,"require_user_approval_before_launch":true,"max_active_agents":2,"startup_order":["alpha","bravo"],"dangerous_auto_approve":false,"fast":false,"tick_interval_sec":2,"push_min_interval_sec":60,"stuck_timeout_sec":300},"context":{"state_file":"team_state.md","artifact_dir":".team/artifacts","log_dir":".team/logs","summarization":{"worker_full_logs":"retain_outside_leader_context","state_update":"after_each_result"}},"tasks":[{"id":"task_initial","title":"Initial document-driven team task","type":"implementation","assignee":"alpha","deps":[],"acceptance":["Worker reports valid result_envelope_v1"],"status":"pending","requires_tools":["mcp_team"],"files":[],"risk":"low"}]}"#;
+const TWO_AGENTS_JSON: &str = r#"{"version":1,"team":{"name":"doc-team","mode":"supervisor_worker","objective":"Compile role docs.","workspace":"__WS__"},"leader":{"id":"leader","role":"leader","provider":"codex","model":"gpt-5.5","tools":["fs_read","fs_list","mcp_team"],"context_policy":{"keep_user_thread":true,"receive_worker_outputs":"business_messages_and_short_summaries","max_worker_result_tokens":2000}},"agents":[{"id":"alpha","role":"Alpha Worker","provider":"codex","model":"gpt-5.5","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Alpha body.","file":null},"tools":["mcp_team"],"dangerously_skip_permissions":false,"communication_mode":"leader_centric","preferred_for":["alpha","Alpha Worker"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}},{"id":"bravo","role":"Bravo Worker","provider":"codex","model":"gpt-5.5","auth_mode":"subscription","working_directory":"__WS__","system_prompt":{"inline":"Bravo body.","file":null},"tools":["mcp_team"],"dangerously_skip_permissions":false,"communication_mode":"leader_centric","preferred_for":["bravo","Bravo Worker"],"avoid_for":[],"output_contract":{"format":"result_envelope_v1","required_fields":["task_id","status","summary","artifacts"]}}],"routing":{"default_assignee":"alpha","rules":[{"id":"route-alpha","match":{"assignee":["alpha"]},"assign_to":"alpha","priority":10},{"id":"route-bravo","match":{"assignee":["bravo"]},"assign_to":"bravo","priority":10}]},"communication":{"protocol":"mcp_inbox","topology":"leader_centered","worker_to_worker":true,"ack_timeout_sec":60,"result_format":"result_envelope_v1","message_store":{"sqlite":".team/runtime/team.db","mirror_files":".team/messages"}},"runtime":{"backend":"tmux","display_backend":"adaptive","session_name":"team-doc-team","auto_launch":true,"require_user_approval_before_launch":true,"max_active_agents":2,"startup_order":["alpha","bravo"],"fast":false,"tick_interval_sec":2,"push_min_interval_sec":60,"stuck_timeout_sec":300},"context":{"state_file":"team_state.md","artifact_dir":".team/artifacts","log_dir":".team/logs","summarization":{"worker_full_logs":"retain_outside_leader_context","state_update":"after_each_result"}},"tasks":[{"id":"task_initial","title":"Initial document-driven team task","type":"implementation","assignee":"alpha","deps":[],"acceptance":["Worker reports valid result_envelope_v1"],"status":"pending","requires_tools":["mcp_team"],"files":[],"risk":"low"}]}"#;
 
 #[test]
 fn compile_two_agents_sorted_by_filename_with_routing_and_startup_order() {
@@ -394,6 +400,7 @@ name: implementer
 role: Implementation Engineer
 model: gpt-5.5
 auth_mode: subscription
+dangerously_skip_permissions: false
 tools:
   - mcp_team
 ---
@@ -419,6 +426,7 @@ role: Implementation Engineer
 provider: codex
 model: gpt-5.5
 auth_mode: compatible_api
+dangerously_skip_permissions: false
 tools:
   - mcp_team
 ---
@@ -448,7 +456,7 @@ fn compile_compatible_api_without_profile_errors() {
 const TM_CODEX: &str = "---\nname: T\nprovider: codex\n---\nx\n";
 
 fn role_nomodel(provider: &str) -> String {
-    format!("---\nname: w\nrole: R\nprovider: {provider}\nauth_mode: subscription\ntools:\n  - mcp_team\n---\n\nbody\n")
+    format!("---\nname: w\nrole: R\nprovider: {provider}\nauth_mode: subscription\ndangerously_skip_permissions: false\ntools:\n  - mcp_team\n---\n\nbody\n")
 }
 
 fn agent0(spec: &Value) -> &Value {
@@ -626,7 +634,7 @@ fn fix_a5_session_name_override_wins() {
 
 #[test]
 fn fix_a6_tools_shell_maps_to_execute_bash() {
-    let role = "---\nname: w\nrole: R\nprovider: codex\nauth_mode: subscription\ntools:\n  - shell\n  - mcp_team\n---\nb\n";
+    let role = "---\nname: w\nrole: R\nprovider: codex\nauth_mode: subscription\ndangerously_skip_permissions: false\ntools:\n  - shell\n  - mcp_team\n---\nb\n";
     let team = build_team(TM_CODEX, &[("w.md", role)], &[]);
     let spec = compile_team(&team).expect("shell must normalize to execute_bash and compile");
     assert_eq!(
@@ -637,7 +645,7 @@ fn fix_a6_tools_shell_maps_to_execute_bash() {
 
 #[test]
 fn fix_a6_missing_tools_errors() {
-    let role = "---\nname: w\nrole: R\nprovider: codex\nauth_mode: subscription\n---\nb\n";
+    let role = "---\nname: w\nrole: R\nprovider: codex\nauth_mode: subscription\ndangerously_skip_permissions: false\n---\nb\n";
     let team = build_team(TM_CODEX, &[("w.md", role)], &[]);
     let err = compile_team(&team).unwrap_err();
     assert!(
@@ -648,7 +656,7 @@ fn fix_a6_missing_tools_errors() {
 
 #[test]
 fn fix_a6_tools_not_a_list_errors() {
-    let role = "---\nname: w\nrole: R\nprovider: codex\nauth_mode: subscription\ntools: justastring\n---\nb\n";
+    let role = "---\nname: w\nrole: R\nprovider: codex\nauth_mode: subscription\ndangerously_skip_permissions: false\ntools: justastring\n---\nb\n";
     let team = build_team(TM_CODEX, &[("w.md", role)], &[]);
     let err = compile_team(&team).unwrap_err();
     assert!(
@@ -661,7 +669,7 @@ fn fix_a6_tools_not_a_list_errors() {
 
 #[test]
 fn fix_a7_empty_body_inline_falls_back_to_role() {
-    let role = "---\nname: w\nrole: Reviewer Role\nprovider: codex\nauth_mode: subscription\ntools:\n  - mcp_team\n---\n";
+    let role = "---\nname: w\nrole: Reviewer Role\nprovider: codex\nauth_mode: subscription\ndangerously_skip_permissions: false\ntools:\n  - mcp_team\n---\n";
     let team = build_team(TM_CODEX, &[("w.md", role)], &[]);
     let spec = compile_team(&team).unwrap();
     assert_eq!(
@@ -675,7 +683,7 @@ fn fix_a7_empty_body_inline_falls_back_to_role() {
 #[test]
 fn fix_a8_official_api_without_profile_errors() {
     // official_api (any non-subscription) without profile MUST NOT silently compile.
-    let role = "---\nname: w\nrole: R\nprovider: codex\nauth_mode: official_api\ntools:\n  - mcp_team\n---\nb\n";
+    let role = "---\nname: w\nrole: R\nprovider: codex\nauth_mode: official_api\ndangerously_skip_permissions: false\ntools:\n  - mcp_team\n---\nb\n";
     let team = build_team(TM_CODEX, &[("w.md", role)], &[]);
     let err = compile_team(&team).unwrap_err();
     assert!(
@@ -706,14 +714,9 @@ fn fix_a8_compatible_api_error_names_the_auth_mode() {
 #[test]
 fn fix_a9_bool_coercion_yes_and_one_are_true() {
     for v in ["yes", "1"] {
-        let tm = format!("---\nname: T\nprovider: codex\ndangerous_auto_approve: {v}\nworker_to_worker: {v}\n---\nx\n");
+        let tm = format!("---\nname: T\nprovider: codex\nworker_to_worker: {v}\n---\nx\n");
         let team = build_team(&tm, &[("w.md", &role_nomodel("codex"))], &[]);
         let spec = compile_team(&team).unwrap();
-        assert_eq!(
-            get_path(&spec, &["runtime", "dangerous_auto_approve"]),
-            Some(&Value::Bool(true)),
-            "value {v}"
-        );
         assert_eq!(
             get_path(&spec, &["communication", "worker_to_worker"]),
             Some(&Value::Bool(true)),
@@ -726,11 +729,11 @@ fn fix_a9_bool_coercion_yes_and_one_are_true() {
 fn fix_a9_bool_coercion_no_is_python_truthy() {
     // FLAG: Python bool("no") is TRUE (only 0/false/False are falsy). The contract
     // note said "no->false" but Python golden is no->true; we lock Python.
-    let tm = "---\nname: T\nprovider: codex\ndangerous_auto_approve: no\n---\nx\n";
+    let tm = "---\nname: T\nprovider: codex\nworker_to_worker: no\n---\nx\n";
     let team = build_team(tm, &[("w.md", &role_nomodel("codex"))], &[]);
     let spec = compile_team(&team).unwrap();
     assert_eq!(
-        get_path(&spec, &["runtime", "dangerous_auto_approve"]),
+        get_path(&spec, &["communication", "worker_to_worker"]),
         Some(&Value::Bool(true))
     );
 }
@@ -753,7 +756,7 @@ fn fix_a9_int_coercion_of_quoted_string() {
 fn fix_a10_crlf_role_doc_front_matter_is_parsed() {
     // Windows-authored \r\n doc: read_text universal-newlines normalizes before
     // the "---\n" check, so the front matter parses (current keeps \r\n → no FM).
-    let crlf_role = "---\r\nname: crlfworker\r\nrole: R\r\nprovider: codex\r\nauth_mode: subscription\r\ntools:\r\n  - mcp_team\r\n---\r\n\r\nbody\r\n";
+    let crlf_role = "---\r\nname: crlfworker\r\nrole: R\r\nprovider: codex\r\nauth_mode: subscription\r\ndangerously_skip_permissions: false\r\ntools:\r\n  - mcp_team\r\n---\r\n\r\nbody\r\n";
     let team = build_team(TM_CODEX, &[("w.md", crlf_role)], &[]);
     let spec = compile_team(&team).expect("CRLF role doc must parse its front matter");
     assert_eq!(

package/crates/team-agent/src/compiler.rs

@@ -299,10 +299,6 @@ pub fn compile_team(team_dir: &Path) -> Result<Value, ModelError> {
                     Value::Int(max_active_agents(agent_ids.len())),
                 ),
                 ("startup_order", list_str(agent_ids)),
-                (
-                    "dangerous_auto_approve",
-                    bool_field(&team_meta, "dangerous_auto_approve", false),
-                ),
                 ("fast", bool_field(&team_meta, "fast", false)),
                 (
                     "tick_interval_sec",
@@ -394,6 +390,8 @@ fn compile_role_agent_with_mode(
     let id = required_string(&meta, role_path, "name")?;
     let role = required_string(&meta, role_path, "role")?;
     let provider = required_string(&meta, role_path, "provider")?;
+    require_explicit_grok_role_model(&meta, role_path, &provider)?;
+    require_explicit_cursor_role_model(&meta, role_path, &provider)?;
     let model = resolve_model(&meta, team_meta, &provider);
     let auth_mode = string_field(&meta, "auth_mode")
         .or_else(|| string_field(team_meta, "default_auth_mode"))
@@ -421,7 +419,12 @@ fn compile_role_agent_with_mode(
             ]),
         ),
         ("tools", list_str(tools)),
-        ("permission_mode", Value::Str("restricted".to_string())),
+        // 0.5.66 bypass 单源:compiler 透传角色 md 的 `dangerously_skip_permissions`
+        // (必填 bool,spec 校验保证存在)。取代旧"恒发 permission_mode: restricted"。
+        (
+            "dangerously_skip_permissions",
+            Value::Bool(required_dangerously_skip_permissions(&meta, role_path)?),
+        ),
         (
             "communication_mode",
             Value::Str(communication_mode.as_str().to_string()),
@@ -482,6 +485,15 @@ fn compile_role_agent_with_mode(
                 effort.as_str()
             )));
         }
+        if provider_enum == Provider::CursorAgent {
+            return Err(ModelError::Validation(format!(
+                "{}: cursor_agent does not support effort '{}'. \
+The Cursor CLI has no `--effort` flag; the framework must not drop the field and still launch. \
+Remove effort from the role file (do not map it into `--model[effort=]` until that form is measured).",
+                role_path.display(),
+                effort.as_str()
+            )));
+        }
         agent_items.push(("effort", Value::Str(effort.as_str().to_string())));
     }
     Ok(CompiledRole {
@@ -549,6 +561,73 @@ fn required_string(meta: &Value, path: &Path, key: &str) -> Result<String, Model
     })
 }
 
+/// 缺 model 时框架会填内建默认（grok 上是 grok-4），席位因此静默拿到
+/// 与角色文件无关的模型和上下文窗口，而 argv 看起来完全正常。
+/// 角色文件必须自己写死；内建默认、team 级默认、CLI 全局默认都是隐式来源。
+fn require_explicit_grok_role_model(
+    meta: &Value,
+    path: &Path,
+    provider: &str,
+) -> Result<(), ModelError> {
+    if parse_canonical_provider(provider) != Some(Provider::Grok) {
+        return Ok(());
+    }
+    if string_field(meta, "model").is_some_and(|value| !value.trim().is_empty()) {
+        return Ok(());
+    }
+    Err(ModelError::Validation(format!(
+        "{}: missing front matter field model. \
+Without an explicit model the framework fills a built-in default (grok-4 for grok), \
+so the seat silently gets a model and context window that are not in the role file, \
+while argv still looks normal. The role file must name the model itself; \
+built-in defaults, team-level defaults, and the Grok CLI global default are all implicit sources. Example:\n\
+model: grok-4.6",
+        path.display()
+    )))
+}
+
+/// 缺 model 时框架曾填 builtin `sonnet-4-thinking`，本机 shim 还会剥掉该默认。
+/// 角色必须自己写死；内建默认、team 级默认、CLI 全局默认都是隐式来源。
+fn require_explicit_cursor_role_model(
+    meta: &Value,
+    path: &Path,
+    provider: &str,
+) -> Result<(), ModelError> {
+    if parse_canonical_provider(provider) != Some(Provider::CursorAgent) {
+        return Ok(());
+    }
+    if string_field(meta, "model").is_some_and(|value| !value.trim().is_empty()) {
+        return Ok(());
+    }
+    Err(ModelError::Validation(format!(
+        "{}: missing front matter field model. \
+Without an explicit model the framework fills a built-in default (sonnet-4-thinking for cursor_agent), \
+so the seat silently gets a model that is not in the role file, while argv still looks normal. \
+The role file must name the model itself; built-in defaults, team-level defaults, and the Cursor CLI default are all implicit sources. Example:\n\
+model: sonnet-4-thinking",
+        path.display()
+    )))
+}
+
+/// 0.5.66 bypass 单源:角色 md 的 `dangerously_skip_permissions` 必填 bool。
+/// 缺 = 编译失败(消息含硬串);非 bool = 同 fail-loud。
+fn required_dangerously_skip_permissions(
+    meta: &Value,
+    path: &Path,
+) -> Result<bool, ModelError> {
+    match meta.get("dangerously_skip_permissions") {
+        Some(Value::Bool(value)) => Ok(*value),
+        Some(_) => Err(ModelError::Validation(format!(
+            "{}: front matter field dangerously_skip_permissions must be a boolean. This field must be declared explicitly; it controls whether the agent launches with permission prompts bypassed.",
+            path.display()
+        ))),
+        None => Err(ModelError::Validation(format!(
+            "{}: missing front matter field dangerously_skip_permissions. This field must be declared explicitly; it controls whether the agent launches with permission prompts bypassed.",
+            path.display()
+        ))),
+    }
+}
+
 fn optional_string_value(meta: &Value, key: &str) -> Value {
     match string_field(meta, key) {
         Some(s) => Value::Str(s),

package/crates/team-agent/src/conpty/backend.rs

@@ -644,6 +644,22 @@ impl Transport for ConPtyBackend {
         Ok(SetEnvOutcome::InternalizedAtSpawn)
     }
 
+    fn set_window_option(
+        &self,
+        _session: &SessionName,
+        _window: &WindowName,
+        _option: &str,
+        _value: &str,
+    ) -> Result<(), TransportError> {
+        // Design §Transport Boundary: window options are tmux concepts; ConPTY
+        // has no per-window option registry, so this is a typed capability
+        // refusal. Callers must `let _ =` this (A-55 lockdown is best-effort).
+        Err(TransportError::MuxUnavailable {
+            backend: BackendKind::ConPty,
+            detail: "set-window-option is tmux-only".to_string(),
+        })
+    }
+
     fn has_pane(&self, pane: &PaneId) -> Result<Option<bool>, TransportError> {
         let resp = self.dispatch(Op::HasPane, serde_json::json!({"pane_id": pane.as_str()}))?;
         Ok(Some(resp.result["present"].as_bool().unwrap_or(false)))

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

@@ -1,3 +1,29 @@
+//! ---
+//! purpose: coordinator daemon 进程的宿主——装配 transport/registry，跑主循环，把 tick 的崩溃收进退避与事件
+//! contract:
+//!   provides:
+//!     - name: run_daemon
+//!       what: `team-agent coordinator --workspace ..` 子进程入口：解析 transport、构造 Coordinator、进主循环
+//!     - name: backoff_sleep_sec
+//!       what: 连续失败次数到睡眠秒数的纯函数（5→10→20→40→60→60，封顶 BACKOFF_MAX_SEC）
+//!     - name: resolve_tick_interval
+//!       what: 解析 tick 间隔并顺带确保 message store schema 可打开
+//!   depends:
+//!     - super::health
+//!     - super::tick
+//!     - super::types
+//!     - super::conpty_shim
+//!     - crate::state::persist
+//!     - crate::transport_factory
+//!     - crate::tmux_backend
+//!     - crate::message_store
+//!     - crate::event_log
+//! boundary:
+//!   - 不做单次 tick 的编排内容，tick 体在 tick.rs
+//!   - 不决定健康与否，只消费 health.rs 的判定与路径
+//!   - transport 解析失败时降级为 tmux workspace 后端保活，但不静默——降级原因写进 boot metadata
+//! maturity: wired
+//! ---
 //!
 //! daemon 主循环面(`__main__.py`)—— 退避序列 + tick 间隔解析 + 子进程入口。
 
@@ -41,6 +67,13 @@ pub struct DaemonArgs {
 /// daemon 主循环(`main`,`__main__.py:25-98`)。写 pid/meta(source=boot)、装信号→STOP、孤儿自检、
 /// catch-all + 指数退避 + tick_error 去重/抑制、tick_recovered 重置、`result.stop || once` → break。
 /// §10:返 `Result`(顶层 bin 用 anyhow 收;§12 边界)。
+/// ---
+/// purpose: daemon 进程入口——解析 transport 后端、构造 Coordinator、跑主循环直到 stop 或 --once
+/// params:
+///   args: workspace（已 resolve）、once、tick_interval_sec、可选 team_key；team_key 为空时回落到 state.active_team_key
+/// returns: 主循环正常退出（收到 STOP、tick 报 stop、或 --once 跑完一轮）时为 Ok
+/// errors: 写 pid/metadata、事件日志或 tick 间隔解析失败时返回 DaemonError
+/// ---
 pub fn run_daemon(args: DaemonArgs) -> Result<(), DaemonError> {
     // CP-1: the daemon's whole tick surface (has_session / capture / inject / list_windows / kill)
     // runs through this backend. Prefer the persisted runtime endpoint so attached explicit-socket
@@ -123,6 +156,14 @@ pub fn run_daemon(args: DaemonArgs) -> Result<(), DaemonError> {
     run_daemon_with_coordinator_and_boot_tmux(&args, &coordinator, Some(tmux_metadata))
 }
 
+/// ---
+/// purpose: 用调用方已装配好的 Coordinator 跑主循环（测试与内部复用入口，跳过 transport 解析）
+/// params:
+///   args: 与 run_daemon 同一份参数
+///   coordinator: 已注入 provider registry 与 transport 的实例
+/// returns: 与 run_daemon 相同的主循环退出语义
+/// errors: 同 run_daemon
+/// ---
 pub(crate) fn run_daemon_with_coordinator(
     args: &DaemonArgs,
     coordinator: &Coordinator,
@@ -520,6 +561,13 @@ fn current_ppid() -> u32 {
 
 /// 计算 tick 间隔(`_tick_interval`,`__main__.py:104-115`)。读 spec `runtime.tick_interval_sec`,
 /// 缺失/出错 → `DEFAULT_TICK_INTERVAL_SEC`;并确保 schema 存在(`MessageStore(workspace)`)。
+/// ---
+/// purpose: 取本 workspace 的 tick 间隔秒数，并顺带确保 message store schema 可打开
+/// params:
+///   workspace: 已 resolve 的 workspace 根
+/// returns: tick 间隔秒数；当前实现恒为 DEFAULT_TICK_INTERVAL_SEC（spec 覆盖尚未接线）
+/// errors: MessageStore::open 失败时返回 TickError
+/// ---
 pub(super) fn resolve_tick_interval(workspace: &WorkspacePath) -> Result<f64, TickError> {
     let _ = MessageStore::open(workspace.as_path())?;
     Ok(DEFAULT_TICK_INTERVAL_SEC)
@@ -527,6 +575,13 @@ pub(super) fn resolve_tick_interval(workspace: &WorkspacePath) -> Result<f64, Ti
 
 /// 退避序列(`__main__.py:65`):`min(interval * 2^min(failures-1, 5), 60.0)` → 5→10→20→40→60→60s。
 /// unit test 锁死本序列(card §85)。**纯函数,无 I/O,可直接 impl 钉死**(但 ROUND-0 仍占位)。
+/// ---
+/// purpose: 由连续失败次数算出本轮该睡多少秒的纯函数
+/// params:
+///   interval: 基准 tick 间隔秒数
+///   consecutive_failures: 至今连续失败次数；0 与 1 同视为首次失败
+/// returns: interval * 2^min(failures-1, 5)，上限 BACKOFF_MAX_SEC
+/// ---
 pub(super) fn backoff_sleep_sec(interval: f64, consecutive_failures: u32) -> f64 {
     let failures = consecutive_failures.saturating_sub(1).min(5);
     let exp = i32::try_from(failures).unwrap_or(5);

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

@@ -1,3 +1,30 @@
+//! ---
+//! purpose: Windows ConPTY shim 的生命周期主人——定位并启动 windows-shim.exe、做 Hello 握手、把可复用的连接与 pid/pipe 名记进 state
+//! contract:
+//!   provides:
+//!     - name: ensure_shim_running
+//!       what: 幂等入口：state 里记的 shim 还活着就重连，否则新起一个并握手
+//!     - name: reconnect_recorded_shim
+//!       what: 只按 state 记的 pipe 名重连并重做 Hello，绝不新起进程
+//!     - name: recorded_shim_pid
+//!       what: 读 state.transport.shim.pid，供停机路由
+//!     - name: recorded_shim_pipe_name
+//!       what: 读 state.transport.shim.pipe_name，供重连路由
+//!     - name: mark_transport_unavailable
+//!       what: shim 不可达时发 stale 家族事件并清掉 state 里的 pipe_ready
+//!   depends:
+//!     - conpty_transport
+//!     - crate::state::repository
+//!     - crate::state::persist
+//!     - crate::event_log
+//!     - crate::platform::process
+//! boundary:
+//!   - pipe_token 绝不落 state：只经子进程环境变量传递并留在本进程内存里，state 只记 pid/pipe_name/pipe_ready
+//!   - 终态失败不静默回落 tmux，交由调用方按传输不可用处理
+//!   - 重连只证明线协议可用，不做新的令牌认证
+//!   - 整个文件仅在 Windows 编译；非 Windows 调用方必须自己 cfg 门控
+//! maturity: wired
+//! ---
 //!
 //! Windows ConPTY shim lifecycle manager.
 //!
@@ -75,16 +102,28 @@ pub struct ShimHandle {
 impl ShimHandle {
     /// The connected pipe client, ready for the factory to wire into
     /// `ConPtyBackend`. Callable exactly once — takes ownership.
+    /// ---
+    /// purpose: 取走已完成 Hello 握手的管道客户端，交给传输后端接线
+    /// returns: 首次调用返回客户端并转移所有权；再次调用为 None
+    /// ---
     pub fn take_client(&mut self) -> Option<NamedPipeClient> {
         self.client.take()
     }
 
     /// The shim pid (for status + shutdown routing).
+    /// ---
+    /// purpose: 给出 shim 进程号，用于状态展示与停机路由
+    /// returns: 启动时记下的 pid；子进程句柄已被 detach 或 drop 后该值仍可读
+    /// ---
     pub fn pid(&self) -> u32 {
         self.pid
     }
 
     /// The pipe name the shim listens on.
+    /// ---
+    /// purpose: 给出 shim 正在监听的命名管道名
+    /// returns: 形如 team-agent-conpty-<hash>-<team> 的管道全名
+    /// ---
     pub fn pipe_name(&self) -> &str {
         &self.pipe_name
     }
@@ -95,6 +134,11 @@ impl ShimHandle {
     /// an explicit `platform::process::terminate_pid` via
     /// `recorded_shim_pid`. Without this call, going out of scope
     /// would terminate the shim and orphan every worker.
+    /// ---
+    /// purpose: 放弃对 shim 子进程的所有权，使本句柄析构时不再杀它
+    /// returns: shim 的 pid，供调用方日后按精确 pid 显式终止
+    /// ---
+    /// 不调用它就让句柄离开作用域，会连带杀掉 shim 并使全部 worker 变成孤儿。
     pub fn detach(mut self) -> u32 {
         // Forget the child so its own Drop doesn't run either. The
         // shim survives until an explicit kill.
@@ -453,6 +497,12 @@ fn finalize(
 /// `None` when no shim is currently registered (Unix / never-launched
 /// Windows worker). Callers use `platform::process::terminate_pid`
 /// on the returned pid.
+/// ---
+/// purpose: 从 state 读出已登记的 shim 进程号
+/// params:
+///   workspace: workspace 根
+/// returns: state.transport.shim.pid 存在且能转成 u32 时给值；没有登记过 shim（未起过或非 Windows 队）时为 None。只读状态，不做存活探测
+/// ---
 pub fn recorded_shim_pid(workspace: &Path) -> Option<u32> {
     let state = crate::state::repository::StateRepository::new(workspace)
         .load_workspace_if_exists_without_migrations()
@@ -466,6 +516,12 @@ pub fn recorded_shim_pid(workspace: &Path) -> Option<u32> {
 }
 
 /// Read `state.transport.shim.pipe_name` for reconnect routing.
+/// ---
+/// purpose: 从 state 读出已登记的 shim 管道名
+/// params:
+///   workspace: workspace 根
+/// returns: state.transport.shim.pipe_name 的字符串值；未登记时为 None
+/// ---
 pub fn recorded_shim_pipe_name(workspace: &Path) -> Option<String> {
     let state = crate::state::repository::StateRepository::new(workspace)
         .load_workspace_if_exists_without_migrations()
@@ -497,6 +553,15 @@ pub fn recorded_shim_pipe_name(workspace: &Path) -> Option<String> {
 /// This gives the "coord can die, shim survives" invariant: a fresh
 /// coord that finds a live shim just reconnects; a fresh coord that
 /// finds no shim spawns one.
+/// ---
+/// purpose: 保证本 (workspace, team) 有一个可用的 shim——这是 coordinator 侧唯一的 shim 所有权入口
+/// params:
+///   workspace: workspace 根
+///   team_key: 目标 team，进 Hello 请求的作用域
+///   workspace_hash: 管道名里用的 workspace 摘要
+/// returns: 已登记 pid 还活着且重连成功 → 复用原进程的句柄（不拥有子进程）；否则新起一个并握手，返回拥有子进程的句柄
+/// errors: 找不到 shim 可执行文件、spawn 失败、连接超时、Hello 失败或落盘 state 失败时返回对应 ShimError。重连失败不算错误，会直接落到新起那条路
+/// ---
 pub fn ensure_shim_running(
     workspace: &Path,
     team_key: &str,
@@ -541,6 +606,15 @@ pub fn ensure_shim_running(
 /// Handle returned from this fn has no owned child (the shim is
 /// somebody else's — usually a previous coord instance). `detach()`
 /// on the handle is a no-op for the child.
+/// ---
+/// purpose: 只重连 state 里已登记的 shim 并重做 Hello，用来证明线协议仍然可用
+/// params:
+///   workspace: workspace 根
+///   team_key: 目标 team，进 Hello 请求的作用域
+///   _workspace_hash: 未使用；管道名直接取自 state，不再重算
+/// returns: 连上且 Hello 回 ok 时给出不拥有子进程的句柄，对它调 detach 对子进程是空操作
+/// errors: state 里没有管道名或多次连接均失败 → ConnectTimeout；连上但 Hello 回 ok=false → HelloFailed。本函数绝不新起进程
+/// ---
 pub fn reconnect_recorded_shim(
     workspace: &Path,
     team_key: &str,
@@ -630,6 +704,14 @@ fn reconnect_hello(client: &mut NamedPipeClient, team_key: &str) -> Result<(), S
 /// The Windows-only `#[cfg]` gate is at the mod level (see
 /// `coordinator/mod.rs`); on Unix this file isn't compiled, so
 /// downstream callers must cfg-gate their reference themselves.
+/// ---
+/// purpose: 把「shim 不可达」这件事诚实地写出去——发 stale 家族事件，并清掉 state 里的就绪位
+/// params:
+///   workspace: workspace 根
+///   reason: 不可达原因，同时进事件与 state.transport.shim.unavailable_reason
+/// returns: 状态里本来就没有 shim 块时也返回 Ok。事件写入是尽力而为，写不出去不影响返回；清状态才是权威动作
+/// errors: 读写 state 失败时返回 StateError；state JSON 损坏时按空状态继续
+/// ---
 pub fn mark_transport_unavailable(workspace: &Path, reason: &str) -> Result<(), StateError> {
     // Best-effort event emission — a failed event write should not
     // fail the caller. The state-clearing step below is authoritative.