@team-agent/installer 0.5.75 → 0.5.78

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

@@ -58,9 +58,9 @@ pub mod attach_app_server_leader;
 pub mod diagnose;
 pub mod emit;
 pub mod helpers;
+pub mod models;
 pub mod leader;
 pub mod leaders;
-pub mod models;
 pub mod named_address;
 pub mod profile;
 pub mod send;
@@ -74,7 +74,6 @@ pub use diagnose::*;
 pub use emit::*;
 pub use leader::*;
 pub use leaders::*;
-pub use models::*;
 pub use named_address::*;
 pub use profile::*;
 pub use send::*;
@@ -104,6 +103,10 @@ pub(crate) use helpers::*;
 #[cfg(test)]
 mod tests;
 
+#[cfg(test)]
+#[path = "../../tests/support/hermetic.rs"]
+mod hermetic_test_support;
+
 // =============================================================================
 // CROSS-LANE PLACEHOLDERS(sibling 14a-mcp / status / diagnose / step13-lifecycle
 // 尚未落地;leader 集成时收口到真模块。本层只声明 CLI 调用面所需的最小占位,
@@ -3075,15 +3078,6 @@ pub mod lifecycle_port {
     }
 
     fn error_value(error: crate::lifecycle::LifecycleError) -> Value {
-        if let crate::lifecycle::LifecycleError::PiModelPreflight {
-            requested,
-            candidates,
-            action,
-            not_ready,
-        } = error
-        {
-            return json!({"ok": false, "error": "pi model preflight failed", "pi": {"requested_model": requested, "candidates": candidates, "not_ready": not_ready, "action": action.clone(), "next_action": action}});
-        }
         let message = error.to_string();
         let mut payload = json!({"ok": false, "error": message});
         if let Some(next_action) = error_next_action(&message) {
@@ -3096,9 +3090,24 @@ pub mod lifecycle_port {
     /// 匹配 [`LifecycleError`] 的人读消息子串(`agent {id} not found` /
     /// `agent id already exists` / `unknown worker agent id`),给出下一步命令。
     fn error_next_action(message: &str) -> Option<&'static str> {
-        // start-agent 撞"agent ... not found":start-agent 语义=启动 state 已有 agent;
-        // 想新增角色应走 add-agent。
-        if message.contains("not found") && message.contains("agent") {
+        // Missing spec/runtime is not an agent-id miss. Workspace paths often
+        // contain "team-agent", so "not found"+"agent" must not win here.
+        if message.contains("active team spec not found")
+            || message.contains("missing spec for restart")
+        {
+            return Some(
+                "no team spec or runtime was found in this workspace. \
+                 Run `team-agent quick-start <workspace>` for first launch, \
+                 or restart from a workspace that already contains `.team`.",
+            );
+        }
+        // start-agent 撞"agent {id} not found":start-agent 语义=启动 state 已有 agent;
+        // 想新增角色应走 add-agent。只在 RequirementUnmet detail 以 `agent ` 开头时匹配，
+        // 避免 profile 文案中的 `team-agent profile ... not found` 误命中。
+        let agent_not_found = message
+            .strip_prefix("agent start requirement unmet: ")
+            .is_some_and(|detail| detail.starts_with("agent ") && detail.contains(" not found"));
+        if agent_not_found {
             return Some(
                 "start-agent only starts an agent that already exists in state. \
                  To add a NEW role at runtime use: team-agent add-agent <id> --role-file <path>",
@@ -3260,6 +3269,90 @@ pub mod lifecycle_port {
         }
     }
 
+    fn public_leader_bind_failure(
+        stage: Option<&str>,
+        reason: Option<&str>,
+        _workers_spawned: bool,
+    ) -> (&'static str, String, Option<String>) {
+        match reason {
+            Some("invalid_caller_tuple") => (
+                "leader_bind_refused",
+                "invalid_caller_tuple".to_string(),
+                Some(
+                    "fix conflicting CALLER_* identity; do not run claim-leader".to_string(),
+                ),
+            ),
+            Some("provider_unresolved") => (
+                "leader_bind_refused",
+                "provider_unresolved".to_string(),
+                Some(
+                    "set TEAM_AGENT_LEADER_PROVIDER or run from a provider pane; do not run claim-leader"
+                        .to_string(),
+                ),
+            ),
+            Some("caller_pane_missing") => (
+                "leader_binding_incomplete",
+                "caller_pane_missing".to_string(),
+                Some("run from the intended leader tmux pane; do not run claim-leader".to_string()),
+            ),
+            Some("registry_readback_unavailable")
+            | Some("receiver_scope_unavailable")
+            | Some("receiver_live_channel_unavailable")
+            | Some("registry_identity_mismatch") => (
+                "leader_binding_unknown",
+                format!("{}:{}", stage.unwrap_or("bind"), reason.unwrap_or("unknown")),
+                Some(
+                    "inspect the selected-team registry file and live leader channel; do not claim-leader"
+                        .to_string(),
+                ),
+            ),
+            Some("no_attached_owner") => (
+                "leader_receiver_unbound",
+                "no_attached_owner".to_string(),
+                Some("team-agent claim-leader --confirm --json".to_string()),
+            ),
+            Some(reason) => (
+                "leader_binding_unknown",
+                format!("{}:{reason}", stage.unwrap_or("bind")),
+                Some(
+                    "inspect the selected-team registry file and live leader channel; do not claim-leader"
+                        .to_string(),
+                ),
+            ),
+            None => (
+                "leader_binding_unknown",
+                "unclassified_bind_failure".to_string(),
+                Some(
+                    "inspect the selected-team registry file and live leader channel; do not claim-leader"
+                        .to_string(),
+                ),
+            ),
+        }
+    }
+
+    fn dirty_topology_next_actions(reason: &str, issue_ids: &[String], team: &str) -> Vec<String> {
+        if reason == "worker_session_is_leader_session"
+            || issue_ids
+                .iter()
+                .any(|id| id == "worker_session_is_leader_session")
+        {
+            return vec![
+                "repair state.session_name to the worker session; it currently names the leader launcher session".to_string(),
+                format!("team-agent diagnose --team {team} --json"),
+            ];
+        }
+        let mut actions = vec![format!("team-agent diagnose --team {team} --json")];
+        if issue_ids
+            .iter()
+            .any(|id| id.contains("socket") || id.contains("endpoint"))
+        {
+            actions.push(
+                "repair tmux endpoint/socket split from the intended leader socket".to_string(),
+            );
+        }
+        actions
+    }
+
     fn quick_start_value(report: crate::lifecycle::QuickStartReport) -> Value {
         match report {
             crate::lifecycle::QuickStartReport::Ready {
@@ -3269,6 +3362,7 @@ pub mod lifecycle_port {
                 attach_commands,
                 display_backend,
                 worker_readiness,
+                team,
             } => {
                 // BUG-7: never emit bare "ready" while worker tool-load is unverified.
                 // The summary string + a structured `worker_readiness` block tell the
@@ -3337,7 +3431,7 @@ pub mod lifecycle_port {
                         } else if launch.leader_receiver_attached {
                             (
                                 format!(
-                                    "quick-start launched (worker tool load unverified): {}",
+                                    "team started; leader bound; send a task next (worker tool load unverified): {}",
                                     session_name.as_str()
                                 ),
                                 all_spawned && all_attached_receiver && all_resumable_have_session,
@@ -3355,33 +3449,43 @@ pub mod lifecycle_port {
                                     "session_capture_incomplete": !all_resumable_have_session,
                                     "incomplete_session_capture_agents": incomplete_session_capture_agents.clone(),
                                     "pending_session_agent_ids": incomplete_session_capture_agents,
-                                    "reason": "worker MCP tool set load not yet confirmed; run `team-agent doctor` or wait for first worker turn",
+                                    "reason": "team started; leader bound; send a task next (worker tool load unverified)",
                                 }),
                             )
                         } else {
+                            let (state, reason, next_action) = public_leader_bind_failure(
+                                launch.leader_bind_stage.as_deref(),
+                                launch.leader_bind_reason.as_deref(),
+                                all_spawned,
+                            );
+                            let mut readiness = json!({
+                                "all_spawned": all_spawned,
+                                "all_workers_spawned": all_workers_spawned,
+                                "all_attached_receiver": all_attached_receiver,
+                                "attached_receiver": attached_receiver,
+                                "leader_receiver_attached": leader_receiver_attached,
+                                "all_resumable_have_session": all_resumable_have_session,
+                                "all_resumable_agents_have_sessions": all_resumable_agents_have_sessions,
+                                "ready": false,
+                                "state": state,
+                                "session_capture_complete": all_resumable_have_session,
+                                "session_capture_incomplete": !all_resumable_have_session,
+                                "incomplete_session_capture_agents": incomplete_session_capture_agents.clone(),
+                                "pending_session_agent_ids": incomplete_session_capture_agents,
+                                "reason": reason,
+                            });
+                            if let Some(next_action) = next_action {
+                                if let Some(object) = readiness.as_object_mut() {
+                                    object.insert("next_action".to_string(), json!(next_action));
+                                }
+                            }
                             (
                                 format!(
-                                    "quick-start degraded: {}; leader receiver unbound",
+                                    "quick-start degraded: {}; {reason}",
                                     session_name.as_str()
                                 ),
                                 false,
-                                json!({
-                                    "all_spawned": all_spawned,
-                                    "all_workers_spawned": all_workers_spawned,
-                                    "all_attached_receiver": all_attached_receiver,
-                                    "attached_receiver": attached_receiver,
-                                    "leader_receiver_attached": leader_receiver_attached,
-                                    "all_resumable_have_session": all_resumable_have_session,
-                                    "all_resumable_agents_have_sessions": all_resumable_agents_have_sessions,
-                                    "ready": all_spawned && all_attached_receiver && all_resumable_have_session,
-                                    "state": "leader_receiver_unbound",
-                                    "session_capture_complete": all_resumable_have_session,
-                                    "session_capture_incomplete": !all_resumable_have_session,
-                                    "incomplete_session_capture_agents": incomplete_session_capture_agents.clone(),
-                                    "pending_session_agent_ids": incomplete_session_capture_agents,
-                                    "reason": "launched team has no attached leader receiver",
-                                    "next_action": "claim-leader",
-                                }),
+                                readiness,
                             )
                         }
                     }
@@ -3393,6 +3497,7 @@ pub mod lifecycle_port {
                     "reason": readiness_json.get("reason").cloned().unwrap_or(Value::Null),
                     "ready": readiness_json.get("ready").cloned().unwrap_or(Value::Bool(false)),
                     "session_name": session_name.as_str(),
+                    "team": team,
                     "agent_ids": launch.started.iter().map(|agent| agent.agent_id.as_str()).collect::<Vec<_>>(),
                     "dry_run": launch.dry_run,
                     "display_backend": display_backend,
@@ -3409,12 +3514,14 @@ pub mod lifecycle_port {
                 state_path,
                 next_actions,
                 attach_commands,
+                agent_ids,
             } => json!({
                 "ok": false,
                 "status": "existing_runtime",
                 "reason": "team already has runtime state; use restart",
                 "summary": "existing runtime",
                 "team": team,
+                "agent_ids": agent_ids,
                 "session_name": session_name.map(|s| s.as_str().to_string()),
                 "state_path": state_path.map(|p| p.to_string_lossy().to_string()),
                 "next_actions": next_actions,
@@ -3454,21 +3561,21 @@ pub mod lifecycle_port {
                 "all_resumable_have_session": true,
                 "all_resumable_agents_have_sessions": true,
                 "ready": false,
-                "state": "leader_receiver_unbound",
+                "state": "leader_bind_refused",
                 "session_capture_complete": true,
                 "session_capture_incomplete": false,
                 "incomplete_session_capture_agents": [],
                 "pending_session_agent_ids": [],
-                "reason": "launched team has no attached leader receiver",
-                "next_action": "claim-leader"
+                "reason": "provider_unresolved",
+                "next_action": "set TEAM_AGENT_LEADER_PROVIDER or run from a provider pane; do not run claim-leader"
             });
             let detail = json!({
                 "ok": false,
-                "status": "leader_receiver_unbound",
-                "reason": "launched team has no attached leader receiver",
+                "status": "leader_bind_refused",
+                "reason": "provider_unresolved",
                 "ready": false,
                 "session_name": "team-fresh",
-                "next_actions": ["claim-leader"],
+                "next_actions": ["set TEAM_AGENT_LEADER_PROVIDER or run from a provider pane; do not run claim-leader"],
                 "attach_commands": ["tmux attach"],
                 "send_commands": ["team-agent send worker hi"],
                 "agent_ids": ["worker"],
@@ -3478,12 +3585,15 @@ pub mod lifecycle_port {
             });
             let mut default = detail.clone();
             compact_quick_start_value(&mut default);
-            assert_eq!(default["status"], json!("leader_receiver_unbound"));
+            assert_eq!(default["status"], json!("leader_bind_refused"));
             assert_eq!(
                 default["reason"],
-                json!("launched team has no attached leader receiver")
+                json!("provider_unresolved")
+            );
+            assert_eq!(
+                default["next_actions"],
+                json!(["set TEAM_AGENT_LEADER_PROVIDER or run from a provider pane; do not run claim-leader"])
             );
-            assert_eq!(default["next_actions"], json!(["claim-leader"]));
             assert_eq!(default["attach_commands"], json!(["tmux attach"]));
             assert_eq!(
                 default["send_commands"],
@@ -3492,8 +3602,11 @@ pub mod lifecycle_port {
             assert!(default.get("agent_ids").is_none());
             assert!(default.get("dry_run").is_none());
             assert_eq!(default["readiness"]["all_workers_spawned"], json!(true));
-            assert_eq!(default["readiness"]["state"], json!("leader_receiver_unbound"));
-            assert_eq!(default["readiness"]["next_action"], json!("claim-leader"));
+            assert_eq!(default["readiness"]["state"], json!("leader_bind_refused"));
+            assert_eq!(
+                default["readiness"]["next_action"],
+                json!("set TEAM_AGENT_LEADER_PROVIDER or run from a provider pane; do not run claim-leader")
+            );
             assert!(default["readiness"].get("all_spawned").is_none());
             assert!(default["readiness"].get("all_attached_receiver").is_none());
             assert!(default["readiness"].get("leader_receiver_attached").is_none());
@@ -3507,6 +3620,152 @@ pub mod lifecycle_port {
         }
 
         #[test]
+        fn pending_tool_load_success_output_explains_bound_send_without_doctor() {
+            let value = quick_start_value(crate::lifecycle::QuickStartReport::Ready {
+                session_name: crate::transport::SessionName::new("team-demo"),
+                launch: Box::new(crate::lifecycle::LaunchReport {
+                    session_name: crate::transport::SessionName::new("team-demo"),
+                    started: vec![crate::lifecycle::StartedAgent {
+                        agent_id: crate::model::ids::AgentId::new("worker"),
+                        start_mode: crate::lifecycle::StartMode::Fresh,
+                        target: "worker".to_string(),
+                        spawned_at: "2026-09-10T00:00:00Z".to_string(),
+                        session_id: None,
+                        rollout_path: None,
+                        pending_session_id: None,
+                        claude_config_dir: None,
+                        provider_projects_root: None,
+                        managed_mcp_config: false,
+                        layout_window: None,
+                        layout_index: None,
+                        pane_index: None,
+                        display: crate::lifecycle::WorkerDisplay::Blocked {
+                            reason: crate::lifecycle::AdaptiveBlockReason::AggregatorRebuildFailed,
+                        },
+                    }],
+                    dry_run: false,
+                    tmux_endpoint: None,
+                    routes: Vec::new(),
+                    permissions: Vec::new(),
+                    leader_receiver_attached: true,
+                    leader_bind_stage: None,
+                    leader_bind_reason: None,
+                    session_capture_incomplete_agents: Vec::new(),
+                }),
+                next_actions: Vec::new(),
+                attach_commands: Vec::new(),
+                display_backend: "none".to_string(),
+                worker_readiness: crate::lifecycle::QuickStartReadiness::PendingToolLoad,
+                team: "team-demo".to_string(),
+            });
+            assert_eq!(
+                value.get("summary").and_then(Value::as_str),
+                Some("team started; leader bound; send a task next (worker tool load unverified): team-demo")
+            );
+            assert_eq!(
+                value.get("reason").and_then(Value::as_str),
+                Some("team started; leader bound; send a task next (worker tool load unverified)")
+            );
+            assert_eq!(
+                value.get("status").and_then(Value::as_str),
+                Some("pending_tool_load")
+            );
+            assert_eq!(value.get("ready").and_then(Value::as_bool), Some(true));
+            assert!(value
+                .get("reason")
+                .and_then(Value::as_str)
+                .is_some_and(|reason| !reason.contains("doctor")));
+        }
+
+        #[test]
+        fn restarted_json_ok_follows_bind_status() {
+            let coordinator = crate::lifecycle::CoordinatorStartSummary {
+                ok: true,
+                status: "started".to_string(),
+                pid: None,
+                binary_path: None,
+                binary_version: None,
+                rotation_reason: None,
+                binary_identity_relation: "same".to_string(),
+            };
+            let value = restart_value(
+                crate::lifecycle::RestartReport::Restarted {
+                    session_name: crate::transport::SessionName::new("s"),
+                    agents: Vec::new(),
+                    coordinator_started: true,
+                    coordinator: coordinator.clone(),
+                    next_actions: Vec::new(),
+                    attach_commands: Vec::new(),
+                    attach_window_failures: None,
+                    leader_bind_ok: true,
+                    leader_bind_reason: None,
+                },
+                None,
+            );
+            assert_eq!(value.get("ok").and_then(Value::as_bool), Some(true));
+            let incomplete = restart_value(
+                crate::lifecycle::RestartReport::Restarted {
+                    session_name: crate::transport::SessionName::new("s"),
+                    agents: Vec::new(),
+                    coordinator_started: true,
+                    coordinator,
+                    next_actions: Vec::new(),
+                    attach_commands: Vec::new(),
+                    attach_window_failures: None,
+                    leader_bind_ok: false,
+                    leader_bind_reason: Some("leader_registry_index_missing".to_string()),
+                },
+                None,
+            );
+            assert_eq!(incomplete.get("ok").and_then(Value::as_bool), Some(false));
+            assert_eq!(
+                incomplete.get("reason").and_then(Value::as_str),
+                Some("leader_registry_index_missing")
+            );
+        }
+
+        #[test]
+        fn partial_json_exposes_leader_bind_ok() {
+            let value = restart_value(
+                crate::lifecycle::RestartReport::Partial {
+                    session_name: crate::transport::SessionName::new("s"),
+                    agents: Vec::new(),
+                    failed_agents: Vec::new(),
+                    coordinator_started: true,
+                    coordinator: crate::lifecycle::CoordinatorStartSummary {
+                        ok: true,
+                        status: "started".to_string(),
+                        pid: None,
+                        binary_path: None,
+                        binary_version: None,
+                        rotation_reason: None,
+                        binary_identity_relation: "same".to_string(),
+                    },
+                    next_actions: Vec::new(),
+                    attach_commands: Vec::new(),
+                    attach_window_failures: Some(json!({"registry_maintain_failed": true})),
+                    leader_bind_ok: false,
+                    leader_bind_reason: Some("leader_registry_maintain_failed".to_string()),
+                },
+                None,
+            );
+            assert_eq!(value.get("ok").and_then(Value::as_bool), Some(false));
+            assert_eq!(
+                value.get("leader_bind_ok").and_then(Value::as_bool),
+                Some(false)
+            );
+            assert_eq!(
+                value.get("leader_bind_reason").and_then(Value::as_str),
+                Some("leader_registry_maintain_failed")
+            );
+            assert_eq!(
+                value
+                    .pointer("/attach_window_failures/registry_maintain_failed")
+                    .and_then(Value::as_bool),
+                Some(true)
+            );
+        }
+
         fn restart_default_receipt_is_compact_but_detail_preserves_coordinator() {
             let detail = json!({
                 "ok": false,
@@ -3526,6 +3785,128 @@ pub mod lifecycle_port {
             assert!(detail.get("coordinator").is_some());
         }
 
+        #[test]
+        #[serial_test::serial(env)]
+        fn existing_runtime_producer_scopes_send_team() {
+            let _hermetic = super::super::hermetic_test_support::HermeticTestEnv::enter(
+                "quick-start-value-existing-runtime",
+            );
+            let root = std::env::temp_dir().join(format!(
+                "ta-n5-prod-{}-{}",
+                std::process::id(),
+                std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)
+                    .unwrap()
+                    .as_nanos()
+            ));
+            let team_dir = root.join("teamdir");
+            std::fs::create_dir_all(team_dir.join("agents")).unwrap();
+            std::fs::write(
+                team_dir.join("TEAM.md"),
+                "---\nname: quickteam\nobjective: Quick start.\nprovider: codex\n---\n\nQuick-start team.\n",
+            )
+            .unwrap();
+            std::fs::write(
+                team_dir.join("agents").join("implementer.md"),
+                "---\nname: implementer\nrole: Implementation Engineer\nprovider: codex\nmodel: gpt-5.5\nauth_mode: subscription\ndangerously_skip_permissions: false\ntools:\n  - mcp_team\n---\n\nImplement bounded tasks.\n",
+            )
+            .unwrap();
+            let transport = crate::transport::test_support::OfflineTransport::new();
+            let first = crate::lifecycle::quick_start_with_transport(
+                &team_dir,
+                Some("from-name"),
+                true,
+                None,
+                &transport,
+            )
+            .expect("first quick-start");
+            let crate::lifecycle::QuickStartReport::Ready { team: ready_team, .. } = &first
+            else {
+                panic!("first producer must return Ready; got {first:?}");
+            };
+            assert_eq!(ready_team, "from-name");
+            let ready_command = crate::cli::adapters::send_command(
+                "implementer",
+                &team_dir,
+                Some(ready_team.as_str()),
+            )
+            .expect("Ready send_command");
+            assert_eq!(
+                crate::cli::adapters::split_shell_argv(&ready_command),
+                vec![
+                    "team-agent".to_string(),
+                    "send".to_string(),
+                    "implementer".to_string(),
+                    "MESSAGE".to_string(),
+                    "--workspace".to_string(),
+                    team_dir.to_string_lossy().into_owned(),
+                    "--team".to_string(),
+                    "from-name".to_string(),
+                ]
+            );
+            let report = crate::lifecycle::quick_start_with_transport(
+                &team_dir,
+                Some("from-name"),
+                true,
+                None,
+                &transport,
+            )
+            .expect("second quick-start");
+            let crate::lifecycle::QuickStartReport::ExistingRuntime {
+                team: canonical,
+                agent_ids,
+                ..
+            } = &report
+            else {
+                panic!("producer must return ExistingRuntime; got {report:?}");
+            };
+            assert_eq!(canonical.as_deref(), Some("from-name"));
+            assert!(agent_ids.iter().any(|id| id == "implementer"));
+            let mut value = quick_start_value(report);
+            crate::cli::adapters::append_send_guidance(&mut value, &team_dir, None);
+            let command = value
+                .pointer("/send_commands/0")
+                .and_then(Value::as_str)
+                .expect("producer send_commands");
+            assert_eq!(
+                crate::cli::adapters::split_shell_argv(command),
+                vec![
+                    "team-agent".to_string(),
+                    "send".to_string(),
+                    "implementer".to_string(),
+                    "MESSAGE".to_string(),
+                    "--workspace".to_string(),
+                    team_dir.to_string_lossy().into_owned(),
+                    "--team".to_string(),
+                    "from-name".to_string(),
+                ]
+            );
+            let _ = std::fs::remove_dir_all(&root);
+        }
+
+        #[test]
+        fn existing_runtime_json_includes_canonical_team_and_agent_ids() {
+            let value = quick_start_value(crate::lifecycle::QuickStartReport::ExistingRuntime {
+                team: Some("from-spec".to_string()),
+                session_name: Some(crate::transport::SessionName::new("team-from-spec")),
+                state_path: Some(PathBuf::from("/tmp/state.json")),
+                next_actions: vec!["restart".to_string()],
+                attach_commands: Vec::new(),
+                agent_ids: vec!["sol".to_string(), "luna".to_string()],
+            });
+            assert_eq!(value.get("team").and_then(Value::as_str), Some("from-spec"));
+            assert_eq!(
+                value
+                    .get("agent_ids")
+                    .and_then(Value::as_array)
+                    .map(|items| items
+                        .iter()
+                        .filter_map(Value::as_str)
+                        .collect::<Vec<_>>()),
+                Some(vec!["sol", "luna"])
+            );
+        }
+
         #[test]
         fn existing_runtime_json_includes_attach_commands() {
             let value = quick_start_value(crate::lifecycle::QuickStartReport::ExistingRuntime {
@@ -3536,6 +3917,7 @@ pub mod lifecycle_port {
                 attach_commands: vec![
                     "tmux -S /tmp/tmux-501/ta-test attach -t team-teamA:worker".to_string()
                 ],
+                agent_ids: vec!["worker".to_string()],
             });
             assert_eq!(
                 value.pointer("/attach_commands/0").and_then(Value::as_str),
@@ -3548,6 +3930,37 @@ pub mod lifecycle_port {
             );
         }
 
+        #[test]
+        fn existing_runtime_send_guidance_does_not_pair_alice_with_bob() {
+            let mut value = quick_start_value(crate::lifecycle::QuickStartReport::ExistingRuntime {
+                team: Some("bob".to_string()),
+                session_name: Some(crate::transport::SessionName::new("team-bob")),
+                state_path: Some(PathBuf::from("/tmp/state.json")),
+                next_actions: vec!["restart".to_string()],
+                attach_commands: Vec::new(),
+                agent_ids: vec!["bob".to_string()],
+            });
+            crate::cli::adapters::append_send_guidance(
+                &mut value,
+                Path::new("/tmp/ws"),
+                Some("bob"),
+            );
+            let command = value
+                .pointer("/send_commands/0")
+                .and_then(Value::as_str)
+                .expect("bob send command");
+            let argv = crate::cli::adapters::split_shell_argv(command);
+            assert_eq!(argv.get(2).map(String::as_str), Some("bob"));
+            assert_eq!(
+                argv.iter()
+                    .position(|item| item == "--team")
+                    .and_then(|i| argv.get(i + 1))
+                    .map(String::as_str),
+                Some("bob")
+            );
+            assert!(!argv.iter().any(|item| item == "alice"));
+        }
+
         #[test]
         fn preflight_blocked_json_includes_empty_attach_commands() {
             let value = quick_start_value(crate::lifecycle::QuickStartReport::PreflightBlocked {
@@ -3579,40 +3992,6 @@ pub mod lifecycle_port {
                 Some(crate::cli::QUICK_START_REMINDER)
             );
         }
-
-        #[test]
-        fn spawn_failure_without_session_does_not_claim_a_worker_pane_exists() {
-            let value = restart_value(
-                crate::lifecycle::RestartReport::Failed {
-                    session_name: crate::transport::SessionName::new("team-current"),
-                    failed_agents: vec![crate::lifecycle::RestartFailedAgent {
-                        agent_id: crate::model::ids::AgentId::new("coder"),
-                        restart_mode: crate::lifecycle::StartMode::Fresh,
-                        decision: crate::lifecycle::ResumeDecision::FreshStart,
-                        session_id: None,
-                        phase: "spawn".to_string(),
-                        error: "provider io error".to_string(),
-                    }],
-                    next_actions: Vec::new(),
-                    attach_commands: Vec::new(),
-                },
-                None,
-            );
-            let action = value
-                .pointer("/failed_agents/0/action")
-                .and_then(Value::as_str)
-                .expect("spawn failure action");
-
-            assert!(
-                action.contains("before a pane was created"),
-                "action={action}"
-            );
-            assert!(
-                !action.contains("inspect worker coder output"),
-                "action={action}"
-            );
-            assert!(!action.contains("restart-agent"), "action={action}");
-        }
     }
 
     pub(crate) fn compact_restart_value(value: &mut Value) {
@@ -3624,7 +4003,7 @@ pub mod lifecycle_port {
         }
     }
 
-    fn restart_value(report: crate::lifecycle::RestartReport, team: Option<&str>) -> Value {
+    pub fn restart_value(report: crate::lifecycle::RestartReport, team: Option<&str>) -> Value {
         match report {
             crate::lifecycle::RestartReport::Restarted {
                 session_name,
@@ -3633,17 +4012,29 @@ pub mod lifecycle_port {
                 coordinator,
                 next_actions,
                 attach_commands,
-            } => json!({
-                "ok": true,
-                "status": "restarted",
-                "session_name": session_name.as_str(),
-                "agents": agents.iter().map(|a| a.agent_id.as_str()).collect::<Vec<_>>(),
-                "coordinator_started": coordinator_started,
-                "coordinator": crate::lifecycle::coordinator_start_summary_value(&coordinator),
-                "next_actions": next_actions,
-                "attach_commands": attach_commands,
-                "reminder": crate::cli::QUICK_START_REMINDER,
-            }),
+                attach_window_failures,
+                leader_bind_ok,
+                leader_bind_reason,
+            } => {
+                let mut value = json!({
+                    "ok": leader_bind_ok,
+                    "status": if leader_bind_ok { "restarted" } else { "restarted_binding_incomplete" },
+                    "session_name": session_name.as_str(),
+                    "agents": agents.iter().map(|a| a.agent_id.as_str()).collect::<Vec<_>>(),
+                    "coordinator_started": coordinator_started,
+                    "coordinator": crate::lifecycle::coordinator_start_summary_value(&coordinator),
+                    "next_actions": next_actions,
+                    "attach_commands": attach_commands,
+                    "reminder": crate::cli::QUICK_START_REMINDER,
+                });
+                if let Some(debt) = attach_window_failures {
+                    value["attach_window_failures"] = debt;
+                }
+                if let Some(reason) = leader_bind_reason {
+                    value["reason"] = json!(reason);
+                }
+                value
+            },
             crate::lifecycle::RestartReport::Partial {
                 session_name,
                 agents,
@@ -3652,35 +4043,52 @@ pub mod lifecycle_port {
                 coordinator,
                 next_actions,
                 attach_commands,
-            } => json!({
-                "ok": false,
-                "status": "partial",
-                "reason": "restart_agent_failed",
-                "session_name": session_name.as_str(),
-                "agents": agents.iter().map(|a| a.agent_id.as_str()).collect::<Vec<_>>(),
-                "failed_agents": failed_agents.iter().map(|failure| json!({
-                    "agent_id": failure.agent_id.as_str(),
-                    "restart_mode": failure.restart_mode,
-                    "decision": failure.decision,
-                    "session_id": failure.session_id.as_ref().map(|session| session.as_str()),
-                    "phase": failure.phase,
-                    "error": failure.error,
-                    "action": crate::lifecycle::restart_failure_action(
-                        &failure.agent_id,
-                        &failure.phase,
-                        failure.session_id.as_ref(),
-                    ),
-                    "log": format!(
-                        ".team/logs/coordinator.log and .team/runtime/state.json agent={}",
-                        failure.agent_id
-                    ),
-                })).collect::<Vec<_>>(),
-                "coordinator_started": coordinator_started,
-                "coordinator": crate::lifecycle::coordinator_start_summary_value(&coordinator),
-                "next_actions": next_actions,
-                "attach_commands": attach_commands,
-                "reminder": crate::cli::QUICK_START_REMINDER,
-            }),
+                attach_window_failures,
+                leader_bind_ok,
+                leader_bind_reason,
+            } => {
+                let mut value = json!({
+                    "ok": false,
+                    "status": "partial",
+                    "reason": "restart_agent_failed",
+                    "leader_bind_ok": leader_bind_ok,
+                    "session_name": session_name.as_str(),
+                    "agents": agents.iter().map(|a| a.agent_id.as_str()).collect::<Vec<_>>(),
+                    "failed_agents": failed_agents.iter().map(|failure| json!({
+                        "agent_id": failure.agent_id.as_str(),
+                        "restart_mode": failure.restart_mode,
+                        "decision": failure.decision,
+                        "session_id": failure.session_id.as_ref().map(|session| session.as_str()),
+                        "phase": failure.phase,
+                        "error": failure.error,
+                        "action": format!(
+                            "inspect worker {} output, then restart that worker with `team-agent restart-agent {}` or rerun `team-agent restart --allow-fresh`",
+                            failure.agent_id,
+                            failure.agent_id
+                        ),
+                        "log": format!(
+                            ".team/logs/coordinator.log and .team/runtime/state.json agent={}",
+                            failure.agent_id
+                        ),
+                    })).collect::<Vec<_>>(),
+                    "coordinator_started": coordinator_started,
+                    "coordinator": crate::lifecycle::coordinator_start_summary_value(&coordinator),
+                    "next_actions": next_actions,
+                    "attach_commands": attach_commands,
+                    "reminder": crate::cli::QUICK_START_REMINDER,
+                });
+                if let Some(debt) = attach_window_failures {
+                    value["attach_window_failures"] = debt;
+                }
+                if !leader_bind_ok {
+                    value["ok"] = json!(false);
+                    value["status"] = json!("partial_binding_incomplete");
+                }
+                if let Some(reason) = leader_bind_reason {
+                    value["leader_bind_reason"] = json!(reason);
+                }
+                value
+            },
             crate::lifecycle::RestartReport::Failed {
                 session_name,
                 failed_agents,
@@ -3699,10 +4107,10 @@ pub mod lifecycle_port {
                     "session_id": failure.session_id.as_ref().map(|session| session.as_str()),
                     "phase": failure.phase,
                     "error": failure.error,
-                    "action": crate::lifecycle::restart_failure_action(
-                        &failure.agent_id,
-                        &failure.phase,
-                        failure.session_id.as_ref(),
+                    "action": format!(
+                        "inspect worker {} output, then restart that worker with `team-agent restart-agent {}` or rerun `team-agent restart --allow-fresh`",
+                        failure.agent_id,
+                        failure.agent_id
                     ),
                     "log": format!(
                         ".team/logs/coordinator.log and .team/runtime/state.json agent={}",
@@ -4055,9 +4463,6 @@ pub mod lifecycle_port {
                 let repair_team = team
                     .filter(|team| !team.is_empty())
                     .unwrap_or(session_name.as_str());
-                let claim =
-                    format!("team-agent claim-leader --team {repair_team} --confirm --json");
-                let takeover = format!("team-agent takeover --team {repair_team} --confirm --json");
                 json!({
                     "ok": false,
                     "status": "refused_dirty_topology",
@@ -4068,11 +4473,11 @@ pub mod lifecycle_port {
                         .iter()
                         .map(|id| json!({"id": id}))
                         .collect::<Vec<_>>(),
-                    "next_actions": [
-                        "team-agent diagnose --json",
-                        claim,
-                        takeover
-                    ],
+                    "next_actions": dirty_topology_next_actions(
+                        &reason,
+                        &issue_ids,
+                        repair_team,
+                    ),
                     "reminder": crate::cli::QUICK_START_REMINDER,
                 })
             }
@@ -4290,6 +4695,45 @@ pub mod lifecycle_port {
             );
         }
 
+        #[test]
+        fn restart_missing_team_spec_does_not_point_to_add_agent() {
+            // Live empty-workspace restart: error is missing spec/runtime, but the
+            // workspace path commonly contains "team-agent", which the substring
+            // "not found"+"agent" matcher treats as start-agent miss.
+            let msg = "team select: active team spec not found: \
+                 input_workspace=/tmp/team-agent-live-missing \
+                 expected_runtime_dir=/tmp/team-agent-live-missing/.team/runtime";
+            let na = error_next_action(msg).expect("missing spec must keep a recovery action");
+            assert!(
+                !na.contains("add-agent"),
+                "must not steer restart-missing-spec to add-agent: {na}"
+            );
+            assert!(
+                !na.contains("start-agent only starts an agent"),
+                "must not reuse the start-agent miss copy: {na}"
+            );
+            assert!(
+                na.contains("quick-start"),
+                "must steer first launch to quick-start: {na}"
+            );
+        }
+
+        #[test]
+        fn restart_missing_spec_error_value_keeps_recovery_action() {
+            let err = crate::lifecycle::LifecycleError::RequirementUnmet(
+                "team select: active team spec not found: input_workspace=/tmp/team-agent-empty expected_runtime_dir=/tmp/team-agent-empty/.team/runtime"
+                    .to_string(),
+            );
+            let v = error_value(err);
+            assert_eq!(v["ok"], serde_json::json!(false));
+            let na = v["next_action"].as_str().unwrap_or("");
+            assert!(
+                na.contains("quick-start"),
+                "error_value must attach spec-missing recovery, got {v}"
+            );
+            assert!(!na.contains("add-agent"), "must not attach add-agent: {v}");
+        }
+
         #[test]
         fn error_value_attaches_next_action_field() {
             let err = crate::lifecycle::LifecycleError::RequirementUnmet(
@@ -4305,6 +4749,21 @@ pub mod lifecycle_port {
                 "error_value must attach the add-agent guidance: {v}"
             );
         }
+
+        #[test]
+        fn profile_not_found_preserves_error_without_agent_guidance() {
+            let detail =
+                "profile pi-default not found; run team-agent profile init pi-default --auth-mode subscription";
+            let v = error_value(crate::lifecycle::LifecycleError::RequirementUnmet(
+                detail.to_string(),
+            ));
+            let expected = format!("agent start requirement unmet: {detail}");
+            assert_eq!(v["error"].as_str(), Some(expected.as_str()));
+            assert!(
+                v.get("next_action").is_none(),
+                "profile missing must not suggest start-agent/add-agent: {v}"
+            );
+        }
     }
 }
 
@@ -5260,11 +5719,14 @@ pub mod leader_port {
         if let Some(topology_convergence) = result.topology_convergence {
             out.insert("topology_convergence".to_string(), topology_convergence);
         }
+        if let Some(attach_window_failures) = result.attach_window_failures {
+            out.insert("attach_window_failures".to_string(), attach_window_failures);
+        }
         Value::Object(out)
     }
 
     fn attach_lease_value(result: crate::leader::LeaseResult, requeued: Value) -> Value {
-        json!({
+        let mut value = json!({
             "ok": result.ok,
             "leader_receiver": result
                 .receiver
@@ -5277,7 +5739,11 @@ pub mod leader_port {
                 "action": result.action,
             },
             "requeued_exhausted_watchers": requeued,
-        })
+        });
+        if let Some(attach_window_failures) = result.attach_window_failures {
+            value["attach_window_failures"] = attach_window_failures;
+        }
+        value
     }
 
     fn attach_requeued_exhausted_watchers(