@team-agent/installer 0.5.75 → 0.5.78

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

@@ -103,6 +103,21 @@ pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value
         issues.push(issue);
     }
 
+    if state
+        .get("leader_receiver")
+        .is_some_and(receiver_has_empty_attached_pane)
+    {
+        issues.push(json!(LEADER_NOT_ATTACHED));
+        repairs.push(recovery_hint(
+            state
+                .get("session_name")
+                .and_then(Value::as_str)
+                .unwrap_or("unknown"),
+            LEADER_NOT_ATTACHED,
+            LEADER_NOT_ATTACHED_REPAIR,
+        ));
+    }
+
     if let Some(session_name) = state
         .get("session_name")
         .and_then(Value::as_str)
@@ -140,17 +155,7 @@ pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value
         }
     }
 
-    if !leader_receiver_attached(state) {
-        issues.push(json!("leader_not_attached"));
-        repairs.push(recovery_hint(
-            state
-                .get("session_name")
-                .and_then(Value::as_str)
-                .unwrap_or("unknown"),
-            "leader_not_attached",
-            "team-agent attach-leader",
-        ));
-    } else {
+    if leader_receiver_attached(state) {
         // 0.4.x (CR R2 P0): leader provider health reconciliation. The
         // leader_receiver may be marked `attached` (pane addressable) but the
         // provider process has exited — pane fell back to shell with the exit
@@ -186,7 +191,7 @@ pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value
                             .and_then(Value::as_str)
                             .unwrap_or("unknown"),
                         "leader_provider_unreachable",
-                        "team-agent claim-leader",
+                        "leader pane provider is unreachable; restart the provider in the bound pane",
                     ));
                 }
                 crate::leader::LeaderProviderHealth::Alive => {}
