@team-agent/installer 0.3.0 → 0.3.1

package/Cargo.lock

@@ -555,7 +555,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent"]
 
 [workspace.package]
 edition = "2021"
-version = "0.3.0"
+version = "0.3.1"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

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

@@ -121,6 +121,50 @@ fn dispatch(command: &str, args: &[String], cwd: &Path) -> Result<ExitCode, CliE
     }
 }
 
+const DISPATCH_COMMANDS: &[&str] = &[
+    "init",
+    "quick-start",
+    "compile",
+    "send",
+    "allow-peer-talk",
+    "status",
+    "stop",
+    "shutdown",
+    "restart",
+    "restart-agent",
+    "start-agent",
+    "stop-agent",
+    "reset-agent",
+    "add-agent",
+    "fork-agent",
+    "remove-agent",
+    "stuck-list",
+    "stuck-cancel",
+    "acknowledge-idle",
+    "takeover",
+    "claim-leader",
+    "identity",
+    "approvals",
+    "inbox",
+    "doctor",
+    "watch",
+    "sessions",
+    "validate",
+    "profile",
+    "validate-result",
+    "collect",
+    "settle",
+    "repair-state",
+    "diagnose",
+    "preflight",
+    "wait-ready",
+    "e2e",
+    "peek",
+    "coordinator",
+];
+
+const SPEC_ONLY_HELP_COMMANDS: &[&str] = &["start", "purge-agent", "attach-leader"];
+
 fn emit_missing_subcommand_usage() -> ExitCode {
     emit_usage_error("the following arguments are required: {codex,claude,...,doctor}");
     ExitCode::Usage
@@ -131,65 +175,62 @@ fn emit_missing_subcommand_usage() -> ExitCode {
 /// Used by the `--help` short-circuit gate so unknown commands keep falling through
 /// to the argparse invalid-choice path.
 fn is_known_subcommand(command: &str) -> bool {
-    matches!(
-        command,
-        "init"
-            | "quick-start"
-            | "compile"
-            | "send"
-            | "allow-peer-talk"
-            | "status"
-            | "start"
-            | "stop"
-            | "shutdown"
-            | "restart"
-            | "restart-agent"
-            | "start-agent"
-            | "stop-agent"
-            | "reset-agent"
-            | "add-agent"
-            | "fork-agent"
-            | "remove-agent"
-            | "purge-agent"
-            | "stuck-list"
-            | "stuck-cancel"
-            | "acknowledge-idle"
-            | "takeover"
-            | "claim-leader"
-            | "attach-leader"
-            | "identity"
-            | "approvals"
-            | "inbox"
-            | "doctor"
-            | "watch"
-            | "sessions"
-            | "validate"
-            | "profile"
-            | "validate-result"
-            | "collect"
-            | "settle"
-            | "repair-state"
-            | "diagnose"
-            | "preflight"
-            | "wait-ready"
-            | "e2e"
-            | "peek"
-            | "coordinator"
-    )
+    DISPATCH_COMMANDS.contains(&command) || SPEC_ONLY_HELP_COMMANDS.contains(&command)
 }
 
 fn command_help(command: Option<&str>) -> String {
     match command {
-        None => "usage: team-agent <command> [options]\n\nCommands: quick-start, status, send, collect, start, stop, shutdown, restart, restart-agent, start-agent, stop-agent, reset-agent, add-agent, remove-agent, purge-agent".to_string(),
-        Some("quick-start") => "usage: team-agent quick-start [TEAMDIR] [--name NAME] [--team-id TEAM] [--yes] [--fresh] [--json]".to_string(),
+        None => {
+            let mut commands = vec!["codex", "claude"];
+            commands.extend_from_slice(DISPATCH_COMMANDS);
+            commands.extend_from_slice(SPEC_ONLY_HELP_COMMANDS);
+            format!(
+                "usage: team-agent <command> [options]\n\nCommands: {}\n\nRun `team-agent <command> --help` for command flags.",
+                commands.join(", ")
+            )
+        }
+        Some("init") => "usage: team-agent init [--workspace WORKSPACE] [--force] [--json]".to_string(),
+        Some("quick-start") => "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--fresh] [--json]".to_string(),
         Some("start") => "usage: team-agent start [TEAMDIR] [--yes] [--fresh] [--json]".to_string(),
-        Some("stop") | Some("shutdown") => "usage: team-agent stop [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]".to_string(),
+        Some("compile") => "usage: team-agent compile --team TEAM [--out FILE] [--json]".to_string(),
+        Some("send") => "usage: team-agent send TARGET MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--targets AGENTS] [--task TASK] [--sender SENDER] [--watch-result] [--requires-ack|--no-ack] [--no-wait] [--timeout SECONDS] [--confirm-human] [--message-id ID] [--json]".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] [--summary|--json] [--detail]".to_string(),
+        Some("stop") => "usage: team-agent stop [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]".to_string(),
+        Some("shutdown") => "usage: team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]".to_string(),
+        Some("restart") => "usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--json]".to_string(),
         Some("restart-agent") => "usage: team-agent restart-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--discard-session] [--no-display] [--json]".to_string(),
+        Some("reset-agent") => "usage: team-agent reset-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--discard-session] [--no-display] [--json]".to_string(),
+        Some("start-agent") => "usage: team-agent start-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--force] [--allow-fresh] [--no-display] [--json]".to_string(),
+        Some("stop-agent") => "usage: team-agent stop-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
+        Some("add-agent") => "usage: team-agent add-agent AGENT --role-file FILE [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]".to_string(),
+        Some("fork-agent") => "usage: team-agent fork-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]".to_string(),
+        Some("remove-agent") => "usage: team-agent remove-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--from-spec] [--confirm] [--force] [--json]".to_string(),
         Some("purge-agent") => "usage: team-agent purge-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--force] [--json]".to_string(),
-        Some("restart") => "usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--json]".to_string(),
-        Some("status") => "usage: team-agent status [AGENT] [--workspace WORKSPACE] [--summary|--json] [--detail]".to_string(),
-        Some("send") => "usage: team-agent send TARGET MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
+        Some("stuck-list") => "usage: team-agent stuck-list [--workspace WORKSPACE] [--json]".to_string(),
+        Some("stuck-cancel") => "usage: team-agent stuck-cancel AGENT [--workspace WORKSPACE] [--alert-type stuck|idle_fallback|cross_worker_deadlock|all] [--json]".to_string(),
+        Some("acknowledge-idle") => "usage: team-agent acknowledge-idle [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
+        Some("takeover") => "usage: team-agent takeover [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json]".to_string(),
+        Some("claim-leader") => "usage: team-agent claim-leader [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json]".to_string(),
+        Some("attach-leader") => "usage: team-agent attach-leader [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json]".to_string(),
+        Some("identity") => "usage: team-agent identity [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
+        Some("approvals") => "usage: team-agent approvals [AGENT] [--workspace WORKSPACE] [--json]".to_string(),
+        Some("inbox") => "usage: team-agent inbox AGENT [--workspace WORKSPACE] [--limit N] [--since CURSOR] [--json]".to_string(),
+        Some("doctor") => "usage: team-agent doctor [SPEC] [--workspace WORKSPACE] [--team TEAM] [--gate orphans|comms] [--comms] [--fix] [--fix-schema] [--cleanup-orphans] [--confirm] [--json]".to_string(),
+        Some("watch") => "usage: team-agent watch [--workspace WORKSPACE] [--team TEAM]".to_string(),
+        Some("sessions") => "usage: team-agent sessions [--workspace WORKSPACE] [--json]".to_string(),
+        Some("validate") => "usage: team-agent validate [SPEC] [--json]".to_string(),
+        Some("profile") => "usage: team-agent profile COMMAND NAME [--workspace WORKSPACE] [--team TEAM] [--auth-mode MODE] [--json]".to_string(),
+        Some("validate-result") => "usage: team-agent validate-result [ENVELOPE] [--file FILE|--result JSON] [--json]".to_string(),
         Some("collect") => "usage: team-agent collect [--workspace WORKSPACE] [--result-file FILE] [--json]".to_string(),
+        Some("settle") => "usage: team-agent settle [--workspace WORKSPACE] [--json]".to_string(),
+        Some("repair-state") => "usage: team-agent repair-state --task TASK --status STATUS [SUMMARY] [--assignee AGENT] [--workspace WORKSPACE] [--json]".to_string(),
+        Some("diagnose") => "usage: team-agent diagnose [--workspace WORKSPACE] [--json]".to_string(),
+        Some("preflight") => "usage: team-agent preflight [TEAMDIR] [--json]".to_string(),
+        Some("wait-ready") => "usage: team-agent wait-ready [--workspace WORKSPACE] [--timeout SECONDS] [--json]".to_string(),
+        Some("e2e") => "usage: team-agent e2e [--workspace WORKSPACE] [--providers LIST] [--real] [--json]".to_string(),
+        Some("peek") => "usage: team-agent peek AGENT [--workspace WORKSPACE] [--tail N] [--allow-raw-screen] [--json]".to_string(),
+        Some("coordinator") => "usage: team-agent coordinator [--workspace WORKSPACE] [--once] [--tick-interval SECONDS]".to_string(),
         Some(other) => format!("usage: team-agent {other} [options]"),
     }
 }
@@ -1056,6 +1097,92 @@ mod tests {
         items.iter().map(|s| (*s).to_string()).collect()
     }
 
+    fn source_dispatch_commands() -> Vec<&'static str> {
+        let source = include_str!("emit.rs");
+        let after_start = source.split_once("fn dispatch(").unwrap().1;
+        let dispatch_source = after_start.split_once("const DISPATCH_COMMANDS").unwrap().0;
+        let mut commands = Vec::new();
+        for line in dispatch_source.lines() {
+            let line = line.trim_start();
+            let Some(rest) = line.strip_prefix('"') else {
+                continue;
+            };
+            let Some((command, after_command)) = rest.split_once('"') else {
+                continue;
+            };
+            let after_command = after_command.trim_start();
+            if (after_command.starts_with("=>") || after_command.starts_with("if "))
+                && !commands.contains(&command)
+            {
+                commands.push(command);
+            }
+        }
+        commands
+    }
+
+    #[test]
+    fn t0_help_catalog_tracks_dispatch_commands() {
+        let source_commands = source_dispatch_commands();
+        for command in &source_commands {
+            assert!(
+                DISPATCH_COMMANDS.contains(command),
+                "dispatch command `{command}` is missing from DISPATCH_COMMANDS"
+            );
+        }
+        for command in DISPATCH_COMMANDS {
+            assert!(
+                source_commands.contains(command),
+                "DISPATCH_COMMANDS contains `{command}` but dispatch has no matching arm"
+            );
+        }
+
+        let top_help = command_help(None);
+        for command in DISPATCH_COMMANDS {
+            assert!(
+                top_help.contains(command),
+                "top-level --help is missing dispatch command `{command}`"
+            );
+            let command_help = command_help(Some(command));
+            assert!(
+                command_help.contains("usage: team-agent") && command_help.contains(command),
+                "`team-agent {command} --help` must show command-specific usage, got {command_help:?}"
+            );
+        }
+        for command in SPEC_ONLY_HELP_COMMANDS {
+            assert!(
+                top_help.contains(command),
+                "top-level --help is missing spec-only help command `{command}`"
+            );
+        }
+    }
+
+    #[test]
+    fn t0_help_catalog_lists_command_flags() {
+        for (command, flags) in [
+            ("quick-start", &["--workspace", "--team-id", "--yes", "--fresh", "--json"][..]),
+            ("send", &["--workspace", "--team", "--targets", "--watch-result", "--timeout", "--json"][..]),
+            ("status", &["--workspace", "--summary", "--json", "--detail"][..]),
+            ("shutdown", &["--workspace", "--team", "--keep-logs", "--json"][..]),
+            ("restart", &["--team", "--allow-fresh", "--json"][..]),
+            ("start-agent", &["--workspace", "--team", "--force", "--allow-fresh", "--no-display", "--json"][..]),
+            ("reset-agent", &["--workspace", "--team", "--discard-session", "--no-display", "--json"][..]),
+            ("add-agent", &["--role-file", "--workspace", "--team", "--no-display", "--json"][..]),
+            ("fork-agent", &["--as", "--label", "--workspace", "--team", "--no-display", "--json"][..]),
+            ("remove-agent", &["--workspace", "--team", "--from-spec", "--confirm", "--force", "--json"][..]),
+            ("doctor", &["--workspace", "--team", "--gate", "--fix-schema", "--cleanup-orphans", "--json"][..]),
+            ("collect", &["--workspace", "--result-file", "--json"][..]),
+            ("repair-state", &["--task", "--status", "--assignee", "--workspace", "--json"][..]),
+            ("wait-ready", &["--workspace", "--timeout", "--json"][..]),
+            ("peek", &["--workspace", "--tail", "--allow-raw-screen", "--json"][..]),
+            ("coordinator", &["--workspace", "--once", "--tick-interval"][..]),
+        ] {
+            let help = command_help(Some(command));
+            for flag in flags {
+                assert!(help.contains(flag), "`team-agent {command} --help` is missing {flag}");
+            }
+        }
+    }
+
     #[test]
     fn ux_quick_start_workspace_resolves_relative_agents_dir_inside_workspace() {
         let cwd = tmp_workspace();

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

@@ -28,6 +28,7 @@
 // §10:CLI 命令实现层禁 unwrap/expect/panic(unimplemented!() stub 不被拦);tests 子模块各自 allow。
 #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
 
+use std::io::Read;
 use std::path::{Path, PathBuf};
 
 use serde::{Deserialize, Serialize};
@@ -137,10 +138,12 @@ pub mod lifecycle_port {
         team: Option<&str>,
         transport: &dyn crate::transport::Transport,
     ) -> Result<Value, CliError> {
-        let wp = crate::coordinator::WorkspacePath::new(workspace.to_path_buf());
+        let run_workspace = crate::model::paths::canonical_run_workspace(workspace)
+            .map_err(|e| CliError::Runtime(e.to_string()))?;
+        let wp = crate::coordinator::WorkspacePath::new(run_workspace.clone());
         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 mut state = crate::state::persist::load_runtime_state(&run_workspace)?;
         let session_name = state
             .get("session_name")
             .and_then(Value::as_str)
@@ -156,8 +159,8 @@ pub mod lifecycle_port {
             false
         };
         mark_agents_stopped(&mut state);
-        crate::state::persist::save_runtime_state(workspace, &state)?;
-        let _event = crate::event_log::EventLog::new(workspace)
+        crate::state::persist::save_runtime_state(&run_workspace, &state)?;
+        let _event = crate::event_log::EventLog::new(&run_workspace)
             .write(
                 "lifecycle.shutdown",
                 json!({
@@ -459,13 +462,46 @@ pub mod lifecycle_port {
                 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,
-            }),
+                worker_readiness,
+            } => {
+                // BUG-7: never emit bare "ready" while worker tool-load is unverified.
+                // The summary string + a structured `worker_readiness` block tell the
+                // caller exactly which agents are unhealthy (Degraded) or that the
+                // tool-set load has not been confirmed yet (PendingToolLoad).
+                let (summary, ok, readiness_json) = match &worker_readiness {
+                    crate::lifecycle::QuickStartReadiness::Degraded { unhealthy_agents } => (
+                        format!(
+                            "quick-start degraded: {}; unhealthy: {}",
+                            session_name.as_str(),
+                            unhealthy_agents.join(",")
+                        ),
+                        false,
+                        json!({
+                            "state": "degraded",
+                            "unhealthy_agents": unhealthy_agents,
+                        }),
+                    ),
+                    crate::lifecycle::QuickStartReadiness::PendingToolLoad => (
+                        format!(
+                            "quick-start launched (worker tool load unverified): {}",
+                            session_name.as_str()
+                        ),
+                        true,
+                        json!({
+                            "state": "pending_tool_load",
+                            "reason": "worker MCP tool set load not yet confirmed; run `team-agent doctor` or wait for first worker turn",
+                        }),
+                    ),
+                };
+                json!({
+                    "ok": ok,
+                    "summary": summary,
+                    "session_name": session_name.as_str(),
+                    "dry_run": launch.dry_run,
+                    "next_actions": next_actions,
+                    "worker_readiness": readiness_json,
+                })
+            }
             crate::lifecycle::QuickStartReport::ExistingRuntime {
                 team,
                 session_name,
@@ -595,35 +631,65 @@ pub mod diagnose_port {
 
     fn secret_scan(workspace: &Path) -> Value {
         let mut findings = Vec::new();
-        scan_secret_dir(workspace, workspace, &mut findings);
+        let mut scanned = 0usize;
+        scan_secret_dir(workspace, workspace, 0, &mut scanned, &mut findings);
         json!({
             "ok": findings.is_empty(),
             "findings": findings,
         })
     }
 
-    fn scan_secret_dir(root: &Path, dir: &Path, findings: &mut Vec<Value>) {
+    const SECRET_SCAN_MAX_DEPTH: usize = 4;
+    const SECRET_SCAN_MAX_ENTRIES: usize = 512;
+    const SECRET_SCAN_MAX_FILE_BYTES: u64 = 128 * 1024;
+
+    fn scan_secret_dir(root: &Path, dir: &Path, depth: usize, scanned: &mut usize, findings: &mut Vec<Value>) {
+        if depth > SECRET_SCAN_MAX_DEPTH || *scanned >= SECRET_SCAN_MAX_ENTRIES {
+            return;
+        }
         let Ok(entries) = std::fs::read_dir(dir) else {
             return;
         };
         for entry in entries.flatten() {
+            if *scanned >= SECRET_SCAN_MAX_ENTRIES {
+                return;
+            }
+            *scanned = scanned.saturating_add(1);
             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);
+            let Ok(file_type) = entry.file_type() else {
+                continue;
+            };
+            if file_type.is_dir() {
+                scan_secret_dir(root, &path, depth.saturating_add(1), scanned, findings);
                 continue;
             }
-            scan_secret_file(root, &path, findings);
+            if file_type.is_file() {
+                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 {
+        let Ok(metadata) = std::fs::metadata(path) else {
+            return;
+        };
+        if !metadata.is_file() || metadata.len() > SECRET_SCAN_MAX_FILE_BYTES {
+            return;
+        }
+        let Ok(file) = std::fs::File::open(path) else {
             return;
         };
+        let mut text = String::new();
+        if std::io::Read::take(file, SECRET_SCAN_MAX_FILE_BYTES)
+            .read_to_string(&mut text)
+            .is_err()
+        {
+            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);

package/crates/team-agent/src/coordinator/health.rs

@@ -3,6 +3,7 @@
 use std::io::{Read, Seek, SeekFrom};
 use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
+use std::time::Duration;
 
 use serde_json::Value;
 use thiserror::Error;
@@ -119,6 +120,9 @@ pub fn start_coordinator(workspace: &WorkspacePath) -> Result<StartReport, Start
 pub fn stop_coordinator(workspace: &WorkspacePath) -> Result<StopReport, StopError> {
     let pid_path = coordinator_pid_path(workspace);
     if !pid_path.exists() {
+        if let Some(report) = stop_discovered_coordinators(workspace)? {
+            return Ok(report);
+        }
         return Ok(StopReport {
             ok: true,
             status: StopOutcome::Missing,
@@ -158,6 +162,123 @@ pub fn stop_coordinator(workspace: &WorkspacePath) -> Result<StopReport, StopErr
     })
 }
 
+fn stop_discovered_coordinators(
+    workspace: &WorkspacePath,
+) -> Result<Option<StopReport>, StopError> {
+    let pids = discover_coordinator_pids(workspace);
+    if pids.is_empty() {
+        return Ok(None);
+    }
+
+    let mut stopped = None;
+    let mut failed = None;
+    for pid in pids {
+        if terminate_pid(pid) {
+            stopped.get_or_insert(pid);
+        } else {
+            failed.get_or_insert(pid);
+        }
+    }
+    remove_file_if_exists(&coordinator_meta_path(workspace))?;
+
+    if let Some(pid) = stopped {
+        Ok(Some(StopReport {
+            ok: true,
+            status: StopOutcome::Stopped,
+            pid: Some(pid),
+        }))
+    } else {
+        Ok(Some(StopReport {
+            ok: false,
+            status: StopOutcome::KillFailed,
+            pid: failed,
+        }))
+    }
+}
+
+fn discover_coordinator_pids(workspace: &WorkspacePath) -> Vec<Pid> {
+    let output = match Command::new("ps")
+        .args(["-axo", "pid=,command="])
+        .output()
+    {
+        Ok(output) if output.status.success() => output,
+        _ => return Vec::new(),
+    };
+    let text = String::from_utf8_lossy(&output.stdout);
+    let candidates = workspace_match_candidates(workspace.as_path());
+    text.lines()
+        .filter_map(|line| parse_ps_command_line(line))
+        .filter(|(pid, command)| {
+            *pid != std::process::id()
+                && coordinator_command_matches_workspace(command, &candidates)
+        })
+        .map(|(pid, _)| Pid::new(pid))
+        .collect()
+}
+
+fn parse_ps_command_line(line: &str) -> Option<(u32, &str)> {
+    let line = line.trim_start();
+    let split = line
+        .find(char::is_whitespace)
+        .unwrap_or(line.len());
+    let pid = line.get(..split)?.trim().parse::<u32>().ok()?;
+    let command = line.get(split..)?.trim();
+    Some((pid, command))
+}
+
+fn workspace_match_candidates(workspace: &Path) -> Vec<String> {
+    let mut candidates = vec![workspace.to_string_lossy().to_string()];
+    if let Ok(canonical) = workspace.canonicalize() {
+        let text = canonical.to_string_lossy().to_string();
+        if !candidates.iter().any(|candidate| candidate == &text) {
+            candidates.push(text);
+        }
+    }
+    candidates
+}
+
+fn coordinator_command_matches_workspace(command: &str, workspaces: &[String]) -> bool {
+    command
+        .split_whitespace()
+        .any(|token| token == "team-agent" || token.ends_with("/team-agent"))
+        && command.split_whitespace().any(|token| token == "coordinator")
+        && command.contains("--workspace")
+        && workspaces.iter().any(|workspace| command.contains(workspace))
+}
+
+fn terminate_pid(pid: Pid) -> bool {
+    if pid_is_running(pid).ok() == Some(false) {
+        return true;
+    }
+    if !send_signal(pid, libc::SIGTERM) {
+        return false;
+    }
+    if wait_until_not_running(pid, Duration::from_millis(750)) {
+        return true;
+    }
+    send_signal(pid, libc::SIGKILL) && wait_until_not_running(pid, Duration::from_millis(750))
+}
+
+fn send_signal(pid: Pid, signal: libc::c_int) -> bool {
+    let Ok(pid_t) = libc::pid_t::try_from(pid.get()) else {
+        return false;
+    };
+    unsafe { libc::kill(pid_t, signal) == 0 }
+}
+
+fn wait_until_not_running(pid: Pid, timeout: Duration) -> bool {
+    let start = std::time::Instant::now();
+    loop {
+        if pid_is_running(pid).ok() != Some(true) {
+            return true;
+        }
+        if start.elapsed() >= timeout {
+            return false;
+        }
+        std::thread::sleep(Duration::from_millis(25));
+    }
+}
+
 // ===========================================================================
 // metadata 身份原语(metadata.py)—— 自由函数面
 // ===========================================================================

package/crates/team-agent/src/leader/lease.rs

@@ -424,7 +424,8 @@ fn claim_lease_no_incident_with_target(
         ));
     }
     let non_empty_caller_pane = NonEmptyPaneId::try_from_pane(caller_pane)?;
-    if bound_pane_id.as_deref() == Some(caller_pane.as_str()) {
+    let bound_endpoint_matches_caller = bound_endpoint_matches_current_process(state);
+    if bound_pane_id.as_deref() == Some(caller_pane.as_str()) && bound_endpoint_matches_caller {
         return Ok(LeaseResult {
             ok: true,
             status: LeaseStatus::AlreadyBound,
@@ -438,7 +439,12 @@ fn claim_lease_no_incident_with_target(
     }
     let owner_live = bound_pane_id
         .as_deref()
-        .is_some_and(|pane| liveness.liveness(pane) == PaneLiveness::Live);
+        .is_some_and(|pane| {
+            if pane == caller_pane.as_str() && !bound_endpoint_matches_caller {
+                return false;
+            }
+            liveness.liveness(pane) == PaneLiveness::Live
+        });
     if owner_live && !confirm {
         emit_lease_refusal(
             event_log,
@@ -596,6 +602,20 @@ fn bound_pane(state: &Value) -> Option<String> {
         .or_else(|| get_path_str(state, &["team_owner", "pane_id"]).filter(|v| !v.is_empty()))
 }
 
+fn bound_endpoint_matches_current_process(state: &Value) -> bool {
+    let Some(bound) = get_path_str(state, &["leader_receiver", "tmux_socket"]).filter(|v| !v.is_empty()) else {
+        return true;
+    };
+    let Some(current) = crate::tmux_backend::socket_name_from_tmux_env() else {
+        return false;
+    };
+    tmux_endpoints_match(&bound, &current)
+}
+
+fn tmux_endpoints_match(bound: &str, current: &str) -> bool {
+    bound == current
+}
+
 fn prior_provider(state: &Value) -> Provider {
     get_path_str(state, &["leader_receiver", "provider"])
         .or_else(|| get_path_str(state, &["team_owner", "provider"]))
@@ -844,6 +864,7 @@ fn make_receiver(
         pane_index: target.as_ref().and_then(|t| t.pane_index.map(|v| v.to_string())),
         pane_tty: target.as_ref().and_then(|t| t.tty.clone()),
         pane_current_command: target.as_ref().and_then(|t| t.current_command.clone()),
+        tmux_socket: crate::tmux_backend::socket_name_from_tmux_env(),
         fingerprint: target.as_ref().map(receiver_fingerprint),
         leader_session_uuid: Some(uuid.clone()),
         owner_epoch: Some(epoch),

package/crates/team-agent/src/leader/rediscover/tests.rs

@@ -31,6 +31,7 @@ fn receiver(pane: &str, uuid: &str, epoch: u64) -> LeaderReceiver {
         pane_index: None,
         pane_tty: None,
         pane_current_command: None,
+        tmux_socket: None,
         fingerprint: None,
         leader_session_uuid: serde_json::from_value(Value::String(uuid.to_string())).ok(),
         owner_epoch: Some(OwnerEpoch(epoch)),

package/crates/team-agent/src/leader/rediscover.rs

@@ -1013,6 +1013,7 @@ fn receiver_from_candidate(
         pane_index: target.pane_index.clone(),
         pane_tty: target.tty.clone(),
         pane_current_command: target.current_command.clone(),
+        tmux_socket: prior.tmux_socket.clone(),
         fingerprint: target.fingerprint.clone(),
         leader_session_uuid: uuid,
         owner_epoch: Some(epoch),
@@ -1035,6 +1036,7 @@ fn empty_prior(provider: Provider, epoch: OwnerEpoch) -> LeaderReceiver {
         pane_index: None,
         pane_tty: None,
         pane_current_command: None,
+        tmux_socket: None,
         fingerprint: None,
         leader_session_uuid: None,
         owner_epoch: Some(epoch),