@team-agent/installer 0.3.6 → 0.3.8

package/crates/team-agent/src/cli/status_port.rs

@@ -29,6 +29,15 @@ use rusqlite::params;
             .map_err(|e| CliError::Runtime(e.to_string()))?;
         let conn = crate::db::schema::open_db(store.db_path())
             .map_err(|e| CliError::Runtime(e.to_string()))?;
+        // B-5 / 036b N38 explicable — status 出口 runtime 块:把 coordinator_health
+        // (现状)+ undelivered backlog count 一起暴露;coordinator not running ∧
+        // backlog>0 才挂 down-hint(anti-nag)。auto-recovery 不做(user 已裁)。
+        let coordinator_running = coordinator_status_running(&health);
+        let undelivered_backlog = count_undelivered_backlog(&conn, owner_team_id)?;
+        let runtime_block = build_runtime_status_block(
+            coordinator_running,
+            undelivered_backlog,
+        );
         let agents = enrich_agents(state.get("agents"));
         let tasks = state
             .get("tasks")
@@ -68,6 +77,7 @@ use rusqlite::params;
             "latest_results": latest_result_summaries(&store, owner_team_id)?,
             "readiness": readiness,
             "coordinator": coordinator_health_value(health),
+            "runtime": runtime_block,
             "last_events": Value::Array(
                 crate::event_log::EventLog::new(workspace)
                     .tail(10)
@@ -748,6 +758,58 @@ use rusqlite::params;
         }
     }
 