@@ -267,6 +272,7 @@ pub(crate) fn diagnose_runtime_for_workspace(
     workspace: &std::path::Path,
     state: &Value,
     backend: &dyn Transport,
+    selected_team_key: Option<&str>,
 ) -> (Value, Value) {
     let (mut issues, mut repairs) = diagnose_runtime(state, backend);
     append_live_leader_workspace_mismatch_issue(
@@ -276,43 +282,159 @@ pub(crate) fn diagnose_runtime_for_workspace(
         &mut issues,
         &mut repairs,
     );
-    append_registry_channel_unbound_issue(workspace, state, &mut issues, &mut repairs);
+    append_registry_channel_unbound_issue(
+        workspace,
+        state,
+        selected_team_key,
+        &mut issues,
+        &mut repairs,
+    );
     append_legacy_snapshot_issue(workspace, state, &mut issues);
     append_coordinator_health_issue(workspace, state, &mut issues, &mut repairs);
     append_runtime_bindings_stale_after_boot_issue(workspace, state, &mut issues, &mut repairs);
     (issues, repairs)
 }
 
-fn append_registry_channel_unbound_issue(
+const TEAM_SPEC_OR_RUNTIME_MISSING: &str = "team_spec_or_runtime_missing";
+const TEAM_SPEC_OR_RUNTIME_MISSING_REPAIR: &str = concat!(
+    "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`.",
+);
+
+pub(crate) fn workspace_has_existing_team_runtime(
     workspace: &std::path::Path,
-    state: &Value,
+    team_key: &str,
+) -> bool {
+    workspace.join("team.spec.yaml").is_file()
+        || crate::model::paths::runtime_spec_path(workspace, team_key).is_file()
+        || crate::state::persist::runtime_state_path(workspace).is_file()
+}
+
+pub(crate) fn missing_team_runtime_issues_and_repairs(team_key: &str) -> (Value, Value) {
+    let mut issues = json!([]);
+    let mut repairs = json!([]);
+    push_issue_repair(
+        &mut issues,
+        &mut repairs,
+        team_key,
+        TEAM_SPEC_OR_RUNTIME_MISSING,
+        TEAM_SPEC_OR_RUNTIME_MISSING_REPAIR,
+    );
+    (issues, repairs)
+}
+
+fn push_issue_repair(
     issues: &mut Value,
     repairs: &mut Value,
+    team: &str,
+    issue_id: &str,
+    repair: &str,
 ) {
-    let team_key = crate::state::projection::team_state_key(state);
-    if team_key.is_empty()
-        || crate::lifecycle::launch::launched_team_receiver_is_attached(workspace, &team_key)
-    {
-        return;
-    }
     if let Some(items) = issues.as_array_mut() {
         if !items.iter().any(|item| {
-            item.as_str() == Some("leader_not_attached")
-                || item.get("id").and_then(Value::as_str) == Some("leader_channel_unbound")
+            item.as_str() == Some(issue_id)
+                || item.get("id").and_then(Value::as_str) == Some(issue_id)
         }) {
-            items.push(json!("leader_not_attached"));
+            items.push(json!(issue_id));
         }
     }
     if let Some(items) = repairs.as_array_mut() {
-        items.push(recovery_hint(
-            state
-                .get("session_name")
-                .and_then(Value::as_str)
-                .unwrap_or(team_key.as_str()),
-            "leader_not_attached",
-            "team-agent claim-leader",
-        ));
+        items.push(recovery_hint(team, issue_id, repair));
+    }
+}
+
+fn append_registry_channel_unbound_issue(
+    workspace: &std::path::Path,
+    state: &Value,
+    selected_team_key: Option<&str>,
+    issues: &mut Value,
+    repairs: &mut Value,
+) {
+    let team_key = selected_team_key
+        .filter(|team| !team.is_empty())
+        .map(str::to_string)
+        .unwrap_or_else(|| crate::state::projection::team_state_key(state));
+    if team_key.is_empty() {
+        return;
+    }
+    // RuntimeOnly diagnose synthesizes team_key=current from empty default
+    // state. That is not an existing unbound team; do not emit claim.
+    if !workspace_has_existing_team_runtime(workspace, &team_key) {
+        push_issue_repair(
+            issues,
+            repairs,
+            &team_key,
+            TEAM_SPEC_OR_RUNTIME_MISSING,
+            TEAM_SPEC_OR_RUNTIME_MISSING_REPAIR,
+        );
+        return;
+    }
+    let class = crate::lifecycle::launch::classify_leader_binding(workspace, &team_key);
+    if class == crate::lifecycle::launch::LeaderBindingClass::Attached {
+        return;
+    }
+    let (issue_id, repair) = existing_team_binding_issue(state, &team_key, class);
+    push_issue_repair(
+        issues,
+        repairs,
+        state
+            .get("session_name")
+            .and_then(Value::as_str)
+            .unwrap_or(team_key.as_str()),
+        issue_id,
+        repair,
+    );
+}
+
+const LEADER_NOT_ATTACHED: &str = "leader_not_attached";
+const LEADER_NOT_ATTACHED_REPAIR: &str =
+    "run from the intended leader tmux pane; do not run claim-leader";
+
+fn receiver_has_empty_attached_pane(receiver: &Value) -> bool {
+    receiver.get("status").and_then(Value::as_str) == Some("attached")
+        && receiver
+            .get("pane_id")
+            .and_then(Value::as_str)
+            .is_none_or(|pane| pane.is_empty())
+}
+
+fn selected_or_top_receiver<'a>(state: &'a Value, team_key: &str) -> Option<&'a Value> {
+    crate::lifecycle::launch::selected_team_leader_receiver(state, team_key)
+        .or_else(|| state.get("leader_receiver"))
+}
+
+fn team_has_initialized_runtime(state: &Value, team_key: &str) -> bool {
+    let team = state
+        .get("teams")
+        .and_then(Value::as_object)
+        .and_then(|teams| teams.get(team_key))
+        .unwrap_or(state);
+    let has_agents = team
+        .get("agents")
+        .and_then(Value::as_object)
+        .is_some_and(|agents| !agents.is_empty())
+        || state
+            .get("agents")
+            .and_then(Value::as_object)
+            .is_some_and(|agents| !agents.is_empty());
+    let has_owner = team.get("team_owner").is_some() || state.get("team_owner").is_some();
+    let has_receiver = selected_or_top_receiver(state, team_key).is_some();
+    has_agents || has_owner || has_receiver
+}
+
+fn existing_team_binding_issue(
+    state: &Value,
+    team_key: &str,
+    class: crate::lifecycle::launch::LeaderBindingClass,
+) -> (&'static str, &'static str) {
+    if selected_or_top_receiver(state, team_key).is_some_and(receiver_has_empty_attached_pane)
+        || (class == crate::lifecycle::launch::LeaderBindingClass::Unbound
+            && team_has_initialized_runtime(state, team_key))
+    {
+        return (LEADER_NOT_ATTACHED, LEADER_NOT_ATTACHED_REPAIR);
     }
+    (class.issue_id(), class.repair())
 }
 
 fn append_live_leader_workspace_mismatch_issue(
@@ -353,8 +475,7 @@ fn live_leader_workspace_mismatch(
     let provider = receiver
         .get("provider")
         .and_then(Value::as_str)
-        .filter(|provider| !provider.is_empty())
-        .unwrap_or("claude");
+        .filter(|provider| !provider.is_empty());
     let refusal =
         PaneAuthorityRefusal::new(PaneAuthorityRefusalFacts::PaneWorkspaceMismatch(facts));
     let PaneAuthorityRefusalFacts::PaneWorkspaceMismatch(facts) = &refusal.facts else {
@@ -413,7 +534,9 @@ fn live_leader_workspace_mismatch(
             HINT_ACTION_FIELD.to_string(),
             Value::String(
                 match refusal.recovery.hint_action {
-                    PaneAuthorityRecoveryHint::AttachLeader => "team-agent attach-leader",
+                    PaneAuthorityRecoveryHint::AttachLeader => {
+                        "open a matching workspace pane bound for this workspace"
+                    }
                 }
                 .to_string(),
             ),
@@ -424,15 +547,19 @@ fn live_leader_workspace_mismatch(
         );
         object.insert(
             ACTION_FIELD.to_string(),
-            Value::String(match refusal.recovery.action {
-                PaneAuthorityRecoveryAction::OpenTerminalOutsideCurrentTmuxPaneOrAttachFromMatchingPane => {
-                    format!(
-                        "open a new terminal window outside the current tmux/pane, change \
-                         directory to the requested workspace, then run \
-                         `team-agent attach-leader --team {team} --provider {provider} \
-                         --confirm --json`; then rerun \
-                         `team-agent diagnose --team {team} --json`"
-                    )
+            Value::String(match (refusal.recovery.action, provider) {
+                (
+                    PaneAuthorityRecoveryAction::OpenTerminalOutsideCurrentTmuxPaneOrAttachFromMatchingPane,
+                    Some(provider),
+                ) => format!(
+                    "open a matching workspace pane already bound as {provider}"
+                ),
+                (
+                    PaneAuthorityRecoveryAction::OpenTerminalOutsideCurrentTmuxPaneOrAttachFromMatchingPane,
+                    None,
+                ) => {
+                    "open a matching workspace pane with the recorded leader provider; do not default claude"
+                        .to_string()
                 }
             }),
         );
@@ -454,9 +581,7 @@ pub(crate) fn append_registry_channel_unbound_to_report(
                 .map(|state| crate::state::projection::team_state_key(&state))
         })
         .unwrap_or_default();
-    if team_key.is_empty()
-        || crate::lifecycle::launch::launched_team_receiver_is_attached(workspace, &team_key)
-    {
+    if team_key.is_empty() {
         return;
     }
     let Some(object) = report.as_object_mut() else {
@@ -467,23 +592,37 @@ pub(crate) fn append_registry_channel_unbound_to_report(
         .and_then(Value::as_array)
         .cloned()
         .unwrap_or_default();
-    if !issues.iter().any(|item| {
-        item.as_str() == Some("leader_not_attached")
-            || item.get("id").and_then(Value::as_str) == Some("leader_channel_unbound")
-    }) {
-        issues.push(json!("leader_not_attached"));
-    }
-    object.insert("issues".to_string(), Value::Array(issues));
     let mut repairs = object
         .get("suggested_repairs")
         .and_then(Value::as_array)
         .cloned()
         .unwrap_or_default();
-    repairs.push(recovery_hint(
-        &team_key,
-        "leader_not_attached",
-        "team-agent claim-leader",
-    ));
+    if !workspace_has_existing_team_runtime(workspace, &team_key) {
+        let mut issues_value = Value::Array(issues);
+        let mut repairs_value = Value::Array(repairs);
+        push_issue_repair(
+            &mut issues_value,
+            &mut repairs_value,
+            &team_key,
+            TEAM_SPEC_OR_RUNTIME_MISSING,
+            TEAM_SPEC_OR_RUNTIME_MISSING_REPAIR,
+        );
+        object.insert("issues".to_string(), issues_value);
+        object.insert("suggested_repairs".to_string(), repairs_value);
+        object.insert("ok".to_string(), Value::Bool(false));
+        return;
+    }
+    let class = crate::lifecycle::launch::classify_leader_binding(workspace, &team_key);
+    if class == crate::lifecycle::launch::LeaderBindingClass::Attached {
+        return;
+    }
+    let state = crate::state::persist::load_runtime_state(workspace).unwrap_or(json!({}));
+    let (issue_id, repair) = existing_team_binding_issue(&state, &team_key, class);
+    if !issues.iter().any(|item| item.as_str() == Some(issue_id)) {
+        issues.push(json!(issue_id));
+    }
+    repairs.push(recovery_hint(&team_key, issue_id, repair));
+    object.insert("issues".to_string(), Value::Array(issues));
     object.insert("suggested_repairs".to_string(), Value::Array(repairs));
 }
 
@@ -798,9 +937,7 @@ fn recovery_hint(team: &str, broken_class: &str, hint_action: &str) -> Value {
         "broken_class": broken_class,
         "hint_action": hint_action,
         "dedupe_key": format!("{team}:{broken_class}"),
-        "action": format!(
-            "{hint_action} # alternatives: team-agent restart; team-agent claim-leader; team-agent takeover; team-agent quick-start; team-agent attach-leader"
-        ),
+        "action": hint_action,
     })
 }
 
@@ -808,6 +945,140 @@ fn recovery_hint(team: &str, broken_class: &str, hint_action: &str) -> Value {
 mod tests {
     use super::*;
 
+    #[test]
+    fn hint_action_does_not_emit_attach_leader() {
+        let workspace = std::path::PathBuf::from("/tmp/ta-hint-ws");
+        let endpoint = "/tmp/ta-hint.sock";
+        let state = json!({
+            "team_key": "alpha",
+            "leader_receiver": {
+                "status": "attached",
+                "pane_id": "%1",
+                "provider": "codex",
+                "tmux_socket": endpoint
+            }
+        });
+        let transport = crate::transport::test_support::OfflineTransport::default()
+            .with_tmux_endpoint(endpoint)
+            .with_targets(vec![crate::transport::PaneInfo {
+                pane_id: crate::transport::PaneId::new("%1"),
+                session: crate::transport::SessionName::new("s"),
+                window_index: None,
+                window_name: None,
+                pane_index: None,
+                tty: None,
+                current_command: Some("codex".to_string()),
+                current_path: Some(std::path::PathBuf::from("/tmp/other-ws")),
+                active: true,
+                pane_pid: None,
+                leader_env: Default::default(),
+            }]);
+        let Some((_, repair)) =
+            live_leader_workspace_mismatch(&workspace, &state, &transport)
+        else {
+            panic!("workspace mismatch repair required");
+        };
+        let hint = repair
+            .get(HINT_ACTION_FIELD)
+            .and_then(Value::as_str)
+            .unwrap_or("");
+        let action = repair
+            .get(ACTION_FIELD)
+            .and_then(Value::as_str)
+            .unwrap_or("");
+        for field in [hint, action] {
+            assert!(
+                !field.contains("attach-leader"),
+                "mismatch repair must not emit attach-leader; got {field}"
+            );
+            assert!(
+                !field.contains("claim-leader"),
+                "mismatch repair must not emit claim-leader; got {field}"
+            );
+            assert!(
+                !field.contains("takeover"),
+                "mismatch repair must not emit takeover; got {field}"
+            );
+        }
+    }
+
+    #[test]
+    fn recovery_hint_does_not_bundle_unrelated_bind_commands() {
+        let hint = recovery_hint("alpha", "tmux_session_missing", "team-agent restart");
+        let action = hint.get("action").and_then(Value::as_str).unwrap_or("");
+        assert_eq!(action, "team-agent restart");
+        assert!(
+            !action.contains("claim-leader"),
+            "shotgun alternatives must not appear; action={action}"
+        );
+        assert!(
+            !action.contains("takeover"),
+            "shotgun alternatives must not appear; action={action}"
+        );
+    }
+
+    #[test]
+    fn missing_workspace_does_not_classify_as_unbound_claim() {
+        let workspace = std::env::temp_dir().join(format!(
+            "ta-diagnose-missing-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&workspace).unwrap();
+        let state = json!({"agents": {}, "tasks": [], "session_name": null, "active_team_key": null});
+        let mut issues = json!([]);
+        let mut repairs = json!([]);
+        append_registry_channel_unbound_issue(
+            &workspace,
+            &state,
+            Some("current"),
+            &mut issues,
+            &mut repairs,
+        );
+        let _ = std::fs::remove_dir_all(&workspace);
+        let issues_text = issues.to_string();
+        let repairs_text = repairs.to_string();
+        assert!(
+            issues_text.contains(TEAM_SPEC_OR_RUNTIME_MISSING),
+            "issues={issues_text}"
+        );
+        assert!(
+            !issues_text.contains("leader_receiver_unbound"),
+            "missing team must not be unbound; issues={issues_text}"
+        );
+        assert!(
+            repairs_text.contains("quick-start"),
+            "repairs={repairs_text}"
+        );
+        assert!(
+            !repairs_text.contains("claim-leader"),
+            "missing team must not induce claim; repairs={repairs_text}"
+        );
+    }
+
+    #[test]
+    fn diagnose_runtime_does_not_emit_not_committed_parallel() {
+        let state = json!({
+            "leader_receiver": {"status": "pending", "pane_id": "%1"}
+        });
+        let transport = crate::transport::test_support::OfflineTransport::default();
+        let (issues, repairs) = diagnose_runtime(&state, &transport);
+        let issues_text = issues.to_string();
+        let repairs_text = repairs.to_string();
+        assert!(
+            !issues_text.contains("leader_receiver_not_committed"),
+            "issues={issues_text}"
+        );
+        assert!(
+            !repairs_text.contains("leader_receiver_not_committed"),
+            "repairs={repairs_text}"
+        );
+    }
+
+
     fn write_codex_identity_rollout(
         workspace: &std::path::Path,
         session_id: &str,
@@ -1492,11 +1763,6 @@ fn fake_agent_started(agent: &Value) -> bool {
 }
 
 fn agent_mcp_ready(agent: &Value) -> bool {
-    if agent.get("provider").and_then(Value::as_str) == Some("pi") {
-        // The generated wrapper proves configured-lazy only. No persisted
-        // objective Pi MCP roundtrip receipt exists on the readiness path yet.
-        return false;
-    }
     agent
         .get("mcp_config")
         .and_then(Value::as_str)
@@ -1640,7 +1906,6 @@ pub(crate) fn provider_doctor_checks() -> Value {
         crate::provider::Provider::GeminiCli,
         crate::provider::Provider::Grok,
         crate::provider::Provider::CursorAgent,
-        crate::provider::Provider::Pi,
         crate::provider::Provider::Fake,
     ] {
         let adapter = crate::provider::get_adapter(provider);

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

@@ -3,6 +3,7 @@
 //! 人读标量/集合渲染(`human_value` / `json_dumps_like`)。
 
 use super::spec::{command_spec, CommandKind, CommandTier, ALL_DISPATCH_KINDS, COMMAND_SPECS};
+use super::models::cmd_models;
 use super::*;
 use std::io::{ErrorKind, Write as _};
 
@@ -85,10 +86,31 @@ pub fn run(argv: &[String], cwd: &Path) -> ExitCode {
     }
     match dispatch(command, &argv[1..], cwd) {
         Ok(exit) => exit,
-        Err(error) => emit_cli_error(command, &argv[1..], cwd, &error),
+        Err(error) => emit_cli_error_for_command(command, &argv[1..], cwd, &error),
     }
 }
 
+fn emit_cli_error_for_command(
+    command: &str,
+    args: &[String],
+    cwd: &Path,
+    error: &CliError,
+) -> ExitCode {
+    if command == "status" {
+        emit_status_cli_error(error)
+    } else {
+        emit_cli_error(command, args, cwd, error)
+    }
+}
+
+fn emit_status_cli_error(error: &CliError) -> ExitCode {
+    let normalized = normalize_cli_error(error);
+    let payload_error = normalized.as_ref().unwrap_or(error);
+    let safe_error = crate::redaction::redact_external_text(&payload_error.to_string());
+    eprintln!("error: {safe_error}");
+    ExitCode::Error
+}
+
 /// Print a handler's CmdResult to stdout (emit formats json/human), then surface its exit code.
 /// (parser.py: `print(emit(result, as_json))` then the ok→exit mapping.)
 fn emit_result(r: CmdResult) -> ExitCode {
@@ -387,7 +409,7 @@ fn command_help(command: Option<&str>) -> String {
         )
         .to_string(),
         Some("allow-peer-talk") => "usage: team-agent allow-peer-talk A B [--workspace WORKSPACE] [--json]".to_string(),
-        Some("status") => "usage: team-agent status [AGENT] [--workspace WORKSPACE] [--team TEAM] [--summary|--json] [--detail]\n\n默认输出: worker,空闲|工作|错误；错误细分走 status --summary".to_string(),
+        Some("status") => "usage: team-agent status [AGENT] [--workspace WORKSPACE] [--team TEAM] [--summary|--json] [--detail]\n\n输出七字段：name/provider/runtime_status/activity/health/session_name/tmux_command；人读与 --json 使用同一投影。缺少可靠定位或 nodeprobe 证据时显示 unknown；tmux_command 可复制到对应目标。--summary/--detail 仅保留兼容性，不增加诊断字段。".to_string(),
         Some("models") => "usage: team-agent models --provider pi [--search TEXT] [--json]\n\nPrints models.v1 exact role_model entries; each entry includes current=true|false. Catalog readiness is reported as auth=ok|not_ready with auth_basis=catalog_visibility.".to_string(),
         Some("stop") => compat_hidden_help("stop", "usage: team-agent stop [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]"),
         Some("shutdown") => "usage: team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]".to_string(),
@@ -416,7 +438,7 @@ fn command_help(command: Option<&str>) -> String {
         Some("sessions") => "usage: team-agent sessions [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
         Some("validate") => "usage: team-agent validate [SPEC] [--json]".to_string(),
         Some("install-skill") => "usage: team-agent install-skill (--source DIR | --uninstall) [--target codex|claude|copilot|all] [--dest DIR] [--dry-run] [--json]".to_string(),
-        Some("profile") => "usage: team-agent profile COMMAND NAME [--workspace WORKSPACE] [--team TEAM] [--auth-mode MODE] [--json]".to_string(),
+        Some("profile") => "usage: team-agent profile COMMAND NAME [--workspace WORKSPACE] [--team TEAM] [--auth-mode MODE] [--proxy-mode direct|inherit] [--json]".to_string(),
         Some("collect") => "usage: team-agent collect [--workspace WORKSPACE] [--team TEAM] [--result-file FILE] [--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(),
@@ -832,6 +854,7 @@ struct ParsedArgs {
     assignee: Option<String>,
     out: Option<PathBuf>,
     auth_mode: Option<String>,
+    proxy_mode: Option<String>,
     pane: Option<String>,
     to_name: Option<String>,
     /// E7 (0.5.9 host-leader-registry-design §4.2): `send --to-leader NAME`
@@ -930,6 +953,7 @@ fn parse_args(args: &[String]) -> ParsedArgs {
             "--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),
             "--to-name" => parsed.to_name = next_arg(args, &mut i),
             "--to-leader" => parsed.to_leader = next_arg(args, &mut i),
@@ -948,6 +972,9 @@ fn parse_args(args: &[String]) -> ParsedArgs {
             other if other.starts_with("--team=") => {
                 parsed.team = Some(other.trim_start_matches("--team=").to_string());
             }
+            other if other.starts_with("--proxy-mode=") => {
+                parsed.proxy_mode = Some(other.trim_start_matches("--proxy-mode=").to_string());
+            }
             other if other.starts_with("--pane=") => {
                 parsed.pane = Some(other.trim_start_matches("--pane=").to_string());
             }
@@ -1682,6 +1709,7 @@ fn profile_args(args: &[String], cwd: &Path) -> Result<ProfileArgs, CliError> {
         workspace: resolve_path(&workspace),
         team: parsed.team,
         auth_mode: parsed.auth_mode,
+        proxy_mode: parsed.proxy_mode,
         json: parsed.json,
     })
 }
@@ -1965,16 +1993,25 @@ mod tests {
                 "`{command}` appears in default help without default_help=true"
             );
         }
-        for spec in COMMAND_SPECS.iter().filter(|spec| spec.default_help) {
+        let expected: Vec<&str> = COMMAND_SPECS
+            .iter()
+            .filter(|spec| spec.default_help)
+            .map(|spec| spec.name)
+            .collect();
+        for spec_name in &expected {
             assert!(
-                visible.iter().any(|command| command == spec.name),
-                "`{}` has default_help=true but is missing from top-level help",
-                spec.name
+                visible.iter().any(|command| command == spec_name),
+                "`{spec_name}` has default_help=true but is missing from top-level help"
             );
         }
-        assert!(
-            visible.len() <= 15,
-            "default visible command count must stay <= 15, got {visible:?}"
+        let mut actual = visible.clone();
+        actual.sort();
+        let mut expected_sorted: Vec<String> =
+            expected.iter().map(|name| (*name).to_string()).collect();
+        expected_sorted.sort();
+        assert_eq!(
+            actual, expected_sorted,
+            "default help must match the exact default_help spec set (d40 ∪ results when present), not a slack threshold; got {visible:?}"
         );
         assert!(
             top_help.contains("copilot"),
@@ -2184,11 +2221,18 @@ mod tests {
     }
 
     #[test]
-    fn status_help_mentions_summary_for_error_details() {
-        assert!(
-            command_help(Some("status")).contains("错误细分走 status --summary"),
-            "status help must tell users where detailed error classes live"
-        );
+    fn status_help_describes_brief_projection_and_unknown_boundary() {
+        let help = command_help(Some("status"));
+        for marker in [
+            "name/provider/runtime_status/activity/health/session_name/tmux_command",
+            "人读与 --json 使用同一投影",
+            "显示 unknown",
+            "tmux_command",
+            "不增加诊断字段",
+        ] {
+            assert!(help.contains(marker), "status help missing {marker}: {help}");
+        }
+        assert!(!help.contains("错误细分走 status --summary"));
     }
 
     #[test]