@team-agent/installer 0.5.104 → 0.5.106

package/Cargo.lock

@@ -581,7 +581,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.104"
+version = "0.5.106"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent", "crates/win-conpty-phase0", "crates/conpty-trans
 
 [workspace.package]
 edition = "2021"
-version = "0.5.104"
+version = "0.5.106"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

package/README.md

@@ -82,9 +82,11 @@ Subagents are one-shot, fire-and-forget, and can't talk to each other. Team Agen
 
 ## Status
 
-`team-agent status` prints one concise row per registered node with seven fields:
-`name`, `provider`, `runtime_status`, `activity`, `health`, `session_name`, and `tmux_command`.
-`--json` exposes the same projection as structured JSON. Missing or conflicting evidence is
+`team-agent status` prints one concise row per registered node with nine fields:
+`name`, `provider`, `model`, `effort`, `runtime_status`, `activity`, `health`, `session_name`, and `tmux_command`.
+`model` and `effort` are the last accepted launch settings, or `null` when unspecified;
+pending role-file edits and provider defaults are not inferred.
+`--json` exposes the same projection as structured JSON. Missing or conflicting runtime evidence is
 reported as `unknown`; a non-null `tmux_command` is safe to copy for the observed socket,
 session, window, and pane. `--summary` and `--detail` remain accepted for compatibility and
 do not add diagnostic or history fields. The accepted nodeprobe pairing and

package/README.zh.md

@@ -82,9 +82,10 @@ subagent 是一次性的、干完即焚、彼此不通信。Team Agent 的队友
 
 ## 状态
 
-`team-agent status` 为每个已登记节点输出七个简要字段：
-`name`、`provider`、`runtime_status`、`activity`、`health`、`session_name`、`tmux_command`。
-`--json` 与人读输出使用同一信息投影。证据缺失或冲突时显示 `unknown`；非空
+`team-agent status` 为每个已登记节点输出九个简要字段：
+`name`、`provider`、`model`、`effort`、`runtime_status`、`activity`、`health`、`session_name`、`tmux_command`。
+`model`、`effort` 来自最近已接受的启动配置，未设置时为 `null`；不会把待启动的角色编辑或猜测的 provider 默认值当作已生效。
+`--json` 与人读输出使用同一信息投影。运行态证据缺失或冲突时显示 `unknown`；非空
 `tmux_command` 可复制到已观测的 socket、session、window 和 pane。`--summary` 与
 `--detail` 保留兼容性，但不会增加诊断或历史字段。已验收 nodeprobe 的配对方式、
 operator-trusted 能力 receipt 与 fail-closed 边界见

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

@@ -174,7 +174,7 @@ fn append_reminder(text: String, reminder: &str) -> String {
     }
 }
 