+    /// B-5 / 036b N38 — status 出口的 runtime 块:把 coordinator_health 与
+    /// undelivered backlog 合体暴露。down-hint 只在【coordinator 不在跑 ∧ 有 backlog】
+    /// 两条件同时满足才挂(anti-nag);健康状态下不挂提示。auto-recovery 不做。
+    fn build_runtime_status_block(coordinator_running: bool, undelivered: i64) -> Value {
+        let mut runtime = serde_json::Map::new();
+        runtime.insert(
+            "coordinator".to_string(),
+            json!({"ok": coordinator_running}),
+        );
+        runtime.insert("undelivered".to_string(), json!(undelivered));
+        if !coordinator_running && undelivered > 0 {
+            runtime.insert(
+                "hint".to_string(),
+                json!(format!(
+                    "coordinator not running with {undelivered} undelivered — run team-agent restart"
+                )),
+            );
+        }
+        Value::Object(runtime)
+    }
+
+    /// Whether the coordinator HealthReport reflects a running tick loop. Used by the
+    /// runtime block + the hint gate.
+    fn coordinator_status_running(health: &crate::coordinator::HealthReport) -> bool {
+        matches!(health.status, crate::coordinator::CoordinatorHealthStatus::Running)
+    }
+
+    /// Count of messages currently sitting in delivery-able backlog
+    /// (accepted/pending/queued forms — not delivered / not failed / not refused).
+    /// owner_team_id scope honored when present.
+    fn count_undelivered_backlog(
+        conn: &rusqlite::Connection,
+        owner_team_id: Option<&str>,
+    ) -> Result<i64, CliError> {
+        // Backlog statuses chosen to mirror what `deliver_pending` would pick up.
+        let sql = match owner_team_id {
+            Some(_) => "select count(*) from messages
+                       where owner_team_id = ?1 and status in ('accepted','pending','queued','queued_until_trust')",
+            None => "select count(*) from messages
+                     where status in ('accepted','pending','queued','queued_until_trust')",
+        };
+        let count: i64 = match owner_team_id {
+            Some(team) => conn
+                .query_row(sql, params![team], |row| row.get(0))
+                .map_err(|e| CliError::Runtime(e.to_string()))?,
+            None => conn
+                .query_row(sql, [], |row| row.get(0))
+                .map_err(|e| CliError::Runtime(e.to_string()))?,
+        };
+        Ok(count)
+    }
+
     fn coordinator_health_value(health: crate::coordinator::HealthReport) -> Value {
         json!({
             "ok": health.ok,

package/crates/team-agent/src/cli/tests/base.rs

@@ -400,15 +400,20 @@ latest result: none";
         let payload = err.to_payload(Path::new("/tmp/cli-error-123.log"), "quick-start");
         assert_eq!(payload.reason.as_deref(), Some("tmux_session_name_conflict"));
         assert_eq!(payload.session_name.as_deref(), Some("my-team"));
+        // E8 (N38): quick-start 撞已有 runtime 引导到 restart(resume),明确 --fresh 会丢上下文。
         assert_eq!(
             payload.action,
-            "tmux session `my-team` already exists. It may be an active team. \
-Do not terminate existing tmux sessions from quick-start; \
-change `name:` in TEAM.md and run quick-start again."
+            "tmux session `my-team` already exists. It may be your own existing team. \
+To resume it use `team-agent restart` (NOT --fresh, which discards context). \
+Only if you want a separate team, change `name:` in TEAM.md and run quick-start again. \
+Never terminate existing tmux sessions from quick-start."
         );
         assert_eq!(
             payload.next_actions,
-            Some(vec!["Change `name:` in TEAM.md and run `team-agent quick-start` again.".to_string()])
+            Some(vec![
+                "If this is your existing team, resume it with `team-agent restart`.".to_string(),
+                "If you want a separate team, change `name:` in TEAM.md and run `team-agent quick-start` again.".to_string(),
+            ])
         );
     }
 

package/crates/team-agent/src/cli/tests/missing_subcommands.rs

@@ -1,4 +1,41 @@
 use super::*;
+use serial_test::serial;
+
+struct EnvUnsetGuard {
+    previous: Vec<(&'static str, Option<String>)>,
+}
+
+impl EnvUnsetGuard {
+    fn unset(keys: &[&'static str]) -> Self {
+        let previous = keys
+            .iter()
+            .map(|key| (*key, std::env::var(key).ok()))
+            .collect::<Vec<_>>();
+        for key in keys {
+            std::env::remove_var(key);
+        }
+        Self { previous }
+    }
+}
+
+impl Drop for EnvUnsetGuard {
+    fn drop(&mut self) {
+        for (key, value) in self.previous.drain(..).rev() {
+            match value {
+                Some(value) => std::env::set_var(key, value),
+                None => std::env::remove_var(key),
+            }
+        }
+    }
+}
+
+struct WorkspaceCleanup(std::path::PathBuf);
+
+impl Drop for WorkspaceCleanup {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
 
     // =========================================================================
     // WAVE-2 NON-SUB CHECKPOINT — 9 MISSING CLI subcommands (ABSENT from cli/emit.rs dispatch).
@@ -131,6 +168,36 @@ tasks:
         std::fs::write(ws.join("team.spec.yaml"), spec).unwrap();
     }
 
+    fn seed_collect_runtime_state(ws: &std::path::Path) {
+        crate::state::persist::save_runtime_state(
+            ws,
+            &json!({
+                "active_team_key": "fake-e2e",
+                "team_dir": ws.to_string_lossy().to_string(),
+                "spec_path": ws.join("team.spec.yaml").to_string_lossy().to_string(),
+                "session_name": "team-agent-fake-e2e",
+                "leader": {"id": "leader"},
+                "agents": {
+                    "fake_impl": {
+                        "status": "running",
+                        "provider": "fake",
+                        "role": "implementation_engineer",
+                        "window": "fake_impl",
+                        "owner_team_id": "fake-e2e"
+                    }
+                },
+                "tasks": [{
+                    "id": "task_impl",
+                    "title": "Fake implementation",
+                    "type": "implementation",
+                    "status": "pending",
+                    "assignee": "fake_impl"
+                }]
+            }),
+        )
+        .unwrap();
+    }
+
     // ── sessions ── golden cli/parser.py:230 `cmd_sessions` -> runtime.sessions(ws). EXIT 0.
     // `team-agent sessions --workspace <ws> --json` on an empty ws ->
     //   {"ok":true,"sessions":[],"workspace":"<ws>"}  (--json sort_keys). RED: unrouted -> Error.
@@ -169,9 +236,25 @@ tasks:
     //    "delivered_messages":[],"invalid_results":[],"ok":true,"results":{...},"state_file":"<ws>/team_state.md"}
     // RED: unrouted -> Error.
     #[test]
+    #[serial(env)]
     fn dispatch_routes_collect_with_spec() {
+        let _env = EnvUnsetGuard::unset(&[
+            "TEAM_AGENT_WORKSPACE",
+            "TEAM_AGENT_TEAM_ID",
+            "TEAM_AGENT_OWNER_TEAM_ID",
+            "TEAM_AGENT_ACTIVE_TEAM",
+            "TEAM_AGENT_ID",
+            "TEAM_AGENT_LEADER_PANE_ID",
+            "TEAM_AGENT_LEADER_SESSION_UUID",
+            "TEAM_AGENT_LEADER_SESSION_UUID_OVERRIDE",
+            "TEAM_AGENT_LEADER_PROVIDER",
+            "TMUX",
+            "TMUX_PANE",
+        ]);
         let ws = tmp_workspace();
+        let _cleanup = WorkspaceCleanup(ws.clone());
         seed_team_spec(&ws);
+        seed_collect_runtime_state(&ws);
         let code = run(&cli_argv(&["collect", "--workspace", &ws.to_string_lossy(), "--json"]), &ws);
         assert_eq!(
             code,
@@ -180,7 +263,6 @@ tasks:
              {{collected,collected_results,coordinator,delivered_messages,invalid_results,ok,results,state_file}}; \
              today -> unknown-subcommand Error"
         );
-        let _ = std::fs::remove_dir_all(&ws);
     }
 
     // ── repair-state ── golden parser.py:303 `cmd_repair_state` -> runtime.repair_state (quick_start.py:285).

package/crates/team-agent/src/cli/tests/mod.rs

@@ -94,5 +94,6 @@ mod status_send;
 mod verb_validate;
 mod verb_settle;
 mod verb_profile;
+mod verb_install_skill;
 mod main_preserved;
 mod shutdown_kill_plan;

package/crates/team-agent/src/cli/tests/run_delegation.rs

@@ -209,10 +209,18 @@ fn current_uid() -> Option<String> {
             json: true,
         };
         let _ = cmd_quick_start(&args); // real quick_start compiles the spec before any coordinator/launch step
+        // E5: spec compiled to .team/runtime/<team_key>/, NOT the user team dir.
+        let team_key = team.file_name().unwrap().to_string_lossy().to_string();
+        let workspace = crate::model::paths::team_workspace(&team).unwrap();
+        let runtime_spec = crate::model::paths::runtime_spec_path(&workspace, &team_key);
         assert!(
-            team.join("team.spec.yaml").exists(),
+            runtime_spec.exists(),
             "cmd_quick_start must delegate to crate::lifecycle::quick_start, which compiles team.spec.yaml \
-             under the team dir; the placeholder never writes it"
+             under .team/runtime/<team_key>/; the placeholder never writes it"
+        );
+        assert!(
+            !team.join("team.spec.yaml").exists(),
+            "E5: quick_start must NOT write spec into the user team dir"
         );
     }
 

package/crates/team-agent/src/cli/tests/shutdown_kill_plan.rs

@@ -1,39 +1,104 @@
-//! B5/F1 · `sessions_to_kill_sparing_leader` 纯函数单测(kill 决策下沉后锁定)。
+//! E12 (P0) · `sessions_to_kill` 纯决策单测(kill 决策下沉)。
 //!
-//! 真相源 = `team-agent-leader-` 确定性命名前缀(leader/start.rs LEADER_SESSION_PREFIX);
-//! 集成面由 tests/b5_leader_terminal_kill_red.rs 的真 tmux 契约覆盖,此处锁纯决策。
+//! spare = state 锚 session(anchor_sessions) ∪ `team-agent-leader-` 命名前缀(并集,锚优先)。
+//! 独享 socket(无 spare)才允许整 server 拆;共享/leader 在 → 逐 session kill。
+//! 集成面由 tests/b5_leader_terminal_kill_red.rs 的真 tmux 契约覆盖,此处锁纯决策 + 4 反向 case。
 
-use crate::cli::lifecycle_port::sessions_to_kill_sparing_leader;
+use crate::cli::lifecycle_port::{sessions_to_kill, KillDecision};
 use crate::transport::SessionName;
+use std::collections::BTreeSet;
 
 fn names(raw: &[&str]) -> Vec<SessionName> {
     raw.iter().map(|name| SessionName::new(*name)).collect()
 }
 
+fn anchors(raw: &[&str]) -> BTreeSet<String> {
+    raw.iter().map(|s| s.to_string()).collect()
+}
+
+// RC-4(独享 socket):仅目标 session(无 spare)→ 整 server 拆。
+#[test]
+fn rc4_exclusive_socket_kills_server() {
+    assert_eq!(
+        sessions_to_kill(&names(&["team-x", "team-y"]), &BTreeSet::new()),
+        KillDecision::KillServerExclusive
+    );
+    // 空 session 集 → 逐 kill(no-op),不整 server 拆(没东西可拆)。
+    assert_eq!(
+        sessions_to_kill(&[], &BTreeSet::new()),
+        KillDecision::KillIndividually { to_kill: vec![], spared: vec![] }
+    );
+}
+
+// RC-1(本 P0 复现):in_tmux leader 在用户 session(**无前缀**),靠 state 锚 spare → 用户 session 存活。
 #[test]
-fn no_leader_session_means_whole_server_kill() {
-    assert_eq!(sessions_to_kill_sparing_leader(&names(&["team-x"])), None);
-    assert_eq!(sessions_to_kill_sparing_leader(&[]), None);
+fn rc1_in_tmux_no_prefix_anchor_spares_user_session() {
+    let sessions = names(&["team-coder-team", "team-x"]); // 用户 session 无 leader 前缀
+    let anchor = anchors(&["team-coder-team"]); // state 锚 pane 所在 session
+    let decision = sessions_to_kill(&sessions, &anchor);
+    match decision {
+        KillDecision::KillIndividually { to_kill, spared } => {
+            assert_eq!(to_kill, names(&["team-x"]), "only non-anchor session killed");
+            assert_eq!(spared, names(&["team-coder-team"]), "user/leader session spared by anchor");
+        }
+        other => panic!("anchor session must force per-session kill, not {other:?}"),
+    }
+}
+
+// 前缀判据仍生效(并集):leader 前缀 session spare,即使无 state 锚。
+#[test]
+fn prefix_session_spared_without_anchor() {
+    let sessions = names(&["team-agent-leader-claude-ws-deadbeef", "team-x"]);
+    let decision = sessions_to_kill(&sessions, &BTreeSet::new());
+    match decision {
+        KillDecision::KillIndividually { to_kill, spared } => {
+            assert_eq!(to_kill, names(&["team-x"]));
+            assert_eq!(spared, names(&["team-agent-leader-claude-ws-deadbeef"]));
+        }
+        other => panic!("prefix session must spare, not {other:?}"),
+    }
+}
+
+// RC-2(state 损坏无锚):anchor_sessions 空 → 退命名前缀判据(此处仅前缀 spare;无前缀则全 kill)。
+// (spare_fallback_to_naming event 在 anchor_anchor_sessions 发,本纯函数只验退化后的决策。)
+#[test]
+fn rc2_no_anchor_falls_back_to_naming() {
+    // 无锚 + 有前缀 leader → 前缀 spare。
+    let with_leader = sessions_to_kill(
+        &names(&["team-agent-leader-codex-ws-cafe", "team-x"]),
+        &BTreeSet::new(),
+    );
+    assert!(matches!(with_leader, KillDecision::KillIndividually { .. }));
+    // 无锚 + 无前缀(真损坏且 in_tmux 无前缀)→ 无 spare → 独享拆(退化兜底,与历史一致)。
+    assert_eq!(
+        sessions_to_kill(&names(&["team-x"]), &BTreeSet::new()),
+        KillDecision::KillServerExclusive
+    );
 }
 
+// RC-3(共享 socket):目标 2 session + 用户 1 session(锚)→ 只 kill 目标 2,用户存活,不整 server 拆。
 #[test]
-fn leader_session_present_kills_only_non_leader_sessions() {
-    let sessions = names(&[
-        "team-agent-leader-claude-myws-deadbeef",
-        "team-x",
-        "team-y",
-    ]);
-    let to_kill = sessions_to_kill_sparing_leader(&sessions)
-        .expect("leader present must switch to per-session kills");
-    assert_eq!(to_kill, names(&["team-x", "team-y"]));
+fn rc3_shared_socket_kills_only_target_sessions() {
+    let sessions = names(&["team-a", "team-b", "user-shell"]);
+    let anchor = anchors(&["user-shell"]);
+    let decision = sessions_to_kill(&sessions, &anchor);
+    match decision {
+        KillDecision::KillIndividually { to_kill, spared } => {
+            assert_eq!(to_kill, names(&["team-a", "team-b"]));
+            assert_eq!(spared, names(&["user-shell"]));
+        }
+        other => panic!("shared socket must not whole-server kill, got {other:?}"),
+    }
 }
 
+// 并集语义:同一 session 既前缀又锚 → spare 一次(不重复)。
 #[test]
-fn only_leader_sessions_left_kills_nothing_but_keeps_server() {
-    let sessions = names(&["team-agent-leader-codex-myws-cafe0123"]);
+fn union_prefix_and_anchor_no_double_count() {
+    let sessions = names(&["team-agent-leader-claude-ws-beef"]);
+    let anchor = anchors(&["team-agent-leader-claude-ws-beef"]);
+    let decision = sessions_to_kill(&sessions, &anchor);
     assert_eq!(
-        sessions_to_kill_sparing_leader(&sessions),
-        Some(Vec::new()),
-        "a socket holding only leader sessions must not be torn down"
+        decision,
+        KillDecision::KillIndividually { to_kill: vec![], spared: names(&["team-agent-leader-claude-ws-beef"]) }
     );
 }

package/crates/team-agent/src/cli/tests/verb_install_skill.rs

@@ -0,0 +1,76 @@
+use super::*;
+
+// RED-1 根治:install-skill 必须作为真 CLI 子命令存在(此前 packaging::install_skill 未接进
+// 任何 dispatch=双重死代码,install.mjs 走自己的 JS 拷贝逻辑漏 copilot)。
+// 这里钉:① 子命令路由 ② --target all 默认 ③ --source 必需 ④ 缺 source 显式 Usage 错。
+
+fn skill_source() -> PathBuf {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static CTR: AtomicU64 = AtomicU64::new(0);
+    let dir = std::env::temp_dir().join(format!(
+        "ta-cli-installskill-src-{}-{}",
+        std::process::id(),
+        CTR.fetch_add(1, Ordering::Relaxed)
+    ));
+    std::fs::create_dir_all(dir.join("team-agent")).unwrap();
+    std::fs::write(dir.join("team-agent").join("SKILL.md"), b"---\nname: team-agent\n---\nbody\n").unwrap();
+    dir.join("team-agent")
+}
+
+#[test]
+fn dispatch_routes_install_skill_dry_run_all() {
+    let ws = tmp_workspace();
+    let source = skill_source();
+    // --dry-run 不落地(不碰真实 HOME),只验路由 + exit 0。
+    let code = run(
+        &[
+            "install-skill".to_string(),
+            "--target".to_string(),
+            "all".to_string(),
+            "--source".to_string(),
+            source.to_string_lossy().to_string(),
+            "--dry-run".to_string(),
+            "--json".to_string(),
+        ],
+        &ws,
+    );
+    assert_eq!(code, ExitCode::Ok, "`install-skill --target all --source <dir> --dry-run` must route + exit 0");
+    let _ = std::fs::remove_dir_all(&ws);
+    let _ = std::fs::remove_dir_all(source.parent().unwrap());
+}
+
+#[test]
+fn install_skill_missing_source_is_usage_error() {
+    let ws = tmp_workspace();
+    // 无 --source → Usage 错(exit 2),不静默。
+    let code = run(
+        &[
+            "install-skill".to_string(),
+            "--target".to_string(),
+            "all".to_string(),
+            "--json".to_string(),
+        ],
+        &ws,
+    );
+    assert_eq!(code, ExitCode::Error, "install-skill without --source must error (CliError::Usage -> emit_cli_error exit 1)");
+    let _ = std::fs::remove_dir_all(&ws);
+}
+
+#[test]
+fn install_skill_invalid_target_is_usage_error() {
+    let ws = tmp_workspace();
+    let source = skill_source();
+    let code = run(
+        &[
+            "install-skill".to_string(),
+            "--target".to_string(),
+            "bogus".to_string(),
+            "--source".to_string(),
+            source.to_string_lossy().to_string(),
+        ],
+        &ws,
+    );
+    assert_eq!(code, ExitCode::Error, "install-skill --target bogus must error (CliError::Usage -> emit_cli_error exit 1)");
+    let _ = std::fs::remove_dir_all(&ws);
+    let _ = std::fs::remove_dir_all(source.parent().unwrap());
+}

package/crates/team-agent/src/cli/types.rs

@@ -86,10 +86,11 @@ impl CliError {
             payload.session_name = Some(session.clone());
             if command == "quick-start" {
                 payload.action = format!(
-                    "tmux session `{session}` already exists. It may be an active team. Do not terminate existing tmux sessions from quick-start; change `name:` in TEAM.md and run quick-start again."
+                    "tmux session `{session}` already exists. It may be your own existing team. To resume it use `team-agent restart` (NOT --fresh, which discards context). Only if you want a separate team, change `name:` in TEAM.md and run quick-start again. Never terminate existing tmux sessions from quick-start."
                 );
                 payload.next_actions = Some(vec![
-                    "Change `name:` in TEAM.md and run `team-agent quick-start` again.".to_string(),
+                    "If this is your existing team, resume it with `team-agent restart`.".to_string(),
+                    "If you want a separate team, change `name:` in TEAM.md and run `team-agent quick-start` again.".to_string(),
                 ]);
             } else {
                 payload.action = format!(

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

@@ -141,56 +141,9 @@ pub fn compile_team(team_dir: &Path) -> Result<Value, ModelError> {
     let mut agents = Vec::new();
     let mut agent_ids = Vec::new();
     for path in role_paths {
-        let (meta, body) = read_front_matter(&path)?;
-        let id = required_string(&meta, &path, "name")?;
-        let role = required_string(&meta, &path, "role")?;
-        let provider = required_string(&meta, &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"))
-            .unwrap_or_else(|| "subscription".to_string());
-        if auth_mode != "subscription" && meta.get("profile").is_none() {
-            return Err(ModelError::Validation(format!(
-                "{}: profile is required when auth_mode is '{auth_mode}'",
-                path.display(),
-            )));
-        }
-        let tools = required_tools(&meta, &path)?;
-        let prompt_inline = non_empty_trimmed(&body).unwrap_or_else(|| role.clone());
-        agent_ids.push(id.clone());
-        let mut agent_items = vec![
-            ("id", Value::Str(id.clone())),
-            ("role", Value::Str(role.clone())),
-            ("provider", Value::Str(provider)),
-            ("model", model),
-            ("auth_mode", Value::Str(auth_mode)),
-            ("working_directory", Value::Str(workspace_s.clone())),
-            (
-                "system_prompt",
-                map(vec![
-                    ("inline", Value::Str(prompt_inline)),
-                    ("file", Value::Null),
-                ]),
-            ),
-            ("tools", list_str(tools)),
-            ("permission_mode", Value::Str("restricted".to_string())),
-            ("preferred_for", list_str(vec![id, role])),
-            ("avoid_for", Value::List(Vec::new())),
-            (
-                "output_contract",
-                map(vec![
-                    ("format", Value::Str("result_envelope_v1".to_string())),
-                    (
-                        "required_fields",
-                        list_str(vec!["task_id", "status", "summary", "artifacts"]),
-                    ),
-                ]),
-            ),
-        ];
-        if let Some(profile) = string_field(&meta, "profile") {
-            agent_items.push(("profile", Value::Str(profile)));
-        }
-        agents.push(map(agent_items));
+        let compiled = compile_role_agent(&path, &team_meta, &workspace_s)?;
+        agent_ids.push(compiled.id);
+        agents.push(compiled.agent);
     }
 
     let default_assignee = agent_ids.first().cloned().unwrap_or_default();
@@ -327,6 +280,76 @@ pub fn compile_team(team_dir: &Path) -> Result<Value, ModelError> {
     Ok(spec)
 }
 
+/// 单个角色文档 → 编译后的 agent spec 条目(从 [`compile_team`] 的 per-role 循环抽出)。
+/// E5 Bug1:add-agent 复用它**就地读** role 文件编译,不再 copy 进平台目录。
+pub struct CompiledRole {
+    pub id: String,
+    pub role: String,
+    pub agent: Value,
+}
+
+/// 把一份 role 文档编译成 agent spec 条目。`team_meta` 供 model/auth_mode 继承;
+/// `workspace_s` 是 working_directory。**纯读 `role_path`,无任何文件落地。**
+pub fn compile_role_agent(
+    role_path: &Path,
+    team_meta: &Value,
+    workspace_s: &str,
+) -> Result<CompiledRole, ModelError> {
+    let (meta, body) = read_front_matter(role_path)?;
+    let id = required_string(&meta, role_path, "name")?;
+    let role = required_string(&meta, role_path, "role")?;
+    let provider = required_string(&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"))
+        .unwrap_or_else(|| "subscription".to_string());
+    if auth_mode != "subscription" && meta.get("profile").is_none() {
+        return Err(ModelError::Validation(format!(
+            "{}: profile is required when auth_mode is '{auth_mode}'",
+            role_path.display(),
+        )));
+    }
+    let tools = required_tools(&meta, role_path)?;
+    let prompt_inline = non_empty_trimmed(&body).unwrap_or_else(|| role.clone());
+    let mut agent_items = vec![
+        ("id", Value::Str(id.clone())),
+        ("role", Value::Str(role.clone())),
+        ("provider", Value::Str(provider)),
+        ("model", model),
+        ("auth_mode", Value::Str(auth_mode)),
+        ("working_directory", Value::Str(workspace_s.to_string())),
+        (
+            "system_prompt",
+            map(vec![
+                ("inline", Value::Str(prompt_inline)),
+                ("file", Value::Null),
+            ]),
+        ),
+        ("tools", list_str(tools)),
+        ("permission_mode", Value::Str("restricted".to_string())),
+        ("preferred_for", list_str(vec![id.clone(), role.clone()])),
+        ("avoid_for", Value::List(Vec::new())),
+        (
+            "output_contract",
+            map(vec![
+                ("format", Value::Str("result_envelope_v1".to_string())),
+                (
+                    "required_fields",
+                    list_str(vec!["task_id", "status", "summary", "artifacts"]),
+                ),
+            ]),
+        ),
+    ];
+    if let Some(profile) = string_field(&meta, "profile") {
+        agent_items.push(("profile", Value::Str(profile)));
+    }
+    Ok(CompiledRole {
+        id,
+        role,
+        agent: map(agent_items),
+    })
+}
+
 fn map(items: Vec<(&str, Value)>) -> Value {
     Value::Map(items.into_iter().map(|(k, v)| (k.to_string(), v)).collect())
 }