@team-agent/installer 0.5.119 → 0.5.121

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

@@ -57,6 +57,8 @@ pub(crate) const STATUS_REMINDER: &str =
     "Next: use team-agent inbox leader -n 3 for replies. Status is not proof of task completion; do not inspect worker terminal content.";
 
 pub mod adapters;
+mod arguments;
+mod intent;
 #[cfg(unix)]
 mod shutdown_socket;
 pub mod attach_app_server_leader;
@@ -194,7 +196,7 @@ pub mod lifecycle_port {
             crate::leader::LeaderLaunchStatus::NotStarted => false,
         };
         let leader_attach_command = if outcome.reason.as_deref() == Some("PaneWorkspaceMismatch") {
-            Some("team-agent attach-leader".to_string())
+            Some(format!("team-agent attach-leader --provider {}", crate::provider::wire::provider_wire(provider)))
         } else {
             leader_attach_command_for_plan(cwd, &plan)
         };
@@ -387,14 +389,16 @@ pub mod lifecycle_port {
         }
 
         let hint_action = match refusal.recovery.hint_action {
-            PaneAuthorityRecoveryHint::AttachLeader => "team-agent attach-leader",
+            PaneAuthorityRecoveryHint::AttachLeader => format!(
+                "team-agent attach-leader --provider {}", crate::provider::wire::provider_wire(provider)
+            ),
         };
         let action = match refusal.recovery.action {
             PaneAuthorityRecoveryAction::OpenTerminalOutsideCurrentTmuxPaneOrAttachFromMatchingPane => {
-                "open a new terminal window outside the current tmux/pane, confirm TMUX and \
+                format!("open a new terminal window outside the current tmux/pane, confirm TMUX and \
                  TMUX_PANE are absent, change directory to the requested workspace, and restart \
                  the leader; alternatively enter the matching workspace pane and run \
-                 `team-agent attach-leader`"
+                 `{hint_action}`")
             }
         };
         facts.insert(
@@ -1720,7 +1724,10 @@ pub mod lifecycle_port {
             let wp = crate::coordinator::WorkspacePath::new(run_workspace.clone());
             let coordinator_pid_before_stop = crate::coordinator::coordinator_health(&wp).pid;
             coordinator_pid_for_report = coordinator_pid_before_stop.map(|pid| pid.get());
-            match stop_coordinator_bounded(wp, std::time::Duration::from_millis(900)) {
+            // Owned termination can use 5s graceful + 5s escalation waits.
+            // Await its result within the existing shutdown deadline, not an
+            // unrelated 900ms cap that abandons a still-finishing stop worker.
+            match stop_coordinator_bounded(wp, deadline.remaining()) {
                 Some(Ok(report)) => Some(report),
                 Some(Err(error)) => {
                     kill_error.get_or_insert(error);
@@ -4091,6 +4098,25 @@ pub mod lifecycle_port {
                     "reminder": crate::cli::QUICK_START_REMINDER,
                     "readiness": readiness_json.clone(),
                     "worker_readiness": readiness_json,
+                    "effects": {"worker_panes_started": agent_ids, "coordinator_start": "running_confirmed"},
+                })
+            }
+            crate::lifecycle::QuickStartReport::Partial {
+                workspace, session_name, launch, team, error, coordinator_state,
+            } => {
+                let agents: Vec<_> = launch.started.iter().map(|agent| agent.agent_id.as_str())
+                    .chain(launch.contract_started.iter().map(|id| id.as_str())).collect();
+                let recovery = format!(
+                    "team-agent doctor --workspace {} --team {} --json; inspect confirmed effects before any retry; no automatic rollback is claimed",
+                    shell_quote(&workspace.to_string_lossy()), shell_quote(&team),
+                );
+                json!({
+                    "ok": false, "status": "partial", "phase": "post_spawn",
+                    "workspace": workspace, "team": team, "session_name": session_name.as_str(),
+                    "error": crate::redaction::redact_external_text(&error),
+                    "effects": {"worker_panes_started": agents, "coordinator_start": coordinator_state},
+                    "last_confirmed_effect": if agents.is_empty() {Value::Null} else {json!("worker_panes_started")},
+                    "current_state": "unknown", "recovery": recovery,
                 })
             }
             crate::lifecycle::QuickStartReport::ExistingRuntime {
@@ -4122,6 +4148,7 @@ pub mod lifecycle_port {
                 "ok": false,
                 "status": "preflight_blocked",
                 "reason": "quick-start preflight blocked",
+                "effects": {"worker_panes_started": [], "coordinator_start": "not_attempted"},
                 "summary": summary,
                 "blockers": blockers,
                 "next_actions": next_actions,
@@ -4205,6 +4232,25 @@ pub mod lifecycle_port {
                 .is_some());
         }
 
+        #[test]
+        fn issue337_partial_start_receipt_retains_workers_and_scoped_recovery() {
+            let crate::lifecycle::QuickStartReport::Ready { launch, .. } = pending_tool_load_report() else { panic!() };
+            let value = quick_start_value(crate::lifecycle::QuickStartReport::Partial {
+                workspace: PathBuf::from("/owned/work space"),
+                session_name: crate::transport::SessionName::new("team-demo"),
+                launch, team: "demo".into(), error: "caller disappeared".into(),
+                coordinator_state: "not_attempted".into(),
+            });
+            assert_eq!(value["status"], "partial");
+            assert_eq!(value["effects"]["worker_panes_started"], json!(["worker"]));
+            assert_eq!(value["effects"]["coordinator_start"], "not_attempted");
+            assert_eq!(value["last_confirmed_effect"], "worker_panes_started");
+            let recovery = value["recovery"].as_str().unwrap();
+            let argv = split_shell_argv(recovery);
+            assert!(argv.windows(2).any(|pair| pair == ["--workspace", "/owned/work space"]));
+            assert!(argv.windows(2).any(|pair| pair == ["--team", "demo"]));
+        }
+
         fn pending_tool_load_report() -> crate::lifecycle::QuickStartReport {
             crate::lifecycle::QuickStartReport::Ready {
                 session_name: crate::transport::SessionName::new("team-demo"),
@@ -4425,7 +4471,7 @@ pub mod lifecycle_port {
         #[test]
         #[serial_test::serial(env)]
         fn existing_runtime_producer_scopes_send_team() {
-            let _hermetic = super::super::hermetic_test_support::HermeticTestEnv::enter(
+            let _hermetic = super::super::hermetic_test_support::HermeticTestEnv::enter_with_leader(
                 "quick-start-value-existing-runtime",
             );
             let root = std::env::temp_dir().join(format!(
@@ -4448,6 +4494,7 @@ pub mod lifecycle_port {
                 "---\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();
+            super::super::hermetic_test_support::seed_in_process_coordinator(&root);
             let transport = crate::transport::test_support::OfflineTransport::new();
             let first = crate::lifecycle::quick_start_with_transport(
                 &team_dir,

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

@@ -1050,6 +1050,7 @@ fn resolve_leader(
                 None,
                 None,
                 transport.tmux_endpoint(),
+                None,
             );
             err.candidates =
                 leader_advisory_candidates(state, team, transport, "state_recorded_socket");
@@ -1111,6 +1112,7 @@ fn resolve_leader(
                 session,
                 window,
                 socket,
+                string_field(receiver, "provider"),
             );
             if matches!(
                 &reason,
@@ -1131,6 +1133,7 @@ fn resolve_leader(
                 session,
                 window,
                 socket,
+                string_field(receiver, "provider"),
             );
             err.log = format!("{} channel_probe_failed={error}", err.log);
             Err(err)
@@ -1574,14 +1577,20 @@ fn leader_not_attached_third_party(
     session: Option<&str>,
     window: Option<&str>,
     socket: Option<String>,
+    provider: Option<&str>,
 ) -> NamedAddressError {
     let workspace = target_workspace.display();
     let mut err = NamedAddressError::new(
         NamedAddressErrorKind::LeaderNotAttached,
         "target team leader is not attached on its recorded tmux endpoint",
     );
+    let provider = provider.and_then(crate::provider::wire::parse_provider)
+        .map(crate::provider::wire::provider_wire);
+    let workspace_arg = super::adapters::shell_quote(&target_workspace.to_string_lossy());
+    let team_arg = super::adapters::shell_quote(team);
     err.action = format!(
-        "Ask the target team owner to run `team-agent attach-leader --workspace {workspace} --team {team}`; the sender-side offline mailbox will requeue the message once attach succeeds"
+        "Ask the target team owner to select the actual Leader provider and run `team-agent attach-leader --workspace {workspace_arg} --team {team_arg} --provider {}`; the sender-side offline mailbox will requeue the message once attach succeeds",
+        provider.unwrap_or("<provider>")
     );
     err.log = format!(
         "name={team}/leader expected_pane={} expected_session={} expected_window={} tmux_socket={}",

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

@@ -32,6 +32,10 @@ pub(crate) enum TokenUsage {
 }
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub(crate) enum DispatchKind {
+    Start,
+    Stop,
+    Team,
+    Agent,
     QuickStart,
     Send,
     Status,
@@ -59,6 +63,10 @@ pub(crate) enum DispatchKind {
     AttachLeader,
 }
 pub(crate) const ALL_DISPATCH_KINDS: &[DispatchKind] = &[
+    DispatchKind::Start,
+    DispatchKind::Stop,
+    DispatchKind::Team,
+    DispatchKind::Agent,
     DispatchKind::QuickStart,
     DispatchKind::Send,
     DispatchKind::Status,
@@ -110,20 +118,24 @@ pub(crate) struct CommandSpec {
 // Only human operations belong here. Compatibility commands are private in emit.rs.
 #[rustfmt::skip]
 pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
-    CommandSpec { name: "quick-start", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::QuickStart), summary: "Create a team from role files; use restart for an initialized team", usage: "team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--team TEAM] [--name NAME] [--team-id TEAM] [--yes] [--backend tmux|conpty] [--json] [--detail]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
+    CommandSpec { name: "start", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::Start), summary: "Start a team or agent; verified live instances stay unchanged", usage: "team-agent start [AGENT|./TEAMDIR] [--from TEAMDIR] [--workspace PATH] [--team KEY] [--session preserve|auto] [--dry-run] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
+    CommandSpec { name: "stop", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Stop), summary: "Stop the selected team or one agent, retaining session associations", usage: "team-agent stop [AGENT] [--workspace PATH] [--team KEY] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
+    CommandSpec { name: "team", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Team), summary: "Explicit team start, stop, restart or status", usage: "team-agent team <start|stop|restart|status> [OPTIONS]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
+    CommandSpec { name: "agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::Agent), summary: "Explicit agent lifecycle operations", usage: "team-agent agent <start|stop|restart|add|remove|reset|clone|fork> AGENT [OPTIONS]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
+    CommandSpec { name: "quick-start", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::QuickStart), summary: "Compatibility creation bridge; prefer start for daily activation", usage: "team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--team TEAM] [--name NAME] [--team-id TEAM] [--yes] [--backend tmux|conpty] [--json] [--detail]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
     CommandSpec { name: "send", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::Send), summary: "Send a task to a specified agent", usage: "team-agent send <agent> MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--mailbox] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: Some("a future compatibility release"), action: Some("Use team-agent send <agent> 'task message'; select scope with --workspace and --team"), governance: None },
     CommandSpec { name: "status", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::Status), summary: "Check agent status without reading conversation content", usage: "team-agent status [<agent>] [--workspace WORKSPACE] [--team TEAM] [--json] [--summary|--detail]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
     CommandSpec { name: "models", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::Models), summary: "Discover model names supported by the native provider", usage: "team-agent models [--provider pi|cursor|cursor_agent|codex|claude|claude_code|grok|kiro] [QUERY|--search TEXT] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
     CommandSpec { name: "inbox", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::Inbox), summary: "Read agent replies", usage: "team-agent inbox <agent> [-n N|--limit N] [--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: "restart", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Restart), summary: "Restart an existing team using saved sessions when available", usage: "team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json] [--detail]", 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: "Shut down the selected team and report residual resources", 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 and start an agent", usage: "team-agent add-agent <agent> [--role-file FILE] [--provider TOOL] [--model MODEL] [--effort LEVEL] [--bypass true|false] [--prompt TEXT] [--profile NAME] [--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 team agent", usage: "team-agent start-agent <agent> [--provider TOOL] [--model MODEL] [--effort LEVEL] [--bypass true|false] [--prompt TEXT] [--profile 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 an agent while retaining configuration and session history", 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: "Discard an agent's saved session association", usage: "team-agent reset-agent <agent> --discard-session [--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: "clone-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::CloneAgent), summary: "Clone agent configuration into a new agent", usage: "team-agent clone-agent <agent> --as NEW_AGENT [--label LABEL] [--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: "fork-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::ForkAgent), summary: "Fork an agent session where supported by the provider", usage: "team-agent fork-agent <agent> --as NEW_AGENT [--label LABEL] [--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: "remove-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::RemoveAgent), summary: "Remove an agent after confirmation", usage: "team-agent remove-agent <agent> --confirm [--workspace WORKSPACE] [--team TEAM] [--from-spec] [--force] [--json]", default_help: true, 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 one agent, or use the frozen bare/path team bridge", usage: "team-agent restart [AGENT|./WORKSPACE] [--workspace WORKSPACE] [--team TEAM] [--session auto|preserve] [--dry-run] [--allow-fresh] [--session-converge-deadline SECONDS] [--json] [--detail]", 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: "Compatibility: shut down the selected team; prefer stop", 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: "Compatibility: strict add-and-start; prefer agent add or start AGENT", usage: "team-agent add-agent <agent> [--role-file FILE] [--provider TOOL] [--model MODEL] [--effort LEVEL] [--bypass true|false] [--prompt TEXT] [--profile NAME] [--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: "Compatibility: start an existing stopped agent; prefer start AGENT", usage: "team-agent start-agent <agent> [--provider TOOL] [--model MODEL] [--effort LEVEL] [--bypass true|false] [--prompt TEXT] [--profile 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: "Compatibility: stop an agent; prefer stop AGENT", 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: "Compatibility: discard session only with approval; prefer agent reset", usage: "team-agent reset-agent <agent> --discard-session [--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: "clone-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::CloneAgent), summary: "Compatibility: copy agent configuration; prefer agent clone", usage: "team-agent clone-agent <agent> --as NEW_AGENT [--label LABEL] [--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: "fork-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::ForkAgent), summary: "Compatibility: admitted new-seat continuation; prefer agent fork", usage: "team-agent fork-agent <agent> --as NEW_AGENT [--label LABEL] [--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: "remove-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::RemoveAgent), summary: "Compatibility: confirmed removal; prefer agent remove", usage: "team-agent remove-agent <agent> --confirm [--workspace WORKSPACE] [--team TEAM] [--from-spec] [--force] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
     CommandSpec { name: "leaders", tier: CommandTier::Core, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Leaders), summary: "List local leaders and their team scopes", usage: "team-agent leaders [QUERY|--search TEXT] [--all|--stale] [--json] | --prune [--dry-run] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
     CommandSpec { name: "doctor", tier: CommandTier::Core, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Doctor), summary: "Diagnose a team and suggest recovery; read-only by default", usage: "team-agent doctor [SPEC] [--workspace WORKSPACE] [--team TEAM] [--comms] [--gate orphans|comms] [--fix] [--fix-schema] [--cleanup-orphans] [--confirm] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
     CommandSpec { name: "approvals", tier: CommandTier::Core, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Approvals), summary: "List pending agent approvals", usage: "team-agent approvals [<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 },

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

@@ -115,6 +115,7 @@ struct BriefNode {
     health: String,
     session_name: Option<String>,
     tmux_command: Option<String>,
+    observation_reason: Option<&'static str>,
 }
 
 #[derive(Clone, Debug, PartialEq, Eq)]
@@ -125,9 +126,10 @@ struct AttachContext {
     pane: String,
 }
 
-#[derive(Debug)]
+#[derive(Debug, Default)]
 struct ProbeResult {
     nodes: Vec<ProbeNode>,
+    exited: BTreeSet<(String, String, String)>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -158,7 +160,7 @@ pub(crate) fn status_brief_scoped(workspace: &Path, state: &Value, agent: Option
     json!({
         "nodes": nodes
             .into_iter()
-            .map(|(node, _)| node.into_json())
+            .map(|(node, _)| scoped_node_json(node, workspace, state))
             .collect::<Vec<_>>()
     })
 }
@@ -167,14 +169,22 @@ pub(crate) fn status_brief_scoped(workspace: &Path, state: &Value, agent: Option
 /// context only when multiple nodes make that repetition useful.
 pub(crate) fn format_status_brief(workspace: &Path, state: &Value, agent: Option<&str>) -> String {
     let nodes = project_status_nodes(workspace, state, agent);
-    if nodes.len() <= 1 {
-        return nodes
-            .into_iter()
-            .filter_map(|(node, _)| format_brief_node(&node.into_json()))
-            .collect::<Vec<_>>()
-            .join("\n");
+    let diagnostics = nodes.iter().filter(|(node, _)| node.observation_reason.is_some())
+        .map(|(node, _)| {
+            let value = scoped_node_json(node.clone(), workspace, state);
+            format!("observation {}: {}; next_action: {}", node.name,
+                value["observation_reason"].as_str().unwrap_or("observation_inconclusive"),
+                value["next_action"].as_str().unwrap_or(""))
+        }).collect::<Vec<_>>();
+    let mut output = if nodes.len() <= 1 {
+        nodes.into_iter().filter_map(|(node, _)| format_brief_node(&node.into_json()))
+            .collect::<Vec<_>>().join("\n")
+    } else { format_multi_node_brief(nodes) };
+    if !diagnostics.is_empty() {
+        output.push('\n');
+        output.push_str(&diagnostics.join("\n"));
     }
-    format_multi_node_brief(nodes)
+    output
 }
 
 fn project_status_nodes(
@@ -200,13 +210,18 @@ fn project_status_nodes(
         .map(|node| {
             #[cfg(unix)]
             if crate::contract_runtime::registry::descriptor(&node.provider).is_some() {
-                let mut brief = BriefNode::unknown(node);
+                let mut brief = BriefNode::unknown(node).with_reason("native_runtime_projection_unavailable");
                 if let Ok(native) = crate::contract_runtime::framework::project_seat(
                     _workspace,
                     &crate::state::projection::team_state_key(state),
                     &node.name,
                 ) {
                     brief.runtime_status = native["status"].as_str().unwrap_or("unknown").into();
+                    brief.observation_reason = match brief.runtime_status.as_str() {
+                        "running" => Some("activity_or_health_not_observed"),
+                        "stopped" => None,
+                        _ => Some("native_runtime_not_ready"),
+                    };
                     brief.model = native["model"].as_str().map(str::to_owned);
                     brief.effort = native["effort"].as_str().map(str::to_owned);
                     if brief.runtime_status == "running" {
@@ -596,11 +611,14 @@ fn sample_native_panes(
     } else {
         snapshots(&pids)
     };
+    let exited = panes.iter().filter(|fields| {
+        native_pane_pid(fields[3]).and_then(|pid| processes.get(&pid)).is_some_and(|p| p.zombie)
+    }).map(|fields| (fields[0].to_string(), fields[1].to_string(), fields[2].to_string())).collect();
     let nodes = panes
         .into_iter()
         .filter_map(|fields| parse_native_pane(fields, endpoint, registered, &processes))
         .collect();
-    ProbeResult { nodes }
+    ProbeResult { nodes, exited }
 }
 
 fn native_pane_fields(line: &str) -> Option<[&str; 5]> {
@@ -1199,7 +1217,7 @@ fn parse_probe(bytes: &[u8], requested_endpoint: &str) -> Result<ProbeResult, ()
         .iter()
         .filter_map(|node| parse_probe_node(node, report_socket))
         .collect();
-    Ok(ProbeResult { nodes })
+    Ok(ProbeResult { nodes, ..Default::default() })
 }
 
 #[cfg(test)]
@@ -1273,18 +1291,34 @@ fn project_node_with_attach(
                 health: "unknown".to_string(),
                 session_name: None,
                 tmux_command: None,
+                observation_reason: None,
             },
-            MatchResult::Unique(_) | MatchResult::Ambiguous => BriefNode::unknown(node),
+            MatchResult::Unique(_) | MatchResult::Ambiguous => BriefNode::unknown(node).with_reason("stopped_registration_has_live_pane"),
         };
         return (projected, None);
     }
     let MatchResult::Unique(observed) = matched else {
-        return (BriefNode::unknown(node), None);
+        let reason = if matches!(matched, MatchResult::Ambiguous) {
+            "pane_observation_ambiguous"
+        } else if node.endpoint.is_none() {
+            "endpoint_unregistered"
+        } else if node.session.is_none() || node.pane.is_none() {
+            "pane_binding_incomplete"
+        } else if let Some(sample) = probe.and_then(Option::as_ref) {
+            if sample.exited.iter().any(|(session, window, pane)| {
+                node.session.as_deref() == Some(session.as_str())
+                    && node.window.as_deref().is_none_or(|name| name == window)
+                    && node.pane.as_deref() == Some(pane.as_str())
+            }) { "pane_process_exited" }
+            else if matches!(node.lifecycle.as_deref(), Some("starting" | "launching" | "pending")) { "startup_not_yet_observed" }
+            else { "registered_pane_not_observed" }
+        } else { "endpoint_probe_unavailable" };
+        return (BriefNode::unknown(node).with_reason(reason), None);
     };
     if !node.provider.eq_ignore_ascii_case("unknown")
         && !node.provider.eq_ignore_ascii_case(&observed.provider)
     {
-        return (BriefNode::unknown(node), None);
+        return (BriefNode::unknown(node).with_reason("provider_observation_mismatch"), None);
     }
     let pi_channel = observed.provider.eq_ignore_ascii_case("pi")
         && observed.evidence_method.as_deref() == Some("pi_activity_channel");
@@ -1321,6 +1355,7 @@ fn project_node_with_attach(
             health: health.to_string(),
             session_name: observed.session_name.clone(),
             tmux_command,
+            observation_reason: (activity == "unknown" || health == "unknown").then_some("activity_or_health_not_observed"),
         },
         attach,
     )
@@ -1405,9 +1440,15 @@ impl BriefNode {
             health: "unknown".to_string(),
             session_name: None,
             tmux_command: None,
+            observation_reason: Some("observation_inconclusive"),
         }
     }
 
+    fn with_reason(mut self, reason: &'static str) -> Self {
+        self.observation_reason = Some(reason);
+        self
+    }
+
     fn into_json(self) -> Value {
         let mut object = Map::new();
         object.insert("name".to_string(), json!(self.name));
@@ -1425,10 +1466,30 @@ impl BriefNode {
             "tmux_command".to_string(),
             self.tmux_command.map(Value::String).unwrap_or(Value::Null),
         );
+        if let Some(reason) = self.observation_reason {
+            object.insert("observation_reason".into(), json!(reason));
+        }
         Value::Object(object)
     }
 }
 
+fn scoped_node_json(node: BriefNode, workspace: &Path, state: &Value) -> Value {
+    let mut value = node.into_json();
+    if let Some(reason) = value["observation_reason"].as_str() {
+        let guidance = match reason {
+            "pane_process_exited" => "pane process exit confirmed; inspect saved session and Leader binding before explicit start",
+            "startup_not_yet_observed" | "native_runtime_not_ready" => "wait for startup convergence and recheck this scope; do not reset on unknown",
+            _ => "inspect this scope's observation and identity; do not infer process exit or retry lifecycle from unknown alone",
+        };
+        value["next_action"] = json!(format!(
+            "team-agent doctor --workspace {} --team {} --json; {guidance}",
+            shell_quote(&workspace.to_string_lossy()),
+            shell_quote(&crate::state::projection::team_state_key(state)),
+        ));
+    }
+    value
+}
+
 #[cfg(test)]
 mod native_ps_batch_regressions {
     #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
@@ -1448,6 +1509,35 @@ mod native_ps_batch_regressions {
         }
     }
 
+    #[test]
+    fn issue338_unknown_status_has_reason_and_same_scope_next_action() {
+        let state = json!({
+            "team_key": "scoped-team", "session_name": "sess",
+            "agents": {"worker": {"provider": "pi", "status": "running"}}
+        });
+        let status = status_brief_scoped(Path::new("/owned/workspace with spaces"), &state, None);
+        let node = &status["nodes"][0];
+        assert_eq!(node["runtime_status"], "unknown");
+        assert_eq!(node["observation_reason"], "endpoint_unregistered");
+        let action = node["next_action"].as_str().unwrap();
+        assert!(action.contains("--workspace '/owned/workspace with spaces'"));
+        assert!(action.contains("--team 'scoped-team'"));
+        assert!(action.contains("doctor"));
+        assert!(!action.contains("restart"));
+    }
+
+    #[test]
+    fn issue338_confirmed_zombie_is_not_reported_as_unexplained_unknown() {
+        let node = registered("e1", "%7");
+        let probe = sample_native_panes("hp\tw\t%7\t123\tpi\n", "e1", &[node.clone()], |_| {
+            BTreeMap::from([(123, ProcessSnapshot { zombie: true })])
+        });
+        let value = project_node(&node, Some(&Some(probe))).into_json();
+        assert_eq!(value["runtime_status"], "unknown");
+        assert_eq!(value["observation_reason"], "pane_process_exited");
+        assert!(value["tmux_command"].is_null());
+    }
+
     #[test]
     fn eight_panes_use_one_endpoint_query() {
         let registered = (0..8)
@@ -1713,6 +1803,7 @@ mod tests {
                     None,
                     Some(ProbeResult {
                         nodes: vec![probe("pi_activity_channel")],
+                        ..Default::default()
                     }),
                 ] {
                     let value = project_node(&node, Some(&sample)).into_json();
@@ -1724,7 +1815,11 @@ mod tests {
                         settings.0.unwrap_or("null"),
                         settings.1.unwrap_or("null")
                     )));
-                    assert_eq!(value.as_object().unwrap().len(), 9);
+                    let diagnostics = usize::from(value.get("observation_reason").is_some());
+                    assert_eq!(value.as_object().unwrap().len(), 9 + diagnostics);
+                    if value["runtime_status"] == "unknown" {
+                        assert!(!value["observation_reason"].as_str().unwrap().is_empty());
+                    }
                 }
             }
         }
@@ -1757,6 +1852,7 @@ mod tests {
             &node,
             Some(&Some(ProbeResult {
                 nodes: vec![observed],
+                ..Default::default()
             })),
         );
         assert_eq!(projected.runtime_status, "running");
@@ -1772,6 +1868,7 @@ mod tests {
             &node,
             Some(&Some(ProbeResult {
                 nodes: vec![observed],
+                ..Default::default()
             })),
         );
         assert_eq!(projected.activity, "idle");
@@ -1800,6 +1897,7 @@ mod tests {
             &node,
             Some(&Some(ProbeResult {
                 nodes: vec![observed],
+                ..Default::default()
             })),
         );
         assert_eq!(projected.runtime_status, "unknown");
@@ -1814,6 +1912,7 @@ mod tests {
             &node,
             Some(&Some(ProbeResult {
                 nodes: vec![probe("pi_activity_channel"), probe("pi_activity_channel")],
+                ..Default::default()
             })),
         );
         assert_eq!(projected.runtime_status, "unknown");
@@ -1829,6 +1928,7 @@ mod tests {
             &node,
             Some(&Some(ProbeResult {
                 nodes: vec![observed],
+                ..Default::default()
             })),
         );
         assert_eq!(projected.runtime_status, "unknown");
@@ -1841,6 +1941,7 @@ mod tests {
             &node,
             Some(&Some(ProbeResult {
                 nodes: vec![probe("pi_activity_channel"), probe("pi_activity_channel")],
+                ..Default::default()
             })),
         );
         assert_eq!(projected.runtime_status, "unknown");

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

@@ -875,7 +875,12 @@ fn kiro_leader_entry_has_help_and_typed_refusal_without_native_or_fallback_effec
         assert_eq!(value["reason"], "kiro_leader_not_admitted");
         let mut argv = vec!["kiro".into()];
         argv.extend(args);
-        assert_eq!(crate::cli::run(&argv, &cwd), ExitCode::Error);
+        let expected = if values.contains(&"--attach-existing") {
+            ExitCode::Usage // Unknown controls fail before capability dispatch.
+        } else {
+            ExitCode::Error // Supported syntax retains the typed refusal.
+        };
+        assert_eq!(crate::cli::run(&argv, &cwd), expected);
     }
     assert_eq!(std::fs::read_dir(&cwd).unwrap().count(), 0);
     assert_eq!(