-/// `cmd_status`(`commands.py:90`)。CLI status 统一为只读七字段 brief；
+/// `cmd_status`(`commands.py:90`)。CLI status 统一为只读九字段 brief；
 /// `--json` 与人读路径共享 native tmux/process projection；`--summary`/`--detail` 保留参数兼容性但不暴露诊断。
 #[cfg(test)]
 pub(crate) fn cmd_status(args: &StatusArgs) -> Result<CmdResult, CliError> {
@@ -1100,6 +1100,7 @@ pub fn cmd_start_agent(args: &StartAgentArgs) -> Result<CmdResult, CliError> {
         args.force,
         args.allow_fresh,
         args.team.as_deref(),
+        &args.role_config,
     )?;
     if value.get("agent_ids").is_none() {
         if let Some(object) = value.as_object_mut() {
@@ -1142,6 +1143,7 @@ pub fn cmd_add_agent(args: &AddAgentArgs) -> Result<CmdResult, CliError> {
         &args.role_file,
         args.team.as_deref(),
         args.force,
+        &args.role_config,
     )?;
     if value.get("agent_ids").is_none() {
         if let Some(object) = value.as_object_mut() {
@@ -1638,6 +1640,20 @@ mod tests {
         );
     }
 
+    #[test]
+    fn reminders_only_recommend_supported_result_commands() {
+        let reminder = crate::cli::QUICK_START_REMINDER;
+        assert!(reminder.contains("Use team-agent status / inbox instead."));
+        for text in [
+            reminder,
+            crate::cli::STATUS_REMINDER,
+            crate::cli::SEND_REMINDER,
+            &quickstart_human(&json!({"summary": "team started"})),
+        ] {
+            assert!(!text.contains("collect"), "removed CLI command leaked: {text}");
+        }
+    }
+
     #[test]
     fn e13_quickstart_human_summary_only_when_no_attach() {
         let value = json!({"summary": "quick-start complete"});

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

@@ -340,15 +340,21 @@ fn command_help(command: Option<&str>) -> String {
         )
         .to_string(),
         Some("allow-peer-talk") => "usage: team-agent allow-peer-talk A B [--workspace WORKSPACE] [--json]".to_string(),
-        Some("status") => "usage: team-agent status [AGENT] [--workspace WORKSPACE] [--team TEAM] [--summary|--json] [--detail]\n\n输出七字段：name/provider/runtime_status/activity/health/session_name/tmux_command；人读与 --json 使用同一投影。缺少可靠定位或原生 tmux/process 采样时显示 unknown；tmux_command 可复制到对应目标。--summary/--detail 仅保留兼容性，不增加诊断字段。".to_string(),
+        Some("status") => "usage: team-agent status [AGENT] [--workspace WORKSPACE] [--team TEAM] [--summary|--json] [--detail]\n\n输出九字段：name/provider/model/effort/runtime_status/activity/health/session_name/tmux_command；人读与 --json 使用同一投影。model/effort 为已接受启动配置，未设置为 null，不猜 provider 默认值。缺少可靠定位或原生 tmux/process 采样时显示 unknown；tmux_command 可复制到对应目标。--summary/--detail 仅保留兼容性，不增加诊断字段。".to_string(),
         Some("models") => "usage: team-agent models [--provider pi|cursor_agent|codex|claude|claude_code] [QUERY|--search TEXT] [--json]\n\nLists exact provider model ids with case-insensitive multi-word search across provider, vendor, id, display name, and source aliases. Uses each provider's native catalog; Codex uses `codex debug models` and Claude uses SDK stream-json initialize.".to_string(),
         Some("leaders") => "usage: team-agent leaders [QUERY|--search TEXT] [--all|--stale] [--json] | --prune [--dry-run] [--json]\n\nLists LIVE leaders by default. Use --all to include retained STALE entries, --stale to inspect only STALE entries, QUERY or --search TEXT to match workspace/team/name fields, and --prune to remove only entries proven terminal by canonical state. --dry-run is valid only with --prune.".to_string(),
         Some("shutdown") => "usage: team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]".to_string(),
         Some("restart") => "usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json] [--detail]".to_string(),
         Some("reset-agent") => "usage: team-agent reset-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--discard-session] [--json]".to_string(),
-        Some("start-agent") => "usage: team-agent start-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--force] [--allow-fresh] [--json]\n\nAfter a successful start, use the returned `send_commands` with `team-agent send AGENT MESSAGE`.".to_string(),
+        Some(name @ ("start-agent" | "add-agent")) => command_spec(name)
+            .map(|spec| format!(
+                "{}\n\n{}\n\nAfter a successful {}, use the returned `send_commands` with `team-agent send AGENT MESSAGE`.",
+                spec.usage,
+                spec.summary,
+                if name == "start-agent" { "start" } else { "add" },
+            ))
+            .unwrap_or_else(|| format!("usage: team-agent {name} [options]")),
         Some("stop-agent") => "usage: team-agent stop-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
-        Some("add-agent") => "usage: team-agent add-agent AGENT --role-file FILE [--force] [--workspace WORKSPACE] [--team TEAM] [--json]\n\nAfter a successful add, use the returned `send_commands` with `team-agent send AGENT MESSAGE`.".to_string(),
         Some("clone-agent") => "usage: team-agent clone-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
         Some("fork-agent") => "usage: team-agent fork-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
         Some("remove-agent") => "usage: team-agent remove-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--from-spec] [--confirm] [--force] [--json]".to_string(),
@@ -1430,9 +1436,107 @@ fn restart_args(args: &[String], cwd: &Path) -> Result<RestartArgs, CliError> {
     })
 }
 
+// Keep strict role CLI parsing separate from the legacy shared parser.
+fn role_agent_args(args: &[String], add: bool) -> Result<(ParsedArgs, crate::lifecycle::role_config::RoleConfigPatch), CliError> {
+    let mut role = crate::lifecycle::role_config::RoleConfigPatch::default();
+    let mut forwarded = Vec::new();
+    let mut seen = std::collections::BTreeSet::new();
+    let mut index = 0;
+    while index < args.len() {
+        let argument = &args[index];
+        if !argument.starts_with('-') {
+            forwarded.push(argument.clone());
+            index += 1;
+            continue;
+        }
+        let (flag, inline) = argument.split_once('=').map_or((argument.as_str(), None), |(key, value)| (key, Some(value)));
+        if !seen.insert(flag.to_string()) { return Err(CliError::Usage(format!("duplicate {flag}"))); }
+        if matches!(flag, "--json" | "--allow-fresh" | "--force") {
+            if inline.is_some() || (add && flag == "--allow-fresh") {
+                return Err(CliError::Usage(format!("unsupported option: {argument}")));
+            }
+            forwarded.push(flag.to_string());
+            index += 1;
+            continue;
+        }
+        if !matches!(flag, "--provider" | "--model" | "--effort" | "--bypass" | "--prompt" | "--profile" | "--workspace" | "--team" | "--role-file")
+            || (!add && flag == "--role-file") {
+            return Err(CliError::Usage(format!("unknown option: {flag}")));
+        }
+        let value = if let Some(value) = inline { value.to_string() } else {
+            index += 1;
+            args.get(index).filter(|value| !value.starts_with("--"))
+                .ok_or_else(|| CliError::Usage(format!("missing value for {flag}")))?.clone()
+        };
+        if value.trim().is_empty() { return Err(CliError::Usage(format!("empty value for {flag}"))); }
+        match flag {
+            "--provider" => {
+                let provider = crate::provider::wire::parse_provider(&value)
+                    .ok_or_else(|| CliError::Usage(format!("unknown provider: {value}")))?;
+                role.provider = Some(crate::provider::wire::provider_wire(provider).to_string());
+            }
+            "--bypass" => role.bypass = Some(match value.as_str() {
+                "true" => true, "false" => false,
+                _ => return Err(CliError::Usage("--bypass requires true or false".into())),
+            }),
+            "--model" => role.model = Some(value),
+            "--effort" => {
+                if crate::model::enums::ProviderEffort::parse(&value).is_none() {
+                    return Err(CliError::Usage(format!("unknown effort: {value}")));
+                }
+                role.effort = Some(value);
+            }
+            "--prompt" => role.prompt = Some(value),
+            "--profile" => role.profile = Some(value),
+            _ => { forwarded.push(flag.to_string()); forwarded.push(value); }
+        }
+        index += 1;
+    }
+    let parsed = parse_args(&forwarded);
+    if add && parsed.role_file.is_none() {
+        if role.provider.is_none() { return Err(CliError::Usage("add-agent requires --provider <name>".into())); }
+        if role.bypass.is_none() { return Err(CliError::Usage("add-agent requires --bypass <true|false>".into())); }
+    }
+    if parsed.positionals.len() != 1 { return Err(CliError::Usage("expected exactly one agent id".into())); }
+    Ok((parsed, role))
+}
+
+#[cfg(test)]
+mod role_cli_tests {
+    use super::*;
+    fn strings(values: &[&str]) -> Vec<String> { values.iter().map(|value| (*value).to_string()).collect() }
+
+    #[test]
+    fn add_requires_decisions_without_a_template_but_accepts_file_input() {
+        for args in [vec!["w"], vec!["w", "--provider", "pi"], vec!["w", "--bypass", "false"]] {
+            assert!(role_agent_args(&strings(&args), true).is_err());
+        }
+        assert!(role_agent_args(&strings(&["w", "--role-file", "w.md"]), true).is_ok());
+        let (parsed, _) = role_agent_args(&strings(&["w", "--role-file", "w.md", "--force"]), true).unwrap();
+        assert!(parsed.force);
+        assert!(role_agent_args(&strings(&["w", "--role-file", "w.md", "--force=true"]), true).is_err());
+        assert!(role_agent_args(&strings(&["w", "--role-file", "w.md", "--allow-fresh"]), true).is_err());
+        let (_, patch) = role_agent_args(&strings(&["w", "--provider=pi", "--bypass=false"]), true).unwrap();
+        assert_eq!(patch.provider.as_deref(), Some("pi"));
+        assert_eq!(patch.bypass, Some(false));
+    }
+
+    #[test]
+    fn strict_role_options_reject_ambiguous_values() {
+        for args in [
+            vec!["w", "--bypass"], vec!["w", "--bypass", "yes"],
+            vec!["w", "--no-bypass"], vec!["w", "--bypass", "true", "--bypass=false"],
+            vec!["w", "--unknown", "x"], vec!["w", "extra"],
+        ] { assert!(role_agent_args(&strings(&args), false).is_err()); }
+        let (_, patch) = role_agent_args(&strings(&["w"]), false).unwrap();
+        assert_eq!(patch, crate::lifecycle::role_config::RoleConfigPatch::default());
+    }
+}
+
 fn start_agent_args(args: &[String], cwd: &Path) -> Result<StartAgentArgs, CliError> {
-    let parsed = parse_args(args);
+    let (parsed, role_config) = role_agent_args(args, false)?;
     Ok(StartAgentArgs {
+        role_config,
         agent: required_pos(&parsed, 0, "agent")?,
         workspace: workspace(&parsed, cwd),
         team: parsed.team,
@@ -1466,14 +1570,13 @@ fn reset_agent_args(args: &[String], cwd: &Path) -> Result<ResetAgentArgs, CliEr
 }
 
 fn add_agent_args(args: &[String], cwd: &Path) -> Result<AddAgentArgs, CliError> {
-    let parsed = parse_args(args);
+    let (parsed, role_config) = role_agent_args(args, true)?;
     Ok(AddAgentArgs {
+        role_config,
         agent: required_pos(&parsed, 0, "agent")?,
         workspace: workspace(&parsed, cwd),
         team: parsed.team,
-        role_file: parsed
-            .role_file
-            .ok_or_else(|| CliError::Usage("missing --role-file".to_string()))?,
+        role_file: parsed.role_file.unwrap_or_default(),
         force: parsed.force,
         json: parsed.json,
     })
@@ -2076,11 +2179,8 @@ mod tests {
             (
                 "start-agent",
                 &[
-                    "--workspace",
-                    "--team",
-                    "--force",
-                    "--allow-fresh",
-                    "--json",
+                    "--model", "--effort", "--bypass", "--prompt", "--profile", "--provider",
+                    "--workspace", "--team", "--allow-fresh", "--json",
                 ][..],
             ),
             (
@@ -2095,10 +2195,8 @@ mod tests {
             (
                 "add-agent",
                 &[
-                    "--role-file",
-                    "--workspace",
-                    "--team",
-                    "--json",
+                    "--role-file", "--provider", "--bypass", "--model", "--effort", "--prompt", "--profile",
+                    "--force", "--workspace", "--team", "--json",
                 ][..],
             ),
             (
@@ -2185,11 +2283,30 @@ mod tests {
         );
     }
 
+    #[test]
+    fn worker_lifecycle_help_uses_authoritative_spec_usage_and_summary() {
+        for name in ["start-agent", "add-agent"] {
+            let spec = command_spec(name).expect("registered worker lifecycle command");
+            let help = command_help(Some(name));
+            assert_eq!(help.lines().next(), Some(spec.usage));
+            assert!(help.contains(spec.summary));
+            for flag in ["--model SLUG", "--effort LEVEL", "--bypass true|false", "--prompt TEXT", "--profile NAME", "--provider NAME"] {
+                assert!(help.contains(flag), "{name} help missing {flag}: {help}");
+            }
+            assert!(help.contains("team-agent send AGENT MESSAGE"));
+        }
+        assert!(!command_help(Some("start-agent")).contains("--force"));
+        let add = command_help(Some("add-agent"));
+        assert!(add.contains("[--role-file FILE]"));
+        assert!(add.contains("provider/bypass required from CLI or role file"));
+        assert!(add.contains("conflicting values rejected"));
+    }
+
     #[test]
     fn status_help_describes_brief_projection_and_unknown_boundary() {
         let help = command_help(Some("status"));
         for marker in [
-            "name/provider/runtime_status/activity/health/session_name/tmux_command",
+            "name/provider/model/effort/runtime_status/activity/health/session_name/tmux_command",
             "人读与 --json 使用同一投影",
             "显示 unknown",
             "tmux_command",

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

@@ -49,7 +49,7 @@ use crate::messaging::{self, MessageTarget, SendOptions, TrustedSender};
 use crate::model::ids::{TaskId, TeamKey};
 
 pub(crate) const COMMS_BOUNDARY_TEXT: &str = "validates live pane binding consistency and zero-token comms contracts. Does NOT perform live runtime message round-trip. (zero token, zero pollution)";
-pub(crate) const QUICK_START_REMINDER: &str = "Reminder: Do not inspect raw worker pane output during normal operation. Use team-agent status / inbox / collect instead. Wait for report_result.";
+pub(crate) const QUICK_START_REMINDER: &str = "Reminder: Do not inspect raw worker pane output during normal operation. Use team-agent status / inbox instead. Wait for report_result.";
 pub(crate) const SEND_REMINDER: &str = "Message delivered. Wait for the worker to report_result. Do not poll the worker terminal with capture-pane.";
 pub(crate) const STATUS_REMINDER: &str = "Results are finalized automatically; use --watch-result or team-agent inbox AGENT -n 3 for transport fallback. Do not capture-pane worker terminals.";
 
@@ -707,19 +707,7 @@ pub mod lifecycle_port {
     }
 
     fn state_generation(state: &Value) -> Option<&str> {
-        state
-            .get("generation")
-            .and_then(Value::as_str)
-            .or_else(|| {
-                state
-                    .get("agents")
-                    .and_then(Value::as_object)
-                    .and_then(|agents| {
-                        agents.values().find_map(|agent| {
-                            agent.get("spawned_at").and_then(Value::as_str)
-                        })
-                    })
-            })
+        crate::state::projection::session_generation(state)
     }
 
     fn state_for_session<'a>(state: &'a Value, session: &str) -> Option<&'a Value> {
@@ -777,12 +765,23 @@ pub mod lifecycle_port {
         if owner.generation != expected_generation {
             return SessionOwnership::Foreign;
         }
-        if session_targets.iter().any(|target| {
-            target.current_path.as_ref().map_or(true, |path| {
-                !path_is_under(path.as_path(), workspace)
-            })
-        }) {
-            return SessionOwnership::Unknown;
+        for target in session_targets {
+            if target.current_path.as_ref().is_some_and(|path| {
+                path_is_under(path.as_path(), workspace)
+            }) {
+                continue;
+            }
+            // An exited keepalive has no cwd or live process. Exempt only the
+            // internal anchor, with native positive dead-pane proof, AFTER the
+            // session workspace/team/generation ownership gates above.
+            let dead_anchor = target.current_path.as_ref().is_none_or(|path| {
+                path.as_os_str().is_empty()
+            }) && target.window_name.as_ref().is_some_and(|window| {
+                window.as_str() == crate::tmux_backend::KEEPALIVE_WINDOW_NAME
+            }) && matches!(transport.pane_is_dead(&target.pane_id), Ok(Some(true)));
+            if !dead_anchor {
+                return SessionOwnership::Unknown;
+            }
         }
         SessionOwnership::Owned
     }
@@ -793,7 +792,135 @@ pub mod lifecycle_port {
 
         use super::*;
         use crate::transport::test_support::OfflineTransport;
-        use crate::transport::{PaneId, PaneInfo, SessionName};
+        use crate::transport::{PaneId, PaneInfo, SessionName, Transport, WindowName};
+
+        fn ownership_pane(session: &SessionName, pane: &str, window: &str, cwd: Option<PathBuf>) -> PaneInfo {
+            PaneInfo {
+                pane_id: PaneId::new(pane),
+                session: session.clone(),
+                window_index: None,
+                window_name: Some(WindowName::new(window)),
+                pane_index: None,
+                tty: None,
+                current_command: None,
+                current_path: cwd,
+                active: false,
+                pane_pid: None,
+                leader_env: BTreeMap::new(),
+            }
+        }
+
+        #[test]
+        fn dead_anchor_ownership_requires_native_dead_proof_and_all_owner_markers() {
+            let workspace = std::env::temp_dir().canonicalize().unwrap();
+            let session = SessionName::new("owned");
+            let state = json!({"team_key": "owned", "generation": "g"});
+            for (window, cwd, dead, team, generation, expected) in [
+                (crate::tmux_backend::KEEPALIVE_WINDOW_NAME, None, Some(true), "owned", "g", SessionOwnership::Owned),
+                (crate::tmux_backend::KEEPALIVE_WINDOW_NAME, None, Some(false), "owned", "g", SessionOwnership::Unknown),
+                (crate::tmux_backend::KEEPALIVE_WINDOW_NAME, None, None, "owned", "g", SessionOwnership::Unknown),
+                ("foreign", None, Some(true), "owned", "g", SessionOwnership::Unknown),
+                (crate::tmux_backend::KEEPALIVE_WINDOW_NAME, Some(PathBuf::from("/foreign-workspace")), Some(true), "owned", "g", SessionOwnership::Unknown),
+                (crate::tmux_backend::KEEPALIVE_WINDOW_NAME, None, Some(true), "other-team", "g", SessionOwnership::Foreign),
+                (crate::tmux_backend::KEEPALIVE_WINDOW_NAME, None, Some(true), "owned", "other-generation", SessionOwnership::Foreign),
+            ] {
+                let mut transport = OfflineTransport::new().with_session_owner(&workspace, team, generation);
+                if let Some(dead) = dead { transport = transport.with_pane_dead("%1", dead); }
+                let targets = vec![
+                    ownership_pane(&session, "%2", "assistant", Some(workspace.clone())),
+                    ownership_pane(&session, "%1", window, cwd),
+                ];
+                assert_eq!(session_ownership(&workspace, &state, &transport, &session, &targets), expected);
+                if expected == SessionOwnership::Foreign {
+                    assert!(!transport.calls().contains(&"pane_is_dead"), "owner gates must precede exemption");
+                }
+                assert!(!transport.calls().contains(&"kill_session"));
+            }
+        }
+
+        #[test]
+        #[cfg(unix)]
+        #[ignore = "isolated native tmux: explicit Grok execution, no provider subscription"]
+        fn dead_anchor_scoped_shutdown_reaps_worker_wrapper_and_spares_other_team() {
+            let root = std::env::temp_dir().join(format!(
+                "ta-r2-{}-{}", std::process::id(), chrono::Utc::now().timestamp_nanos_opt().unwrap(),
+            ));
+            std::fs::create_dir(&root).unwrap();
+            let root = root.canonicalize().unwrap();
+            let workspace = root.join("owned");
+            let foreign_workspace = root.join("foreign");
+            std::fs::create_dir(&workspace).unwrap();
+            std::fs::create_dir(&foreign_workspace).unwrap();
+            let endpoint = root.join("sock");
+            let transport = crate::tmux_backend::TmuxBackend::with_runner_for_tmux_endpoint(
+                Box::new(crate::tmux_backend::RealCommandRunner), endpoint.to_str().unwrap(),
+            );
+            let session = SessionName::new("round2-owned");
+            let foreign = SessionName::new("round2-foreign");
+            struct Cleanup<'a>(&'a crate::tmux_backend::TmuxBackend, [&'a SessionName; 2], &'a Path);
+            impl Drop for Cleanup<'_> {
+                fn drop(&mut self) {
+                    for session in self.1 { let _ = self.0.kill_session(session); }
+                    let _ = std::fs::remove_dir_all(self.2);
+                }
+            }
+            let _cleanup = Cleanup(&transport, [&session, &foreign], &root);
+            let env = BTreeMap::new();
+            let argv = vec!["sh".to_string(), "-c".to_string(), "exit 0".to_string()];
+            let first = transport.spawn_first_with_worker_shell_wrapper(
+                &session, &WindowName::new("assistant"), &argv, &workspace, &env, &[], "pi",
+            ).unwrap();
+            transport.set_session_owner_with_generation(&session, &workspace, "round2-owned", "g").unwrap();
+            transport.preserve_session_before_stop(&session, &[crate::transport::Target::Pane(first.pane_id.clone())]).unwrap();
+            transport.kill_pane(&first.pane_id).unwrap();
+            let worker = transport.spawn_into_with_worker_shell_wrapper(
+                &session, &WindowName::new("assistant"), &argv, &workspace, &env, &[], "pi",
+            ).unwrap();
+            let foreign_worker = transport.spawn_first(
+                &foreign, &WindowName::new("other"), &["sleep".to_string(), "60".to_string()],
+                &foreign_workspace, &env,
+            ).unwrap();
+            transport.set_session_owner_with_generation(&foreign, &foreign_workspace, "round2-foreign", "foreign-g").unwrap();
+            let deadline = std::time::Instant::now() + std::time::Duration::from_secs(3);
+            let marker = format!("{} 0", crate::tmux_backend::worker_provider_exit_marker("pi"));
+            loop {
+                // This controlled fixture prints nothing: the worker wrapper
+                // and its inert tail supply these two lines. provider_exit_status
+                // is a leader-only receipt, not a worker-wrapper observation.
+                let captured = transport.capture(
+                    &crate::transport::Target::Pane(worker.pane_id.clone()),
+                    crate::transport::CaptureRange::Full,
+                ).unwrap();
+                if captured.text.contains(&marker)
+                    && captured.text.contains("Provider exited; this pane no longer accepts input.")
+                {
+                    break;
+                }
+                assert!(std::time::Instant::now() < deadline, "worker must reach its inert exit wrapper: {}", captured.text);
+                std::thread::sleep(std::time::Duration::from_millis(20));
+            }
+            assert_eq!(transport.pane_is_dead(&worker.pane_id).unwrap(), Some(false));
+            let worker_pid = worker.child_pid.unwrap();
+            assert!(crate::platform::process::pid_is_alive(worker_pid));
+            let state = json!({
+                "team_key": "round2-owned", "active_team_key": "round2-owned",
+                "session_name": session.as_str(), "tmux_socket": endpoint.to_str().unwrap(),
+                "generation": "g", "is_external_leader": true,
+                "agents": {"assistant": {
+                    "status": "running", "provider": "pi", "model": "openai-codex/gpt-6-luna", "effort": "max",
+                    "window": "assistant", "pane_id": worker.pane_id.as_str(), "pane_pid": worker_pid,
+                    "spawned_at": "new-worker-birth-after-start"
+                }}
+            });
+            crate::state::persist::save_runtime_state(&workspace, &state).unwrap();
+            let result = shutdown_with_transport_and_state(&workspace, true, None, &transport, Some(state)).unwrap();
+            assert_eq!(result["ok"], true, "{result}");
+            assert_eq!(result["residuals"], json!({"sessions": [], "processes": [], "owned_files": []}), "{result}");
+            assert!(!transport.has_session(&session).unwrap());
+            assert!(!crate::platform::process::pid_is_alive(worker_pid));
+            assert!(transport.has_session(&foreign).unwrap());
+            assert!(crate::platform::process::pid_is_alive(foreign_worker.child_pid.unwrap()));
+        }
 
         #[test]
         fn leader_process_protection_does_not_alias_panes_across_endpoints() {
@@ -2750,15 +2877,12 @@ pub mod lifecycle_port {
         force: bool,
         allow_fresh: bool,
         team: Option<&str>,
+        role_config: &crate::lifecycle::role_config::RoleConfigPatch,
     ) -> Result<Value, CliError> {
+        let _ = force; // Never grants authority to stop an already-running seat.
         let agent_id = crate::model::ids::AgentId::new(agent);
-        match crate::lifecycle::start_agent(
-            workspace,
-            &agent_id,
-            force,
-            true,
-            allow_fresh,
-            team,
+        match crate::lifecycle::role_config::start_agent_from_role(
+            workspace, &agent_id, role_config, allow_fresh, team,
         ) {
             Ok(crate::lifecycle::StartAgentOutcome::Running {
                 env,
@@ -2876,15 +3000,12 @@ pub mod lifecycle_port {
         role_file: &str,
         team: Option<&str>,
         force: bool,
+        role_config: &crate::lifecycle::role_config::RoleConfigPatch,
     ) -> Result<Value, CliError> {
         let agent_id = crate::model::ids::AgentId::new(agent);
-        match crate::lifecycle::add_agent_force(
-            workspace,
-            &agent_id,
-            Path::new(role_file),
-            true,
-            team,
-            force,
+        let source = (!role_file.is_empty()).then(|| Path::new(role_file));
+        match crate::lifecycle::role_config::add_agent_from_role(
+            workspace, &agent_id, source, role_config, force, team,
         ) {
             Ok(report) => Ok(agent_action_value(
                 agent,

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

@@ -152,8 +152,8 @@ pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
     CommandSpec { name: "wait", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Wait), summary: "block until a task result is stored", usage: "usage: team-agent wait --task TASK [--workspace WORKSPACE] [--json]", default_help: false, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
     CommandSpec { name: "restart", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Restart), summary: "restart the selected team", usage: "usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
     CommandSpec { name: "shutdown", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Shutdown), summary: "stop the selected team", usage: "usage: team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
-    CommandSpec { name: "add-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::AddAgent), summary: "add or force-recreate a worker", usage: "usage: team-agent add-agent AGENT --role-file FILE [--force] [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
-    CommandSpec { name: "start-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::StartAgent), summary: "start an existing worker", usage: "usage: team-agent start-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--force] [--allow-fresh] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
+    CommandSpec { name: "add-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::AddAgent), summary: "create and start a new worker", usage: "usage: team-agent add-agent AGENT [--role-file FILE] [--provider NAME] [--bypass true|false] [--model SLUG] [--effort LEVEL] [--prompt TEXT] [--profile NAME] [--force] [--workspace WORKSPACE] [--team TEAM] [--json] (provider/bypass required from CLI or role file; conflicting values rejected; force only recreates a confirmed dead registered pane)", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
+    CommandSpec { name: "start-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::StartAgent), summary: "update and start a stopped worker (stop first if running)", usage: "usage: team-agent start-agent AGENT [--model SLUG] [--effort LEVEL] [--bypass true|false] [--prompt TEXT] [--profile NAME] [--provider NAME] [--workspace WORKSPACE] [--team TEAM] [--allow-fresh] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
     CommandSpec { name: "stop-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::StopAgent), summary: "stop a worker", usage: "usage: team-agent stop-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
     CommandSpec { name: "reset-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::ResetAgent), summary: "reset a worker session", usage: "usage: team-agent reset-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--discard-session] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
     CommandSpec { name: "claim-leader", tier: CommandTier::Guided, category: CommandCategory::GuidedRecovery, kind: CommandKind::Dispatch(DispatchKind::ClaimLeader), summary: "bind this pane when doctor reports rebind_required", usage: "usage: team-agent claim-leader [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },