@team-agent/installer 0.5.94 → 0.5.98

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

@@ -161,6 +161,19 @@ pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value
             }
             issues.push(issue);
         }
+        // Preserve distinct worker failures even when the shared session probe
+        // short-circuits pane enumeration.  This keeps scope evidence without
+        // issuing another transport probe per worker.
+        if let Some(agents) = state.get("agents").and_then(Value::as_object) {
+            for agent_id in agents.keys() {
+                let issue = format!("worker_window_missing:{agent_id}");
+                issues.push(json!(issue.clone()));
+                repairs.push(json!({
+                    "issue": issue,
+                    "action": "team-agent restart",
+                }));
+            }
+        }
         return (Value::Array(issues), Value::Array(repairs));
     }
 
@@ -289,6 +302,7 @@ pub(crate) fn diagnose_runtime_for_workspace(
     state: &Value,
     backend: &dyn Transport,
     selected_team_key: Option<&str>,
+    coordinator_health: &crate::coordinator::HealthReport,
 ) -> (Value, Value) {
     let (mut issues, mut repairs) = diagnose_runtime(state, backend);
     append_live_leader_workspace_mismatch_issue(
@@ -306,7 +320,7 @@ pub(crate) fn diagnose_runtime_for_workspace(
         &mut repairs,
     );
     append_legacy_snapshot_issue(workspace, state, &mut issues);
-    append_coordinator_health_issue(workspace, state, &mut issues, &mut repairs);
+    append_coordinator_health_issue(workspace, state, coordinator_health, &mut issues, &mut repairs);
     append_runtime_bindings_stale_after_boot_issue(workspace, state, &mut issues, &mut repairs);
     (issues, repairs)
 }
@@ -322,8 +336,27 @@ pub(crate) fn workspace_has_existing_team_runtime(
     workspace: &std::path::Path,
     team_key: &str,
 ) -> bool {
-    workspace.join("team.spec.yaml").is_file()
-        || crate::model::paths::runtime_spec_path(workspace, team_key).is_file()
+    // A source TEAM.md/team.spec.yaml is install/configuration context, not a
+    // live runtime.  Only persisted runtime state/specs make topology checks
+    // applicable; an empty workspace therefore remains a healthy no-runtime
+    // report instead of a fabricated missing-session issue.
+    if let Ok(state) = crate::state::persist::load_runtime_state_without_migrations(workspace) {
+        // The workspace's top-level view may describe a stopped sibling.
+        // Preserve the top-level fallback for legacy single-team state only
+        // when there is no selected team entry.
+        let team_state = state
+            .get("teams")
+            .and_then(|teams| teams.get(team_key))
+            .unwrap_or(&state);
+        let terminal = team_state
+            .get("status")
+            .and_then(Value::as_str)
+            .is_some_and(|status| matches!(status, "stopped" | "shutdown" | "archived" | "terminal"));
+        if terminal {
+            return false;
+        }
+    }
+    crate::model::paths::runtime_spec_path(workspace, team_key).is_file()
         || crate::state::persist::runtime_state_path(workspace).is_file()
 }
 
@@ -790,21 +823,18 @@ fn append_legacy_snapshot_issue(workspace: &std::path::Path, state: &Value, issu
 fn append_coordinator_health_issue(
     workspace: &std::path::Path,
     state: &Value,
+    health: &crate::coordinator::HealthReport,
     issues: &mut Value,
     repairs: &mut Value,
 ) {
-    // Diagnose must observe coordinator state without initializing or rewriting
-    // `.team/runtime/team.db`, including when the file is missing or empty.
-    let workspace = crate::coordinator::WorkspacePath::new(workspace.to_path_buf());
-    let health = crate::coordinator::coordinator_health_read_only(&workspace);
-    let Some(id) = coordinator_issue_id(state, &health) else {
+    let Some(id) = coordinator_issue_id(state, health) else {
         return;
     };
     if let Some(items) = issues.as_array_mut() {
-        items.push(coordinator_issue_value(id, &health, workspace.as_path()));
+        items.push(coordinator_issue_value(id, health, workspace));
     }
     if let Some(items) = repairs.as_array_mut() {
-        items.push(coordinator_repair_hint(id, &health));
+        items.push(coordinator_repair_hint(id, health));
     }
 }
 

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

@@ -174,7 +174,6 @@ fn dispatch(command: &str, args: &[String], cwd: &Path) -> Result<ExitCode, CliE
     match command {
         "init" => cmd_init(&init_args(args, cwd)).map(emit_result),
         "quick-start" => cmd_quick_start(&quick_start_args(args, cwd)?).map(emit_result),
-        "compile" => cmd_compile(&compile_args(args, cwd)?).map(emit_result),
         "send" => cmd_send(&send_args(args, cwd)?).map(emit_result),
         "allow-peer-talk" => {
             cmd_allow_peer_talk(&allow_peer_talk_args(args, cwd)?).map(emit_result)
@@ -225,7 +224,8 @@ fn dispatch(command: &str, args: &[String], cwd: &Path) -> Result<ExitCode, CliE
         "profile" => cmd_profile(&profile_args(args, cwd)?).map(emit_result),
         "results" => cmd_results(&results_args(args, cwd)?).map(emit_result),
         "wait" => cmd_wait(&wait_args(args, cwd)?).map(emit_result),
-        "diagnose" => cmd_diagnose(&diagnose_args(args, cwd)).map(emit_result),
+        // Compatibility spelling: parse and execute the exact doctor contract.
+        "diagnose" => cmd_doctor(&doctor_args(args, cwd)).map(emit_result),
         "preflight" => cmd_preflight(&preflight_args(args, cwd)).map(emit_result),
         "wait-ready" => cmd_wait_ready(&wait_ready_args(args, cwd)).map(emit_result),
         "e2e" => cmd_e2e(&e2e_args(args, cwd)).map(emit_result),
@@ -238,7 +238,6 @@ fn dispatch(command: &str, args: &[String], cwd: &Path) -> Result<ExitCode, CliE
 const DISPATCH_COMMANDS: &[&str] = &[
     "init",
     "quick-start",
-    "compile",
     "send",
     "allow-peer-talk",
     "status",
@@ -340,7 +339,7 @@ pub(crate) fn default_help() -> String {
             "reset-agent",
         ],
     );
-    append_help_section(&mut out, "Diagnose", &["diagnose"]);
+    append_help_section(&mut out, "Diagnose", &["doctor"]);
     append_help_section(
         &mut out,
         "Guided recovery",
@@ -400,7 +399,6 @@ fn command_help(command: Option<&str>) -> String {
         Some("init") => compat_hidden_help("init", "usage: team-agent init [--workspace WORKSPACE] [--force] [--json]"),
         Some("quick-start") => "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--no-display] [--backend tmux|conpty] [--json] [--detail]\n\ndefaults: display_backend=adaptive; set display_backend: none in TEAM.md or pass --no-display to use one worker window per agent.\n\n--backend selects the worker transport (Phase 1d Batch 2): tmux (default on POSIX; unchanged behavior), conpty (Windows-native ConPTY worker transport; requires the shim binary and Windows host).\n\n--detail includes internal receiver/topology diagnostics in JSON output.\n\nAfter a successful start, use the returned `send_commands` (or choose an agent explicitly) with `team-agent send AGENT MESSAGE`.".to_string(),
         Some("start") => compat_hidden_help("start", "usage: team-agent start [TEAMDIR] [--yes] [--fresh] [--json]"),
-        Some("compile") => "usage: team-agent compile --team TEAM [--out FILE] [--json]".to_string(),
         Some("send") => concat!(
             "usage: team-agent send TO MESSAGE... ",
             "[--workspace WORKSPACE] [--team TEAM] ",
@@ -444,7 +442,7 @@ fn command_help(command: Option<&str>) -> String {
         Some("profile") => "usage: team-agent profile COMMAND NAME [--workspace WORKSPACE] [--team TEAM] [--auth-mode MODE] [--proxy-mode direct|inherit] [--json]".to_string(),
         Some("results") => "usage: team-agent results --case CASE_ID [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
         Some("wait") => "usage: team-agent wait --task TASK [--workspace WORKSPACE] [--json]".to_string(),
-        Some("diagnose") => "usage: team-agent diagnose [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
+        Some("diagnose") => "usage: team-agent doctor [SPEC] [--workspace WORKSPACE] [--team TEAM] [--gate orphans|comms] [--comms] [--fix] [--fix-schema] [--cleanup-orphans] [--confirm] [--json]".to_string(),
         Some("preflight") => "usage: team-agent preflight [TEAMDIR] [--json]".to_string(),
         Some("wait-ready") => "usage: team-agent wait-ready [--workspace WORKSPACE] [--team TEAM] [--timeout SECONDS] [--json]".to_string(),
         Some("e2e") => "usage: team-agent e2e [--workspace WORKSPACE] [--providers LIST] [--real] [--json]".to_string(),
@@ -852,7 +850,6 @@ struct ParsedArgs {
     result: Option<String>,
     real: bool,
     assignee: Option<String>,
-    out: Option<PathBuf>,
     auth_mode: Option<String>,
     proxy_mode: Option<String>,
     pane: Option<String>,
@@ -949,7 +946,6 @@ fn parse_args(args: &[String]) -> ParsedArgs {
             "--result" => parsed.result = next_arg(args, &mut i),
             "--real" => parsed.real = true,
             "--assignee" => parsed.assignee = next_arg(args, &mut i),
-            "--out" => parsed.out = next_arg(args, &mut i).map(PathBuf::from),
             "--auth-mode" => parsed.auth_mode = next_arg(args, &mut i),
             "--proxy-mode" => parsed.proxy_mode = next_arg(args, &mut i),
             "--pane" => parsed.pane = next_arg(args, &mut i),
@@ -1144,23 +1140,6 @@ fn init_args(args: &[String], cwd: &Path) -> InitArgs {
     }
 }
 
-fn compile_args(args: &[String], cwd: &Path) -> Result<CompileArgs, CliError> {
-    let parsed = parse_args(args);
-    let team = parsed
-        .team
-        .as_deref()
-        .map(PathBuf::from)
-        .ok_or_else(|| CliError::Usage("missing --team".to_string()))?;
-    let out = parsed
-        .out
-        .unwrap_or_else(|| PathBuf::from("team.spec.yaml"));
-    Ok(CompileArgs {
-        team: resolve_cli_path(cwd, &team),
-        out: resolve_cli_path(cwd, &out),
-        json: parsed.json,
-    })
-}
-
 fn resolve_cli_path(cwd: &Path, path: &Path) -> PathBuf {
     if path.is_absolute() {
         path.to_path_buf()
@@ -2172,7 +2151,8 @@ mod tests {
     fn hidden_commands_not_in_default_help() {
         let top_help = command_help(None);
         let visible = visible_help_commands(&top_help);
-        for command in ["leaders", "doctor", "e2e", "peek", "coordinator"] {
+        assert!(visible.iter().any(|command| command == "doctor"));
+        for command in ["leaders", "diagnose", "e2e", "peek", "coordinator"] {
             assert!(
                 !visible.iter().any(|visible| visible == command),
                 "`{command}` must stay hidden from default help"

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

@@ -516,10 +516,11 @@ pub mod lifecycle_port {
     /// (经同一帧 list_targets pane→session)。state 无任何锚 → 退命名判据 + spare_fallback event。
     fn anchor_sessions_from_state(
         state: &Value,
+        endpoint: Option<&str>,
         pane_targets: &[crate::transport::PaneInfo],
         event_log: &crate::event_log::EventLog,
     ) -> std::collections::BTreeSet<String> {
-        let anchor_pane_ids = collect_state_leader_anchor_pane_ids(state);
+        let anchor_pane_ids = collect_state_leader_anchor_pane_ids(state, endpoint);
         if anchor_pane_ids.is_empty() {
             // 无锚(state 损坏/未记)→ 退纯命名前缀判据(下游 sessions_to_kill 仍 spare 前缀)。
             let _ = event_log.write(
@@ -649,7 +650,12 @@ pub mod lifecycle_port {
                 }
             }
         };
-        let protected_sessions = anchor_sessions_from_state(state, &targets, event_log);
+        let protected_sessions = anchor_sessions_from_state(
+            state,
+            transport.tmux_endpoint().as_deref(),
+            &targets,
+            event_log,
+        );
         let mut result = ShutdownSocketCleanup::default();
         for session in candidates {
             if protected_sessions.contains(session.as_str()) {
@@ -791,6 +797,43 @@ pub mod lifecycle_port {
         use crate::transport::test_support::OfflineTransport;
         use crate::transport::{PaneId, PaneInfo, SessionName};
 
+        #[test]
+        fn leader_process_protection_does_not_alias_panes_across_endpoints() {
+            let state = json!({
+                "team_owner": {"pane_id": "%2"},
+                "leader_receiver": {"pane_id": "%2", "tmux_socket": "/tmp/s4-host-only.sock"}
+            });
+            let table = [(10, 1), (20, 10), (30, 10), (31, 30)]
+                .into_iter()
+                .map(|(pid, ppid)| ProcessInfo { pid, ppid, pgid: None, session: None, command: String::new() })
+                .collect::<Vec<_>>();
+            for (endpoint, pane_pid, should_protect) in [
+                ("/tmp/s4-worker-only.sock", 20, false),
+                ("/tmp/s4-host-only.sock", 30, true),
+            ] {
+                let transport = OfflineTransport::new()
+                    .with_tmux_endpoint(endpoint)
+                    .with_targets(vec![PaneInfo {
+                        pane_id: PaneId::new("%2"),
+                        session: SessionName::new("ordinary-session"),
+                        window_index: None,
+                        window_name: None,
+                        pane_index: None,
+                        tty: None,
+                        current_command: None,
+                        current_path: None,
+                        active: true,
+                        pane_pid: Some(pane_pid),
+                        leader_env: BTreeMap::new(),
+                    }]);
+                let mut protected = ShutdownProtection::default();
+                extend_protection_with_leader_panes(&mut protected, &transport, &state, &table);
+                assert_eq!(protected.pids.contains(&pane_pid), should_protect);
+                assert_eq!(protected.pids.contains(&31), should_protect, "leader descendants");
+                assert_eq!(protected.pids.contains(&10), should_protect, "leader's server");
+            }
+        }
+
         #[test]
         fn audit_write_failure_skips_destructive_kill() {
             let root =
@@ -1042,7 +1085,10 @@ pub mod lifecycle_port {
             // External and managed leaders both pass the same positive ownership
             // gate; topology only decides whether a verified session is reduced
             // to worker panes or removed as a whole.
-            let leader_anchor_ids = collect_state_leader_anchor_pane_ids(&state);
+            let leader_anchor_ids = collect_state_leader_anchor_pane_ids(
+                &state,
+                transport.tmux_endpoint().as_deref(),
+            );
             let (live_targets_now, live_targets_known) = match transport.list_targets() {
                 Ok(targets) => (targets, true),
                 Err(error) => {
@@ -2059,12 +2105,13 @@ pub mod lifecycle_port {
     ///   → 任一 team 的 shutdown 都不杀任何 team 的 leader 锚 pane
     pub fn collect_state_leader_anchor_pane_ids(
         state: &Value,
+        endpoint: Option<&str>,
     ) -> std::collections::BTreeSet<String> {
         let mut out = std::collections::BTreeSet::new();
-        push_anchor_pane_id(state, &mut out);
+        push_anchor_pane_id(state, endpoint, &mut out);
         if let Some(teams) = state.get("teams").and_then(Value::as_object) {
             for (_, team_state) in teams {
-                push_anchor_pane_id(team_state, &mut out);
+                push_anchor_pane_id(team_state, endpoint, &mut out);
             }
         }
         out
@@ -2184,17 +2231,40 @@ pub mod lifecycle_port {
         Ok(())
     }
 
-    /// 单帧扫 team_owner.pane_id + leader_receiver.pane_id → BTreeSet 累加。
-    fn push_anchor_pane_id(state: &Value, out: &mut std::collections::BTreeSet<String>) {
-        for key in &["team_owner", "leader_receiver"] {
-            if let Some(pane_id) = state
-                .get(*key)
-                .and_then(|v| v.get("pane_id"))
-                .and_then(Value::as_str)
+    /// Pane IDs are server-local. Exclude proven foreign-endpoint anchors, but
+    /// retain legacy anchors when their endpoint (or the transport's) is unknown.
+    fn push_anchor_pane_id(
+        state: &Value,
+        endpoint: Option<&str>,
+        out: &mut std::collections::BTreeSet<String>,
+    ) {
+        for (key, peer_key) in [("team_owner", "leader_receiver"), ("leader_receiver", "team_owner")] {
+            let Some(anchor) = state.get(key) else { continue };
+            let Some(pane_id) = anchor.get("pane_id").and_then(Value::as_str).filter(|s| !s.is_empty()) else {
+                continue;
+            };
+            // team_owner often records only a pane ID; its receiver supplies
+            // the endpoint only when it describes that exact same anchor.
+            let anchor_endpoint = anchor.get("tmux_socket").and_then(Value::as_str)
                 .filter(|s| !s.is_empty())
-            {
-                out.insert(pane_id.to_string());
+                .or_else(|| {
+                    state.get(peer_key)
+                        .filter(|peer| peer.get("pane_id").and_then(Value::as_str) == Some(pane_id))
+                        .and_then(|peer| peer.get("tmux_socket"))
+                        .and_then(Value::as_str)
+                        .filter(|s| !s.is_empty())
+                });
+            if let (Some(anchor_path), Some(transport_path)) = (
+                anchor_endpoint.and_then(socket_file_for_endpoint),
+                endpoint.filter(|s| !s.is_empty()).and_then(socket_file_for_endpoint),
+            ) {
+                let anchor_path = anchor_path.canonicalize().unwrap_or(anchor_path);
+                let transport_path = transport_path.canonicalize().unwrap_or(transport_path);
+                if anchor_path != transport_path {
+                    continue;
+                }
             }
+            out.insert(pane_id.to_string());
         }
     }
 
@@ -2305,8 +2375,10 @@ pub mod lifecycle_port {
         );
         // Source 2: state.json team_owner / leader_receiver 真锚 pane_id(top-level +
         // teams[*]),per-workspace socket 命中。
-        let anchor_pane_ids: std::collections::BTreeSet<String> =
-            collect_state_leader_anchor_pane_ids(state);
+        let anchor_pane_ids = collect_state_leader_anchor_pane_ids(
+            state,
+            transport.tmux_endpoint().as_deref(),
+        );
         leader_pane_pids.extend(
             pane_targets
                 .iter()
@@ -2322,6 +2394,7 @@ pub mod lifecycle_port {
         // 的 list_targets 找 anchor pane_id → pane_pid → 进入 process_tree 保护。
         // 不在 state 中的 socket 不查(MUST-17 不撒宽 / 不主动枚举全机器 sockets)。
         for socket_endpoint in collect_state_recorded_tmux_sockets(state) {
+            let anchor_pane_ids = collect_state_leader_anchor_pane_ids(state, Some(&socket_endpoint));
             let cross_backend =
                 crate::tmux_backend::TmuxBackend::for_tmux_endpoint(&socket_endpoint);
             let cross_panes =
@@ -4752,17 +4825,15 @@ pub mod diagnose_port {
             && profile_smoke_value.get("status").and_then(Value::as_str)
                 == Some("legacy_team_invalid");
         let effective_smoke_ok = profile_smoke_ok || legacy_only_failure;
+        // Coordinator and runtime topology are facts of the unified pipeline,
+        // not of the static environment probe.  The caller supplies the
+        // selected runtime workspace and performs one read-only health read.
         let ok = workspace_valid && (team_context || workspace_has_entries) && effective_smoke_ok;
-        let health = crate::coordinator::coordinator_health(
-            &crate::coordinator::WorkspacePath::new(workspace.to_path_buf()),
-        );
-        let coordinator_ok = health.ok;
-        let coordinator_error = health.metadata_mismatch_reason.clone();
         let state = crate::state::persist::load_runtime_state(workspace).unwrap_or(Value::Null);
         let grok_slot = crate::cli::grok_slot_report(workspace, &state).to_json();
         let grok_slot_ok = grok_slot.get("consistent").and_then(Value::as_bool) == Some(true)
             && grok_slot.get("readable").and_then(Value::as_bool) == Some(true);
-        let ok = ok && grok_slot_ok && coordinator_ok;
+        let ok = ok && grok_slot_ok;
         Ok(json!({
             "tmux": {
                 "installed": tmux_installed,
@@ -4770,14 +4841,14 @@ pub mod diagnose_port {
             },
             "workspace": workspace.to_string_lossy().to_string(),
             "workspace_is_git_repo": workspace.join(".git").exists(),
-            "providers": {},
+            "providers": crate::cli::diagnose::provider_doctor_checks(),
             "mcp": {
                 "server_command": which_path("team_orchestrator"),
                 "local_module": true,
             },
             "secret_scan": secret_scan(workspace),
             "profile_smoke": profile_smoke_value,
-            "coordinator": coordinator_health_value(health),
+            "coordinator": coordinator_not_required_value(),
             "grok_slot": grok_slot,
             "ok": ok,
             "error": if ok {
@@ -4789,10 +4860,6 @@ pub mod diagnose_port {
                     .unwrap_or_else(|| json!("grok_slot_mismatch"))
             } else if !profile_smoke_ok && !legacy_only_failure {
                 json!("profile_smoke_failed")
-            } else if !coordinator_ok {
-                coordinator_error
-                    .map(Value::String)
-                    .unwrap_or_else(|| json!("coordinator_unavailable"))
             } else if workspace_valid {
                 json!("workspace has no Team Agent spec or runtime context")
             } else {
@@ -4984,11 +5051,12 @@ pub mod diagnose_port {
                 continue;
             };
             let rel = path.strip_prefix(root).unwrap_or(path);
+            // Keep only a locating rule/path/line tuple.  Never include even
+            // redacted assignment text in the structured report.
             findings.push(json!({
                 "path": rel.to_string_lossy().to_string(),
                 "line": idx.saturating_add(1),
                 "rule": "api_key_assignment",
-                "match_excerpt": format!("{key}=<redacted>"),
             }));
         }
     }
@@ -5153,7 +5221,23 @@ pub mod diagnose_port {
         })
     }
 
-    fn coordinator_health_value(health: crate::coordinator::HealthReport) -> Value {
+    pub(crate) fn coordinator_not_required_value() -> Value {
+        json!({
+            "ok": true,
+            "status": "not_required",
+            "pid": Value::Null,
+            "metadata": Value::Null,
+            "metadata_ok": true,
+            "metadata_mismatch_reason": Value::Null,
+            "binary_path": Value::Null,
+            "binary_version": Value::Null,
+            "schema_ok": true,
+            "schema_error": Value::Null,
+            "schema": {"message_store_schema_version": Value::Null},
+        })
+    }
+
+    pub(crate) fn coordinator_health_value(health: crate::coordinator::HealthReport) -> Value {
         let expose_binary_drift = health.service_available && !health.metadata_ok;
         let binary_identity_relation = health.binary_identity_relation.as_str();
         let mut value = json!({

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

@@ -44,7 +44,6 @@ pub(crate) enum TokenUsage {
 pub(crate) enum DispatchKind {
     Init,
     QuickStart,
-    Compile,
     Send,
     AllowPeerTalk,
     Status,
@@ -90,7 +89,6 @@ pub(crate) enum DispatchKind {
 pub(crate) const ALL_DISPATCH_KINDS: &[DispatchKind] = &[
     DispatchKind::Init,
     DispatchKind::QuickStart,
-    DispatchKind::Compile,
     DispatchKind::Send,
     DispatchKind::AllowPeerTalk,
     DispatchKind::Status,
@@ -176,7 +174,7 @@ pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
     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] [--no-display] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, 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, alias_of: None, 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] [--no-display] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
-    CommandSpec { name: "diagnose", tier: CommandTier::Core, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Diagnose), summary: "inspect this workspace runtime and suggested repairs", usage: "usage: team-agent diagnose [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "diagnose", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::Diagnose), summary: "compatibility alias for doctor", usage: "usage: team-agent doctor [SPEC] [--workspace WORKSPACE] [--team TEAM] [--gate orphans|comms] [--comms] [--fix] [--fix-schema] [--cleanup-orphans] [--confirm] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: Some("doctor"), 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 diagnose 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, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "takeover", tier: CommandTier::Guided, category: CommandCategory::GuidedRecovery, kind: CommandKind::Dispatch(DispatchKind::Takeover), summary: "replace a live leader binding with explicit consent", usage: "usage: team-agent takeover [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "attach-leader", tier: CommandTier::Guided, category: CommandCategory::GuidedRecovery, kind: CommandKind::Dispatch(DispatchKind::AttachLeader), summary: "bind an external leader pane", usage: "usage: team-agent attach-leader [--workspace WORKSPACE] [--team TEAM] [--pane PANE] [--provider PROVIDER] [--confirm] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
@@ -196,7 +194,7 @@ pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
     CommandSpec { name: "stuck-cancel", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::StuckCancel), summary: "legacy stuck alert suppression", usage: "usage: team-agent stuck-cancel AGENT [--workspace WORKSPACE] [--alert-type stuck|idle_fallback|cross_worker_deadlock|all] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: Some("C2"), action: Some("use the concrete notification action or `team-agent diagnose`"), governance: None },
     CommandSpec { name: "acknowledge-idle", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::AcknowledgeIdle), summary: "legacy idle acknowledgement", usage: "usage: team-agent acknowledge-idle [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: Some("C2"), action: Some("use the concrete idle notification action or `team-agent diagnose`"), governance: None },
     CommandSpec { name: "leaders", tier: CommandTier::Secondary, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Leaders), summary: "list live, stale, or ambiguous host leaders", usage: "usage: team-agent leaders [QUERY|--search TEXT] [--all|--stale] [--json] | --prune [--dry-run] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
-    CommandSpec { name: "doctor", tier: CommandTier::Secondary, category: CommandCategory::Setup, kind: CommandKind::Dispatch(DispatchKind::Doctor), summary: "run host maintenance checks", usage: "usage: team-agent doctor [SPEC] [--workspace WORKSPACE] [--team TEAM] [--gate orphans|comms] [--comms] [--fix] [--fix-schema] [--cleanup-orphans] [--confirm] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "doctor", tier: CommandTier::Core, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Doctor), summary: "inspect environment and Team runtime health", usage: "usage: team-agent doctor [SPEC] [--workspace WORKSPACE] [--team TEAM] [--gate orphans|comms] [--comms] [--fix] [--fix-schema] [--cleanup-orphans] [--confirm] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "attach-app-server-leader", tier: CommandTier::Guided, category: CommandCategory::GuidedRecovery, kind: CommandKind::Dispatch(DispatchKind::AttachAppServerLeader), summary: "bind an app-server leader receiver", usage: "usage: team-agent attach-app-server-leader [--workspace WORKSPACE] [--team TEAM] --socket unix:///path.sock --thread-id THREAD_ID [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "remove-agent", tier: CommandTier::Secondary, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::RemoveAgent), summary: "remove a worker", usage: "usage: team-agent remove-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--from-spec] [--confirm] [--force] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "fork-agent", tier: CommandTier::Secondary, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::ForkAgent), summary: "fork a worker", usage: "usage: team-agent fork-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
@@ -210,7 +208,6 @@ pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
     CommandSpec { name: "identity", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Identity), summary: "inspect identity metadata", usage: "usage: team-agent identity [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "watch", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Watch), summary: "watch event logs", usage: "usage: team-agent watch [--workspace WORKSPACE] [--team TEAM]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "sessions", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Sessions), summary: "inspect session inventory", usage: "usage: team-agent sessions [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
-    CommandSpec { name: "compile", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Compile), summary: "compile a team spec", usage: "usage: team-agent compile --team TEAM [--out FILE] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "validate", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Validate), summary: "validate a team spec", usage: "usage: team-agent validate [SPEC] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "preflight", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Preflight), summary: "run preflight checks", usage: "usage: team-agent preflight [TEAMDIR] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "wait-ready", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::WaitReady), summary: "wait for runtime readiness", usage: "usage: team-agent wait-ready [--workspace WORKSPACE] [--team TEAM] [--timeout SECONDS] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },

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

@@ -671,13 +671,12 @@ fn exit_code_numeric() {
 }
 
 // =========================================================================
-// cmd_doctor 分派(commands.py:218-260):--fix 缺 gate -> Usage err
+// cmd_doctor: --fix without --gate is a structured failure in both renderers.
 // =========================================================================
 
 #[test]
-fn cmd_doctor_fix_without_gate_is_usage_error() {
-    // commands.py:220-221: --fix and not gate -> TeamAgentError("--fix requires --gate")
-    let args = DoctorArgs {
+fn cmd_doctor_fix_without_gate_reports_usage_failure() {
+    let mut args = DoctorArgs {
         spec: None,
         workspace: PathBuf::from("."),
         gate: None,
@@ -689,12 +688,23 @@ fn cmd_doctor_fix_without_gate_is_usage_error() {
         confirm: false,
         json: false,
     };
-    let err = cmd_doctor(&args).unwrap_err();
-    let msg = err.to_string();
-    assert!(
-        msg.contains("--fix requires --gate"),
-        "expected '--fix requires --gate', got: {msg}"
-    );
+    let human = cmd_doctor(&args).expect("structured usage failure");
+    assert_eq!(human.exit, ExitCode::Error);
+    let CmdOutput::Human(text) = human.output else {
+        panic!("expected human triage");
+    };
+    assert!(text.contains("fix_requires_gate"), "{text}");
+    assert!(text.contains("add --gate orphans|comms"), "{text}");
+
+    args.json = true;
+    let result = cmd_doctor(&args).expect("structured JSON usage failure");
+    assert_eq!(result.exit, ExitCode::Error);
+    let CmdOutput::Json(value) = result.output else {
+        panic!("expected JSON usage failure");
+    };
+    assert_eq!(value["ok"], false);
+    assert_eq!(value["error"], "--fix requires --gate");
+    assert_eq!(value["issues"], json!(["fix_requires_gate"]));
 }
 
 // =========================================================================

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

@@ -457,14 +457,10 @@ fn red_send_target_none_is_not_broadcast() {
     assert_eq!(send_target(None, Some("*")), MessageTarget::Broadcast);
 }
 
-// ---- #23: cmd_doctor comms (human) returns COMMS_BOUNDARY_TEXT + sorted indented JSON ----
-// golden: for --comms WITHOUT --json, cmd_doctor returns the STRING
-//   f"{COMMS_BOUNDARY_TEXT}\n{json.dumps(result, indent=2, ensure_ascii=False, sort_keys=True)}".
-// Rust always does CmdResult::from_json -> CmdOutput::Json (wrong shape).
+// Unified doctor human output is triage only, including the comms gate.
 #[test]
-fn red_cmd_doctor_comms_human_is_boundary_text_plus_sorted_json() {
-    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)";
-    let args = DoctorArgs {
+fn cmd_doctor_comms_human_is_compact_triage_without_boundary_prefix() {
+    let mut args = DoctorArgs {
         spec: None,
         workspace: PathBuf::from("."),
         gate: None,
@@ -479,21 +475,16 @@ fn red_cmd_doctor_comms_human_is_boundary_text_plus_sorted_json() {
     let result = cmd_doctor(&args).expect("comms doctor returns CmdResult");
     let text = match result.output {
         CmdOutput::Human(s) => s,
-        other => panic!(
-            "comms WITHOUT --json MUST be a Human boundary-text + JSON string, got {other:?}"
-        ),
+        other => panic!("comms WITHOUT --json must be human triage, got {other:?}"),
     };
-    assert!(
-            text.starts_with(&format!("{COMMS_BOUNDARY_TEXT}\n")),
-            "comms human output MUST start with COMMS_BOUNDARY_TEXT then a newline (golden commands.py:231); got: {text:?}"
-        );
-    // the tail is the selftest result rendered as sort_keys+indent=2 JSON (parseable, sorted).
-    let json_tail = text
-        .strip_prefix(&format!("{COMMS_BOUNDARY_TEXT}\n"))
-        .unwrap();
-    let parsed: Value = serde_json::from_str(json_tail)
-        .expect("comms human tail MUST be indent=2 sort_keys JSON of the selftest result");
-    assert!(parsed.is_object(), "comms selftest JSON tail is an object");
+    args.json = true;
+    let CmdOutput::Json(report) = cmd_doctor(&args).unwrap().output else {
+        panic!("--json must preserve the structured report");
+    };
+    assert_eq!(text, crate::cli::triage::render("doctor", &report));
+    assert!(text.starts_with("doctor:"));
+    assert_eq!(text.lines().count(), 1 + report["issues"].as_array().unwrap().len()
+        + report["suggested_repairs"].as_array().unwrap().len());
 }
 
 // ---- #13 / #27 (P2): run() must NOT treat 'claude_code' as a passthrough trigger ----

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

@@ -368,12 +368,17 @@ fn ux_doctor_secret_scan_findings_name_the_exact_trigger() {
         .pointer("/secret_scan/findings/0")
         .and_then(serde_json::Value::as_object)
         .expect("secret-scan must report the concrete trigger");
-    for key in ["path", "line", "rule", "match_excerpt"] {
+    for key in ["path", "line", "rule"] {
         assert!(
             finding.contains_key(key),
             "secret-scan finding missing `{key}`: {finding:?}"
         );
     }
+    assert_eq!(finding["path"], "leaky-role.md");
+    assert_eq!(finding["line"], 1);
+    assert_eq!(finding["rule"], "api_key_assignment");
+    assert!(!finding.contains_key("match_excerpt"));
+    assert!(!value.to_string().contains("sk-test-red-contract"));
     let _ = std::fs::remove_dir_all(&ws);
 }
 #[test]