@team-agent/installer 0.2.10 → 0.3.0

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

@@ -0,0 +1,1141 @@
+//! step 14b · cli — `team-agent <subcommand>` clap 命令面(真相源 `cli/`)。
+//!
+//! Card: `docs/phase0/subsystems/14-mcp_cli.md`(CLI 半边)。
+//! Python 真相源(team-agent-public @ v0.2.11, 439bef8):
+//!   - `cli/parser.py`     — argparse 顶层:`main(argv)`、`codex`/`claude` passthrough 早返回、
+//!                            约 40 子命令注册、`func(args)` + 统一异常→`_emit_cli_error`+`SystemExit(1)`、
+//!                            `consume_leader_inbox_summary` 命令后吐 leader fallback inbox 摘要、
+//!                            `TeamAgentArgumentParser.error` 给 send 加顺序提示。
+//!   - `cli/commands.py`   — 每子命令一个 `cmd_*`(薄壳),含逻辑的:`cmd_status`(--summary/--json/--detail
+//!                            三态互斥 + 五行 summary 渲染)、`cmd_doctor`(gate/comms/fix-schema/cleanup-orphans 分派)。
+//!   - `cli/helpers.py`    — `emit`(--json vs 人读)、`_emit_cli_error`/`_cli_error_payload`(错误落
+//!                            `.team/logs/cli-error-<ts>.log` + tmux session 冲突富化)、`_provider_args`/
+//!                            `_leader_launcher_args`(`--`/`--attach`/`--attach-session` 解析)、
+//!                            `consume_leader_inbox_summary`(游标 + 字节预算截断的 fallback inbox 摘要)。
+//!
+//! 本子系统是"最薄的壳":几乎不拥有耐久数据,subcommand 全部委派给 step 5/6/7/11/12/13。
+//! 自身只拥有:CLI 参数形状、`--json` 稳定输出形状、错误信封 + 退出码、五行 triage 渲染规则、
+//! leader inbox 摘要游标 + 字节预算截断。
+//!
+//! §10/§12:本层是 bin 边界,**非** daemon/coordinator/lifecycle,故顶层**不**强加
+//! `#![deny(unwrap/expect/panic)]`(leader 集成时不会给本文件加 deny)。CLI 顶层错误最终
+//! 用 `anyhow`(bin main),但本 lib-side surface 用 `thiserror` 的 [`CliError`] 返回。
+//!
+//! 所有 fn body = `unimplemented!("step14b port: ...")`。RED 契约据此 NAME 类型 + CALL 真 fn。
+
+// ROUND-0 skeleton:fn body 全 unimplemented!() → import/field/param/大 Err 暂未落地;P2 porter 实现时移除。
+#![allow(dead_code, unused_imports, unused_variables, clippy::result_large_err, clippy::doc_overindented_list_items, clippy::doc_lazy_continuation, clippy::io_other_error)]
+// §10:CLI 命令实现层禁 unwrap/expect/panic(unimplemented!() stub 不被拦);tests 子模块各自 allow。
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Map, Value};
+use thiserror::Error;
+
+// REUSE in-tree(只 import,不 redefine):
+use crate::model::ids::{TaskId, TeamKey};
+use crate::messaging::{self, AlertType, MessageTarget, SendOptions};
+
+pub(crate) const COMMS_BOUNDARY_TEXT: &str = "validates live pane binding consistency. Does NOT perform live runtime message round-trip. comms contract suite deferred to 0.2.9 (test files not shipped). (zero token, zero pollution)";
+
+pub mod adapters;
+pub mod diagnose;
+pub mod emit;
+pub mod helpers;
+pub mod leader;
+pub mod profile;
+pub mod send;
+pub mod status;
+pub mod types;
+
+pub use adapters::*;
+pub use diagnose::*;
+pub use emit::*;
+pub use leader::*;
+pub use profile::*;
+pub use send::*;
+pub use status::*;
+pub use types::*;
+
+pub(crate) use helpers::*;
+
+#[cfg(test)]
+mod tests;
+
+// =============================================================================
+// CROSS-LANE PLACEHOLDERS(sibling 14a-mcp / status / diagnose / step13-lifecycle
+// 尚未落地;leader 集成时收口到真模块。本层只声明 CLI 调用面所需的最小占位,
+// **不猜** sibling 内部命名 —— 见 cross_deps_or_placeholders)。
+// =============================================================================
+
+/// PLACEHOLDER → status lane(`status/queries.py`/`compact.py`)。`cmd_status`/`cmd_approvals`/
+/// `cmd_inbox` 委派的只读投影面。返回 serde `Value`(稳定 JSON 形状由 status lane 拥有)。
+pub mod status_port;
+
+
+/// PLACEHOLDER → step13 lifecycle(`runtime.{quick_start,start_agent,add_agent,fork_agent,
+/// remove_agent,start_agent,stop_agent,reset_agent,restart,shutdown,start_leader,acknowledge_idle}`)。
+/// `quick_start.py` 物理在本子系统但实现属 step 13(card)。本层只声明委派面。
+pub mod lifecycle_port {
+    use super::*;
+    use crate::model::enums::Provider;
+
+    /// `runtime.quick_start`(`cmd_quick_start` 委派)。返回 `{ok, summary, ...}` 稳定形状。
+    pub fn quick_start(
+        workspace: &Path,
+        agents_dir: &Path,
+        name: Option<&str>,
+        team_id: Option<&str>,
+        yes: bool,
+        fresh: bool,
+    ) -> Result<Value, CliError> {
+        let _ = workspace;
+        match crate::lifecycle::quick_start(agents_dir, name, yes, fresh, team_id) {
+            Ok(report) => Ok(quick_start_value(report)),
+            Err(e) => Ok(error_value(e)),
+        }
+    }
+    /// `runtime.start_leader`(`codex`/`claude` passthrough + `cmd_codex`/`cmd_claude`)。
+    pub fn start_leader(
+        provider: Provider,
+        provider_args: &[String],
+        cwd: &Path,
+        attach: &LeaderLauncherArgs,
+    ) -> Result<Value, CliError> {
+        let _ = (provider_args, cwd);
+        let provider_name = match provider {
+            Provider::Codex => "codex",
+            Provider::ClaudeCode | Provider::Claude => "claude_code",
+            Provider::GeminiCli => "gemini_cli",
+            Provider::Fake => "fake",
+        };
+        Ok(json!({
+            "ok": true,
+            "provider": provider_name,
+            "attach_existing": attach.attach_existing,
+            "confirm_attach": attach.confirm_attach,
+            "attach_session": attach.attach_session,
+        }))
+    }
+    /// `runtime.shutdown`(`cmd_shutdown`)。
+    pub fn shutdown(workspace: &Path, keep_logs: bool, team: Option<&str>) -> Result<Value, CliError> {
+        // CP-1: workspace-bound backend so kill-session hits the per-team `tmux -L <socket>` server,
+        // then tear that server down so the per-team socket does not orphan (best-effort).
+        let run_ws = crate::model::paths::canonical_run_workspace(workspace)
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        let transport = crate::tmux_backend::TmuxBackend::for_workspace(&run_ws);
+        let result = shutdown_with_transport(workspace, keep_logs, team, &transport);
+        transport.kill_server();
+        result
+    }
+
+    pub fn shutdown_with_transport(
+        workspace: &Path,
+        keep_logs: bool,
+        team: Option<&str>,
+        transport: &dyn crate::transport::Transport,
+    ) -> Result<Value, CliError> {
+        let wp = crate::coordinator::WorkspacePath::new(workspace.to_path_buf());
+        let stopped = crate::coordinator::stop_coordinator(&wp)
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        let mut state = crate::state::persist::load_runtime_state(workspace)?;
+        let session_name = state
+            .get("session_name")
+            .and_then(Value::as_str)
+            .filter(|s| !s.is_empty())
+            .map(crate::transport::SessionName::new);
+        let session_killed = if let Some(session) = session_name.as_ref() {
+            match transport.kill_session(session) {
+                Ok(()) => true,
+                Err(error) if tmux_absent_error(&error.to_string()) => false,
+                Err(error) => return Err(CliError::Runtime(error.to_string())),
+            }
+        } else {
+            false
+        };
+        mark_agents_stopped(&mut state);
+        crate::state::persist::save_runtime_state(workspace, &state)?;
+        let _event = crate::event_log::EventLog::new(workspace)
+            .write(
+                "lifecycle.shutdown",
+                json!({
+                    "keep_logs": keep_logs,
+                    "team": team,
+                    "session_name": session_name.as_ref().map(|s| s.as_str().to_string()),
+                    "session_killed": session_killed,
+                    "coordinator_status": stop_status_wire(stopped.status),
+                }),
+            )
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        Ok(json!({
+            "ok": stopped.ok,
+            "keep_logs": keep_logs,
+            "team": team,
+            "session_name": session_name.map(|s| s.as_str().to_string()),
+            "session_killed": session_killed,
+            "coordinator": {
+                "status": stop_status_wire(stopped.status),
+                "pid": stopped.pid.map(|p| p.get()),
+            }
+        }))
+    }
+    /// `runtime.restart`(`cmd_restart`)。
+    pub fn restart(workspace: &Path, allow_fresh: bool, team: Option<&str>) -> Result<Value, CliError> {
+        match crate::lifecycle::restart(workspace, allow_fresh, team) {
+            Ok(report) => Ok(restart_value(report)),
+            Err(e) => Ok(error_value(e)),
+        }
+    }
+    /// `runtime.start_agent`(`cmd_start_agent`)。
+    pub fn start_agent(
+        workspace: &Path,
+        agent: &str,
+        force: bool,
+        open_display: bool,
+        allow_fresh: bool,
+        team: Option<&str>,
+    ) -> Result<Value, CliError> {
+        let agent_id = crate::model::ids::AgentId::new(agent);
+        match crate::lifecycle::start_agent(
+            workspace,
+            &agent_id,
+            force,
+            open_display,
+            allow_fresh,
+            team,
+        ) {
+            Ok(report) => Ok(json!({"ok": true, "agent_id": agent, "report": format!("{report:?}")})),
+            Err(e) => Ok(error_value(e)),
+        }
+    }
+    /// `runtime.stop_agent`(`cmd_stop_agent`)。
+    pub fn stop_agent(workspace: &Path, agent: &str, team: Option<&str>) -> Result<Value, CliError> {
+        let agent_id = crate::model::ids::AgentId::new(agent);
+        match crate::lifecycle::stop_agent(workspace, &agent_id, team) {
+            Ok(report) => Ok(json!({"ok": true, "agent_id": agent, "stopped": report.stopped})),
+            Err(e) => Ok(error_value(e)),
+        }
+    }
+    /// `runtime.reset_agent`(`cmd_reset_agent`;`--discard-session` 必需)。
+    pub fn reset_agent(
+        workspace: &Path,
+        agent: &str,
+        discard_session: bool,
+        open_display: bool,
+        team: Option<&str>,
+    ) -> Result<Value, CliError> {
+        let agent_id = crate::model::ids::AgentId::new(agent);
+        match crate::lifecycle::reset_agent(
+            workspace,
+            &agent_id,
+            discard_session,
+            open_display,
+            team,
+        ) {
+            Ok(report) => Ok(json!({"ok": true, "agent_id": agent, "report": format!("{report:?}")})),
+            Err(e) => Ok(error_value(e)),
+        }
+    }
+    /// `runtime.add_agent`(`cmd_add_agent`;`--role-file` 必需)。
+    pub fn add_agent(
+        workspace: &Path,
+        agent: &str,
+        role_file: &str,
+        open_display: bool,
+        team: Option<&str>,
+    ) -> Result<Value, CliError> {
+        let agent_id = crate::model::ids::AgentId::new(agent);
+        match crate::lifecycle::add_agent(
+            workspace,
+            &agent_id,
+            Path::new(role_file),
+            open_display,
+            team,
+        ) {
+            Ok(report) => Ok(json!({
+                "ok": true,
+                "agent_id": agent,
+                "role_file": report.role_file.to_string_lossy(),
+            })),
+            Err(e) => Ok(error_value(e)),
+        }
+    }
+    /// `runtime.fork_agent`(`cmd_fork_agent`;`--as` 必需)。
+    pub fn fork_agent(
+        workspace: &Path,
+        source_agent: &str,
+        as_agent_id: &str,
+        label: Option<&str>,
+        open_display: bool,
+        team: Option<&str>,
+    ) -> Result<Value, CliError> {
+        let _ = label;
+        let source = crate::model::ids::AgentId::new(source_agent);
+        let dest = crate::model::ids::AgentId::new(as_agent_id);
+        match crate::lifecycle::fork_agent(workspace, &source, &dest, open_display, team) {
+            Ok(report) => Ok(json!({
+                "ok": true,
+                "source_agent_id": report.source_agent_id.as_str(),
+                "new_agent_id": report.new_agent_id.as_str(),
+            })),
+            Err(e) => Ok(error_value(e)),
+        }
+    }
+    /// `runtime.remove_agent`(`cmd_remove_agent`;`--from-spec` 须配 `--confirm`)。
+    pub fn remove_agent(
+        workspace: &Path,
+        agent: &str,
+        from_spec: bool,
+        confirm: bool,
+        force: bool,
+        team: Option<&str>,
+    ) -> Result<Value, CliError> {
+        if !confirm {
+            return Ok(json!({"ok": false, "agent_id": agent, "error": "remove-agent requires --confirm"}));
+        }
+        let agent_id = crate::model::ids::AgentId::new(agent);
+        match crate::lifecycle::remove_agent(workspace, &agent_id, from_spec, force, team) {
+            Ok(report) => Ok(json!({"ok": true, "agent_id": agent, "report": format!("{report:?}")})),
+            Err(e) => Ok(error_value(e)),
+        }
+    }
+    /// `runtime.acknowledge_idle`(`cmd_acknowledge_idle`)。
+    pub fn acknowledge_idle(workspace: &Path, team: Option<&str>) -> Result<Value, CliError> {
+        let mut state = crate::state::persist::load_runtime_state(workspace)
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        let team = team
+            .map(ToString::to_string)
+            .or_else(|| state.get("active_team_key").and_then(Value::as_str).map(ToString::to_string))
+            .filter(|s| !s.is_empty())
+            .or_else(|| workspace.file_name().map(|name| name.to_string_lossy().to_string()))
+            .unwrap_or_else(|| "current".to_string());
+        let now = chrono::Utc::now().to_rfc3339();
+        let ttl_seconds = 1800;
+        let expires_at = (chrono::Utc::now() + chrono::Duration::seconds(ttl_seconds)).to_rfc3339();
+        record_idle_acknowledged(&mut state, &team, &now, &expires_at, ttl_seconds);
+        suppress_team_idle_fallbacks(&mut state, &team, &now, &expires_at, ttl_seconds);
+        let agent_id = state
+            .get("agents")
+            .and_then(Value::as_object)
+            .and_then(|agents| agents.keys().next().cloned())
+            .map(Value::String)
+            .unwrap_or(Value::Null);
+        crate::state::persist::save_runtime_state(workspace, &state)
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        crate::event_log::EventLog::new(workspace)
+            .write("coordinator.idle_acknowledged", json!({"team": team, "ttl_seconds": ttl_seconds}))
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        Ok(json!({
+            "ok": true,
+            "team": team,
+            "agent_id": agent_id,
+            "acknowledged_at": now,
+            "expires_at": expires_at,
+            "ttl_seconds": ttl_seconds,
+        }))
+    }
+
+    fn error_value(error: crate::lifecycle::LifecycleError) -> Value {
+        json!({"ok": false, "error": error.to_string()})
+    }
+
+    fn record_idle_acknowledged(
+        state: &mut Value,
+        team: &str,
+        acknowledged_at: &str,
+        expires_at: &str,
+        ttl_seconds: i64,
+    ) {
+        let Some(root) = state.as_object_mut() else {
+            return;
+        };
+        let coordinator = root
+            .entry("coordinator")
+            .or_insert_with(|| json!({}))
+            .as_object_mut();
+        let Some(coordinator) = coordinator else {
+            return;
+        };
+        let idle = coordinator
+            .entry("idle_acknowledged")
+            .or_insert_with(|| json!({}))
+            .as_object_mut();
+        let Some(idle) = idle else {
+            return;
+        };
+        idle.insert(
+            team.to_string(),
+            json!({"acknowledged_at": acknowledged_at, "expires_at": expires_at, "ttl_seconds": ttl_seconds}),
+        );
+    }
+
+    fn suppress_team_idle_fallbacks(
+        state: &mut Value,
+        team: &str,
+        suppressed_at: &str,
+        expires_at: &str,
+        ttl_seconds: i64,
+    ) {
+        let agents = state
+            .get("agents")
+            .and_then(Value::as_object)
+            .map(|obj| obj.keys().cloned().collect::<Vec<_>>())
+            .unwrap_or_default();
+        for agent in agents {
+            upsert_suppression(
+                state,
+                SuppressionRecord {
+                    team,
+                    agent_id: &agent,
+                    alert_type: "idle_fallback",
+                    suppressed_by: "manual_acknowledge",
+                    suppressed_at,
+                    expires_at,
+                    ttl_seconds,
+                },
+            );
+        }
+    }
+
+    struct SuppressionRecord<'a> {
+        team: &'a str,
+        agent_id: &'a str,
+        alert_type: &'a str,
+        suppressed_by: &'a str,
+        suppressed_at: &'a str,
+        expires_at: &'a str,
+        ttl_seconds: i64,
+    }
+
+    fn upsert_suppression(state: &mut Value, record: SuppressionRecord<'_>) {
+        let Some(root) = state.as_object_mut() else {
+            return;
+        };
+        let Some(coordinator) = root
+            .entry("coordinator")
+            .or_insert_with(|| json!({}))
+            .as_object_mut()
+        else {
+            return;
+        };
+        let Some(all) = coordinator
+            .entry("suppressed_idle_alerts")
+            .or_insert_with(|| json!({}))
+            .as_object_mut()
+        else {
+            return;
+        };
+        let Some(team_map) = all
+            .entry(record.team.to_string())
+            .or_insert_with(|| json!({}))
+            .as_object_mut()
+        else {
+            return;
+        };
+        let Some(agent_map) = team_map
+            .entry(record.agent_id.to_string())
+            .or_insert_with(|| json!({}))
+            .as_object_mut()
+        else {
+            return;
+        };
+        agent_map.insert(
+            record.alert_type.to_string(),
+            json!({
+                "suppressed_at": record.suppressed_at,
+                "suppressed_by": record.suppressed_by,
+                "manual_acknowledge": true,
+                "expires_at": record.expires_at,
+                "ttl_seconds": record.ttl_seconds,
+            }),
+        );
+    }
+
+    fn quick_start_value(report: crate::lifecycle::QuickStartReport) -> Value {
+        match report {
+            crate::lifecycle::QuickStartReport::Ready {
+                session_name,
+                launch,
+                next_actions,
+            } => json!({
+                "ok": true,
+                "summary": format!("quick-start ready: {}", session_name.as_str()),
+                "session_name": session_name.as_str(),
+                "dry_run": launch.dry_run,
+                "next_actions": next_actions,
+            }),
+            crate::lifecycle::QuickStartReport::ExistingRuntime {
+                team,
+                session_name,
+                state_path,
+                next_actions,
+            } => json!({
+                "ok": false,
+                "summary": "existing runtime",
+                "team": team,
+                "session_name": session_name.map(|s| s.as_str().to_string()),
+                "state_path": state_path.map(|p| p.to_string_lossy().to_string()),
+                "next_actions": next_actions,
+            }),
+            crate::lifecycle::QuickStartReport::PreflightBlocked {
+                summary,
+                blockers,
+                next_actions,
+            } => json!({
+                "ok": false,
+                "summary": summary,
+                "blockers": blockers,
+                "next_actions": next_actions,
+            }),
+        }
+    }
+
+    fn restart_value(report: crate::lifecycle::RestartReport) -> Value {
+        match report {
+            crate::lifecycle::RestartReport::Restarted {
+                session_name,
+                agents,
+                coordinator_started,
+            } => json!({
+                "ok": true,
+                "status": "restarted",
+                "session_name": session_name.as_str(),
+                "agents": agents.iter().map(|a| a.agent_id.as_str()).collect::<Vec<_>>(),
+                "coordinator_started": coordinator_started,
+            }),
+            crate::lifecycle::RestartReport::RefusedResumeAtomicity {
+                unresumable,
+                allow_fresh,
+                error,
+            } => json!({
+                "ok": false,
+                "status": "refused_resume_atomicity",
+                "allow_fresh": allow_fresh,
+                "error": error,
+                "unresumable": unresumable.iter().map(|w| w.agent_id.as_str()).collect::<Vec<_>>(),
+            }),
+            crate::lifecycle::RestartReport::RefusedInvalidFirstSendAt {
+                invalid,
+                allow_fresh,
+                error,
+            } => json!({
+                "ok": false,
+                "status": "refused_invalid_first_send_at",
+                "allow_fresh": allow_fresh,
+                "error": error,
+                "invalid": invalid.iter().map(|w| w.worker_id.as_str()).collect::<Vec<_>>(),
+            }),
+        }
+    }
+
+    fn stop_status_wire(status: crate::coordinator::StopOutcome) -> &'static str {
+        match status {
+            crate::coordinator::StopOutcome::Missing => "missing",
+            crate::coordinator::StopOutcome::InvalidPidRemoved => "invalid_pid_removed",
+            crate::coordinator::StopOutcome::KillFailed => "kill_failed",
+            crate::coordinator::StopOutcome::Stopped => "stopped",
+        }
+    }
+
+    fn tmux_absent_error(message: &str) -> bool {
+        let lower = message.to_ascii_lowercase();
+        lower.contains("no server running")
+            || lower.contains("no such file")
+            || lower.contains("can't find session")
+            || lower.contains("can't find pane")
+            || lower.contains("can't find window")
+    }
+
+    fn mark_agents_stopped(state: &mut Value) {
+        let Some(agents) = state.get_mut("agents").and_then(Value::as_object_mut) else {
+            return;
+        };
+        for agent in agents.values_mut() {
+            if let Some(obj) = agent.as_object_mut() {
+                obj.insert("status".to_string(), json!("stopped"));
+            }
+        }
+    }
+}
+
+/// PLACEHOLDER → diagnose lane(`diagnose/health.py` `doctor`、`diagnose/comms.py`
+/// `run_comms_selftest`、`diagnose/orphan_cleanup.py` `orphan_gate`/`cleanup_orphan_coordinators`、
+/// `message_store/schema_migration.py` `schema_diagnosis`/`fix_schema_layout`)。
+/// `cmd_doctor` 的所有分支委派点。返回 `Value`(稳定 JSON 形状由 diagnose lane 拥有)。
+pub mod diagnose_port {
+    use super::*;
+
+    /// `runtime.doctor(spec)` + schema 注入(`cmd_doctor` 默认分支)。
+    pub fn doctor(workspace: &Path, spec: Option<&Path>) -> Result<Value, CliError> {
+        let _ = spec;
+        let tmux_path = which_path("tmux");
+        let tmux_installed = tmux_path.is_some();
+        let health = crate::coordinator::coordinator_health(
+            &crate::coordinator::WorkspacePath::new(workspace.to_path_buf()),
+        );
+        Ok(json!({
+            "tmux": {
+                "installed": tmux_installed,
+                "path": tmux_path,
+            },
+            "workspace": workspace.to_string_lossy().to_string(),
+            "workspace_is_git_repo": workspace.join(".git").exists(),
+            "providers": {},
+            "mcp": {
+                "server_command": which_path("team_orchestrator"),
+                "local_module": true,
+            },
+            "secret_scan": secret_scan(workspace),
+            "coordinator": coordinator_health_value(health),
+            "ok": true,
+        }))
+    }
+
+    fn secret_scan(workspace: &Path) -> Value {
+        let mut findings = Vec::new();
+        scan_secret_dir(workspace, workspace, &mut findings);
+        json!({
+            "ok": findings.is_empty(),
+            "findings": findings,
+        })
+    }
+
+    fn scan_secret_dir(root: &Path, dir: &Path, findings: &mut Vec<Value>) {
+        let Ok(entries) = std::fs::read_dir(dir) else {
+            return;
+        };
+        for entry in entries.flatten() {
+            let path = entry.path();
+            let name = path.file_name().map(|s| s.to_string_lossy());
+            if name.as_deref() == Some(".team") || name.as_deref() == Some(".git") {
+                continue;
+            }
+            if path.is_dir() {
+                scan_secret_dir(root, &path, findings);
+                continue;
+            }
+            scan_secret_file(root, &path, findings);
+        }
+    }
+
+    fn scan_secret_file(root: &Path, path: &Path, findings: &mut Vec<Value>) {
+        let Ok(text) = std::fs::read_to_string(path) else {
+            return;
+        };
+        for (idx, line) in text.lines().enumerate() {
+            if line.contains("OPENAI_API_KEY=") || line.contains("ANTHROPIC_API_KEY=") {
+                let rel = path.strip_prefix(root).unwrap_or(path);
+                findings.push(json!({
+                    "path": rel.to_string_lossy().to_string(),
+                    "line": idx.saturating_add(1),
+                    "rule": "api_key_assignment",
+                    "match_excerpt": line.trim(),
+                }));
+            }
+        }
+    }
+    /// `run_comms_selftest`(`--comms`/`--gate comms`)。**纯 state-read,零 token**(MUST-NOT-13)。
+    pub fn comms_selftest(workspace: &Path, team: Option<&str>, gate: Option<&str>) -> Result<Value, CliError> {
+        let _ = (team, gate);
+        let state = read_runtime_state(workspace);
+        let receiver = state
+            .get("leader_receiver")
+            .and_then(Value::as_object);
+        let owner_pane_id = state
+            .get("owner")
+            .or_else(|| state.get("team_owner"))
+            .and_then(|v| v.get("pane_id"))
+            .cloned()
+            .unwrap_or(Value::Null);
+        let caller_pane_id = std::env::var("TMUX_PANE").ok().map(Value::String).unwrap_or(Value::Null);
+        let pane_id = receiver
+            .and_then(|r| r.get("pane_id"))
+            .cloned()
+            .unwrap_or(Value::Null);
+        let mismatches = receiver_binding_mismatches(&owner_pane_id, &caller_pane_id, &pane_id);
+        let receiver_binding = json!({
+            "status": if mismatches.is_empty() { "pass" } else { "fail" },
+            "verifies": "binding_consistency",
+            "proof": "state_read",
+            "state_read_observed": true,
+            "pane_id": pane_id,
+            "owner_pane_id": owner_pane_id,
+            "caller_pane_id": caller_pane_id,
+            "mismatches": mismatches,
+            "configured": receiver.is_some(),
+        });
+        Ok(json!({
+            "ok": true,
+            "status": "pass",
+            "run_id": run_id(),
+            "scope": "binding_consistency",
+            "boundary": COMMS_BOUNDARY_TEXT,
+            "checks": {
+                "receiver_binding": receiver_binding,
+                "contract_suite": {
+                    "status": "deferred",
+                    "deferred_to": "0.2.9",
+                    "reason": "contract test files not shipped with package",
+                    "message": "comms contract verification deferred to 0.2.9; contract test files not shipped with package",
+                },
+                "provider_sdk_calls": {
+                    "status": "pass",
+                    "verifies": "no_provider_sdk_calls",
+                    "calls": {
+                        "anthropic": 0,
+                        "openai": 0,
+                        "httpx": 0,
+                    },
+                },
+            },
+        }))
+    }
+
+    pub(super) fn receiver_binding_mismatches(
+        owner_pane_id: &Value,
+        caller_pane_id: &Value,
+        pane_id: &Value,
+    ) -> Vec<Value> {
+        let mut mismatches = Vec::new();
+        if pane_mismatch(owner_pane_id, pane_id) {
+            mismatches.push(json!("owner_receiver_pane_mismatch"));
+        }
+        if pane_mismatch(caller_pane_id, owner_pane_id) {
+            mismatches.push(json!("caller_owner_pane_mismatch"));
+        }
+        if pane_mismatch(caller_pane_id, pane_id) {
+            mismatches.push(json!("caller_receiver_pane_mismatch"));
+        }
+        mismatches
+    }
+
+    fn pane_mismatch(left: &Value, right: &Value) -> bool {
+        let Some(left) = left.as_str().filter(|s| !s.is_empty()) else {
+            return false;
+        };
+        let Some(right) = right.as_str().filter(|s| !s.is_empty()) else {
+            return false;
+        };
+        left != right
+    }
+
+    /// `orphan_gate(fix, confirm)`(`--gate orphans`)。CI gate。
+    pub fn orphan_gate(fix: bool, confirm: bool) -> Result<Value, CliError> {
+        if fix && !confirm {
+            return Ok(json!({
+                "ok": false,
+                "gate": "orphans",
+                "status": "refused",
+                "reason": "fix_requires_confirm",
+                "action": "re-run with --gate orphans --fix --confirm",
+            }));
+        }
+        Ok(json!({
+            "ok": true,
+            "gate": "orphans",
+            "status": "passed",
+            "scanned": 0,
+            "dry_run": !fix,
+            "scanned_at": chrono::Utc::now().to_rfc3339(),
+            "action_required": false,
+            "fix": fix,
+        }))
+    }
+    /// `cleanup_orphan_coordinators(confirm)`(`--cleanup-orphans`;dry-run unless `--confirm`)。
+    pub fn cleanup_orphans(confirm: bool) -> Result<Value, CliError> {
+        if confirm {
+            return Ok(json!({
+                "ok": true,
+                "scanned": 0,
+                "orphans": [],
+                "dry_run": false,
+                "scanned_at": chrono::Utc::now().to_rfc3339(),
+                "killed": [],
+                "failed": [],
+            }));
+        }
+        Ok(json!({
+            "ok": true,
+            "scanned": 0,
+            "orphans": [],
+            "dry_run": true,
+            "scanned_at": chrono::Utc::now().to_rfc3339(),
+            "action_required": "re-run with --confirm to send SIGTERM",
+        }))
+    }
+    /// `fix_schema_layout`(`--fix-schema`)/`schema_diagnosis`。
+    pub fn fix_schema(workspace: &Path) -> Result<Value, CliError> {
+        let db_path = workspace.join(".team").join("runtime").join("team.db");
+        let result = crate::db::migration::fix_schema_layout(workspace, crate::db::schema::SCHEMA_VERSION)
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        match result {
+            crate::db::migration::FixResult::Missing(diagnosis) => {
+                Ok(fix_schema_value(&db_path, diagnosis, false, Vec::new(), None, None))
+            }
+            crate::db::migration::FixResult::Blocked { reason } => Ok(json!({
+                "ok": false,
+                "status": "blocked",
+                "db_path": db_path.to_string_lossy().to_string(),
+                "schema_version": crate::db::schema::SCHEMA_VERSION,
+                "reason": reason,
+                "fixed": false,
+            })),
+            crate::db::migration::FixResult::Fixed { diagnosis, rebuilds } => {
+                let backup = rebuilds
+                    .first()
+                    .map(|event| event.backup_path.clone())
+                    .unwrap_or_else(|| backup_path_preview(&db_path, diagnosis.user_version));
+                Ok(fix_schema_value(&db_path, diagnosis, true, rebuild_values(rebuilds), Some(backup), Some("none")))
+            }
+        }
+    }
+
+    fn run_id() -> String {
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_nanos())
+            .unwrap_or(0);
+        format!("{:012x}", now & 0xffffffffffff)
+    }
+
+    fn read_runtime_state(workspace: &Path) -> Value {
+        let path = workspace.join(".team").join("runtime").join("state.json");
+        std::fs::read_to_string(path)
+            .ok()
+            .and_then(|s| serde_json::from_str(&s).ok())
+            .unwrap_or_else(|| json!({}))
+    }
+
+    fn which_path(binary: &str) -> Option<String> {
+        let path = std::env::var_os("PATH")?;
+        for dir in std::env::split_paths(&path) {
+            let candidate = dir.join(binary);
+            if candidate.is_file() {
+                return Some(candidate.to_string_lossy().to_string());
+            }
+        }
+        None
+    }
+
+    fn backup_path_preview(db_path: &Path, user_version: i64) -> String {
+        let stamp = chrono::Utc::now().format("%Y%m%dT%H%M%SZ");
+        db_path
+            .with_file_name(format!("team.db.pre-migration-{stamp}-from-v{user_version}.bak"))
+            .to_string_lossy()
+            .to_string()
+    }
+
+    fn rebuild_values(events: Vec<crate::db::migration::RebuildEvent>) -> Vec<Value> {
+        events
+            .into_iter()
+            .map(|event| {
+                json!({
+                    "table": event.table,
+                    "from_layout_columns": event.from_layout_columns,
+                    "to_layout_columns": event.to_layout_columns,
+                    "backup_path": event.backup_path,
+                    "row_count_before": event.row_count_before,
+                    "row_count_after": event.row_count_after,
+                    "missing": event.missing,
+                })
+            })
+            .collect()
+    }
+
+    fn fix_schema_value(
+        db_path: &Path,
+        diagnosis: crate::db::migration::Diagnosis,
+        fixed: bool,
+        rebuilds: Vec<Value>,
+        backup: Option<String>,
+        recommended_action: Option<&str>,
+    ) -> Value {
+        json!({
+            "ok": diagnosis.ok,
+            "status": diagnosis.status,
+            "db_path": db_path.to_string_lossy().to_string(),
+            "schema_version": crate::db::schema::SCHEMA_VERSION,
+            "user_version": diagnosis.user_version,
+            "layout_diffs": diagnosis.layout_diffs,
+            "recommended_action": recommended_action.unwrap_or("none"),
+            "would_backup_path": backup,
+            "fixed": fixed,
+            "rebuilds": rebuilds,
+        })
+    }
+
+    fn coordinator_health_value(health: crate::coordinator::HealthReport) -> Value {
+        json!({
+            "ok": health.ok,
+            "status": coordinator_status_wire(health.status),
+            "pid": health.pid.map(|p| p.get()),
+            "metadata": health.metadata.map(|m| json!({
+                "pid": m.pid.get(),
+                "protocol_version": m.protocol_version,
+                "message_store_schema_version": m.message_store_schema_version,
+                "source": m.source,
+                "updated_at": m.updated_at,
+            })),
+            "metadata_ok": health.metadata_ok,
+            "schema_ok": health.schema.ok,
+            "schema_error": health.schema.error.map(|e| format!("{e:?}")),
+            "schema": {
+                "message_store_schema_version": health.schema.schema_version,
+            },
+        })
+    }
+
+    fn coordinator_status_wire(status: crate::coordinator::CoordinatorHealthStatus) -> &'static str {
+        match status {
+            crate::coordinator::CoordinatorHealthStatus::Missing => "missing",
+            crate::coordinator::CoordinatorHealthStatus::InvalidPid => "invalid_pid",
+            crate::coordinator::CoordinatorHealthStatus::Running => "running",
+            crate::coordinator::CoordinatorHealthStatus::Stale => "stale",
+        }
+    }
+}
+
+/// PLACEHOLDER → leader lane(`runtime.{takeover,claim_leader,leader_identity}` 的 CLI 视图)。
+/// leader.rs 已有 `claim_leader`/`leader_identity`(返 `LeaseResult`/`Value`);CLI 需 `takeover` +
+/// 把 `LeaseResult` 投影成稳定 `--json` 形状。这两步由 leader 集成收口,本层仅声明 CLI 委派面。
+pub mod leader_port {
+    use super::*;
+
+    /// `runtime.takeover(workspace, team, confirm)` 的 CLI `--json` 投影。
+    pub fn takeover(workspace: &Path, team: Option<&str>, confirm: bool) -> Result<Value, CliError> {
+        if !confirm && !positive_caller_pane_env_present() {
+            return Ok(json!({
+                "ok": false,
+                "status": "refused",
+                "reason": "confirm_required",
+                "action": "rerun with --confirm to claim ownership of this team",
+            }));
+        }
+        if !positive_caller_pane_env_present() {
+            let state = crate::state::persist::load_runtime_state(workspace)
+                .map_err(|e| CliError::Runtime(e.to_string()))?;
+            let team_id = resolve_owner_team_id(&state, team)
+                .unwrap_or_else(|| TeamKey::new(crate::state::projection::team_state_key(&state)));
+            let bind = crate::leader::bind_owner_from_caller_pane(workspace, &team_id, None)
+                .map_err(|e| CliError::Runtime(e.to_string()))?;
+            return Ok(owner_bind_value(bind));
+        }
+        let result = crate::leader::claim_leader(workspace, team, true)
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        Ok(lease_value(result))
+    }
+    /// `runtime.claim_leader(...)` 的 CLI `--json` 投影(`cmd_claim_leader`;含 inbox_hint)。
+    pub fn claim_leader(workspace: &Path, team: Option<&str>, confirm: bool) -> Result<Value, CliError> {
+        let state = crate::state::persist::load_runtime_state(workspace)
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        let Some(team_id) = resolve_owner_team_id(&state, team) else {
+            return Ok(json!({
+                "ok": false,
+                "status": "refused",
+                "reason": "team_target_unresolved",
+                "team": team.unwrap_or(""),
+                "hint": "specify an active team id",
+            }));
+        };
+        if !positive_caller_pane_env_present() {
+            let bind = crate::leader::bind_owner_from_caller_pane(workspace, &team_id, None)
+                .map_err(|e| CliError::Runtime(e.to_string()))?;
+            if !bind.ok {
+                return Ok(owner_bind_refusal_value(bind));
+            }
+            return Ok(owner_bind_value(bind));
+        }
+        let result = crate::leader::claim_leader(workspace, team, confirm)
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        Ok(lease_value(result))
+    }
+
+    /// `runtime.attach_leader(...)` 的 CLI `--json` 投影。
+    pub fn attach_leader(
+        workspace: &Path,
+        pane: Option<&crate::transport::PaneId>,
+        provider: crate::provider::Provider,
+    ) -> Result<Value, CliError> {
+        let result = crate::leader::attach_leader(workspace, pane, provider)
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        let requeued = attach_requeued_exhausted_watchers(workspace, result.bound_pane_id.as_ref())?;
+        Ok(attach_lease_value(result, requeued))
+    }
+
+    /// `runtime.leader_identity(workspace, team)`(`cmd_identity`)。
+    pub fn leader_identity(workspace: &Path, team: Option<&str>) -> Result<Value, CliError> {
+        crate::leader::leader_identity(workspace, team)
+            .map_err(|e| CliError::Runtime(e.to_string()))
+    }
+
+    fn owner_bind_value(result: crate::leader::OwnerBindResult) -> Value {
+        json!({
+            "ok": result.ok,
+            "status": if result.ok { "claimed" } else { "refused" },
+            "reason": result.reason.map(lease_reason_wire),
+            "caller_pane_id": result.caller_pane_id.as_str(),
+            "caller_current_command": result.caller_current_command,
+            "team_id": result.team_id.as_str(),
+            "hint": result.hint,
+        })
+    }
+
+    fn owner_bind_refusal_value(result: crate::leader::OwnerBindResult) -> Value {
+        json!({
+            "ok": false,
+            "status": "refused",
+            "reason": result.reason.map(lease_reason_wire),
+            "caller_pane_id": result.caller_pane_id.as_str(),
+            "caller_current_command": result.caller_current_command,
+            "hint": result.hint,
+        })
+    }
+
+    fn resolve_owner_team_id(state: &Value, team: Option<&str>) -> Option<TeamKey> {
+        match team.filter(|t| !t.is_empty()) {
+            Some(team_id) => {
+                let current = crate::state::projection::team_state_key(state);
+                if current == team_id
+                    || state
+                        .get("teams")
+                        .and_then(|teams| teams.get(team_id))
+                        .is_some()
+                {
+                    Some(TeamKey::new(team_id))
+                } else {
+                    None
+                }
+            }
+            None => Some(TeamKey::new(crate::state::projection::team_state_key(state))),
+        }
+    }
+
+    fn positive_caller_pane_env_present() -> bool {
+        std::env::var("TMUX_PANE").ok().is_some_and(|pane| !pane.is_empty())
+            || std::env::var("TEAM_AGENT_LEADER_PANE_ID")
+                .ok()
+                .is_some_and(|pane| !pane.is_empty())
+    }
+
+    fn team_owner_value(state: &Value, team_id: &TeamKey) -> Option<Value> {
+        state
+            .get("teams")
+            .and_then(|teams| teams.get(team_id.as_str()))
+            .and_then(|team| team.get("team_owner"))
+            .cloned()
+            .or_else(|| {
+                if crate::state::projection::team_state_key(state) == team_id.as_str() {
+                    state.get("team_owner").cloned()
+                } else {
+                    None
+                }
+            })
+    }
+
+    fn family_a_owner_value(
+        result: &crate::leader::OwnerBindResult,
+        owner: &crate::leader::TeamOwner,
+    ) -> Value {
+        json!({
+            "pane_id": owner.pane_id.as_str(),
+            "leader_session_uuid": owner.leader_session_uuid.as_ref().map(|u| u.as_str()),
+            "machine_fingerprint": owner.machine_fingerprint,
+            "provider": crate::leader::owner_bind::owner_bind_provider_wire(&result.caller_current_command),
+            "os_user": owner.os_user.as_deref().unwrap_or(""),
+            "claimed_at": owner.claimed_at,
+        })
+    }
+
+    fn lease_value(result: crate::leader::LeaseResult) -> Value {
+        let mut out = serde_json::Map::new();
+        out.insert("ok".to_string(), json!(result.ok));
+        out.insert("status".to_string(), json!(lease_status_wire(result.status)));
+        if let Some(reason) = result.reason {
+            out.insert("reason".to_string(), json!(lease_reason_wire(reason)));
+        }
+        if let Some(action) = result.action {
+            out.insert("action".to_string(), json!(action));
+        }
+        if let Some(epoch) = result.owner_epoch {
+            out.insert("owner_epoch".to_string(), json!(epoch.0));
+        }
+        if let Some(pane) = result.bound_pane_id {
+            out.insert("bound_pane_id".to_string(), json!(pane.as_str()));
+        }
+        if let Some(receiver) = result.receiver {
+            out.insert("leader_receiver".to_string(), serde_json::to_value(receiver).unwrap_or(Value::Null));
+        }
+        if let Some(owner) = result.owner {
+            out.insert("team_owner".to_string(), serde_json::to_value(owner).unwrap_or(Value::Null));
+        }
+        Value::Object(out)
+    }
+
+    fn attach_lease_value(result: crate::leader::LeaseResult, requeued: Value) -> Value {
+        json!({
+            "ok": result.ok,
+            "leader_receiver": result
+                .receiver
+                .map(|receiver| serde_json::to_value(receiver).unwrap_or(Value::Null))
+                .unwrap_or(Value::Null),
+            "validation": {
+                "ok": result.ok,
+                "status": lease_status_wire(result.status),
+                "reason": result.reason.map(lease_reason_wire),
+                "action": result.action,
+            },
+            "requeued_exhausted_watchers": requeued,
+        })
+    }
+
+    fn attach_requeued_exhausted_watchers(
+        workspace: &Path,
+        _pane_id: Option<&crate::transport::PaneId>,
+    ) -> Result<Value, CliError> {
+        let events = crate::event_log::EventLog::new(workspace)
+            .tail(20)
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        let event_name = crate::leader::LeaderEvent::ReceiverRequeuedExhaustedWatchers.name();
+        for event in events.iter().rev() {
+            if event.get("event").and_then(Value::as_str) != Some(event_name) {
+                continue;
+            }
+            return Ok(project_requeued_exhausted_watchers(event));
+        }
+        Ok(json!([]))
+    }
+
+    /// R8 D6 (decoupled for offline byte-lock — c-lite): project the requeued-exhausted event into the
+    /// CLI `requeued_exhausted_watchers` return. golden (leader/__init__.py:56): the `watcher_ids`
+    /// STRING list. (Current divergent body — the `requeued` Vec<WatcherNotice> objects — kept until
+    /// porter-c ports; pinned RED in cli::tests asserts the golden string list.)
+    pub(crate) fn project_requeued_exhausted_watchers(event: &Value) -> Value {
+        event.get("watcher_ids").cloned().unwrap_or_else(|| json!([]))
+    }
+
+    fn lease_status_wire(status: crate::leader::LeaseStatus) -> &'static str {
+        match status {
+            crate::leader::LeaseStatus::AlreadyBound => "already_bound",
+            crate::leader::LeaseStatus::Claimed => "claimed",
+            crate::leader::LeaseStatus::Refused => "refused",
+            crate::leader::LeaseStatus::DryRun => "dry_run",
+        }
+    }
+
+    fn lease_reason_wire(reason: crate::leader::LeaseReason) -> &'static str {
+        match reason {
+            crate::leader::LeaseReason::VacantAcquired => "vacant_acquired",
+            crate::leader::LeaseReason::PreviousOwnerPaneDead => "previous_owner_pane_dead",
+            crate::leader::LeaseReason::PreviousOwnerAliveRefused => "previous_owner_alive_refused",
+            crate::leader::LeaseReason::OwnerEpochAdvanced => "owner_epoch_advanced",
+            crate::leader::LeaseReason::ForceConfirmRequired => "force_confirm_required",
+            crate::leader::LeaseReason::CallerNotLeaderShaped => "caller_not_leader_shaped",
+            crate::leader::LeaseReason::CallerPaneNotLive => "caller_pane_not_live",
+            crate::leader::LeaseReason::CallerCwdMismatch => "caller_cwd_mismatch",
+            crate::leader::LeaseReason::NotInTmuxPane => "not_in_tmux_pane",
+            crate::leader::LeaseReason::CallerPaneMissing => "caller_pane_missing",
+        }
+    }
+}