@team-agent/installer 0.5.114 → 0.5.116

package/Cargo.lock

@@ -727,7 +727,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.114"
+version = "0.5.116"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -11,7 +11,7 @@ exclude = ["crates/team-agent-contract"]
 
 [workspace.package]
 edition = "2021"
-version = "0.5.114"
+version = "0.5.116"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

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

@@ -448,8 +448,8 @@ pub(super) fn command_help(command: Option<&str>) -> String {
             "team-agent inbox leader -n 3\nteam-agent inbox worker --limit 5\nteam-agent inbox leader --workspace . --team help-demo --json", "Wait for a natural reply, then check team-agent status if needed. Do not inspect worker terminal content."),
         "status" => ("Optional <agent> selects one agent. --summary/--detail retain compatibility and do not add fields.\nNine fields: name/provider/model/effort/runtime_status/activity/health/session_name/tmux_command.\nRuntime, activity and health are distinct. unknown means insufficient evidence; null means unset. No default model is guessed.",
             "team-agent status\nteam-agent status worker\nteam-agent status --workspace . --team help-demo --json", "Read replies with team-agent inbox leader -n 3; diagnose problems with team-agent doctor --workspace ."),
-        "models" => ("--provider selects the provider, default pi. QUERY or --search performs keyword search; they are mutually exclusive.\nUse cursor_agent for Cursor. Copilot has no model discovery entrypoint here. Results come from the native catalog, not guesses.",
-            "team-agent models --provider pi\nteam-agent models --provider pi --search luna\nteam-agent models --provider cursor_agent --json", "Use the exact returned model name in a role file or add-agent --model before launch."),
+        "models" => ("--provider selects the provider, default pi. QUERY or --search performs keyword search; they are mutually exclusive.\nUse cursor for the contract-native Cursor catalog; cursor_agent retains the legacy entrypoint. Copilot has no model discovery entrypoint here. Results come from the native catalog, not guesses.",
+            "team-agent models --provider pi\nteam-agent models --provider pi --search luna\nteam-agent models --provider cursor --json", "Use the exact returned model name in a role file or add-agent --model before launch."),
         "restart" => ("WORKSPACE defaults to the current project; saved sessions are preferred.\nUse --allow-fresh only after explicit authorization to lose saved context. --session-converge-deadline sets the wait in seconds.",
             "team-agent restart .\nteam-agent restart . --team help-demo --json", "Check status after restart. Obtain authorization before creating a fresh session; takeover is not a substitute for restart."),
         "shutdown" => ("Shuts down only the selected workspace/team. Logs are retained by default; --keep-logs remains compatible.\n--json reports scope, degradation and owned residuals. Success does not mean other teams were shut down.",

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

@@ -57,6 +57,8 @@ pub(crate) const STATUS_REMINDER: &str =
     "Next: use team-agent inbox leader -n 3 for replies. Status is not proof of task completion; do not inspect worker terminal content.";
 
 pub mod adapters;
+#[cfg(unix)]
+mod shutdown_socket;
 pub mod attach_app_server_leader;
 pub mod diagnose;
 pub mod emit;
@@ -1193,13 +1195,17 @@ pub mod lifecycle_port {
         }
         let workspace_socket = crate::tmux_backend::socket_name_for_workspace(workspace);
         let source = state.get("tmux_socket_source").and_then(Value::as_str);
-        let owned = source == Some("workspace")
-            || source.is_none()
-                && endpoint_matches_workspace_socket(&endpoint, workspace, &workspace_socket);
+        let owned = (source == Some("workspace") || source.is_none())
+            && endpoint_matches_workspace_socket(&endpoint, workspace, &workspace_socket);
         if !owned {
             return None;
         }
         let socket_file = socket_file_for_endpoint(&endpoint);
+        if socket_file.as_ref().and_then(|path| path.file_name())
+            != Some(std::ffi::OsStr::new(&workspace_socket))
+        {
+            return None;
+        }
         Some(OwnedShutdownEndpoint {
             endpoint,
             socket_file,
@@ -1234,9 +1240,18 @@ pub mod lifecycle_port {
         event_log: &crate::event_log::EventLog,
     ) -> OwnedEndpointCleanup {
         let mut cleanup = OwnedEndpointCleanup::default();
-        cleanup.remaining_sessions = transport
-            .list_targets()
-            .unwrap_or_default()
+        let targets = match transport.list_targets() {
+            Ok(targets) => targets,
+            Err(error) => {
+                cleanup.error = Some(format!("owned endpoint session probe failed: {error}"));
+                if let Some(path) = endpoint.socket_file.as_ref() {
+                    cleanup.skipped_files.push(path.display().to_string());
+                    cleanup.residual_files.push(path.display().to_string());
+                }
+                return cleanup;
+            }
+        };
+        cleanup.remaining_sessions = targets
             .into_iter()
             .map(|pane| pane.session.as_str().to_string())
             .collect::<std::collections::BTreeSet<_>>()
@@ -1257,20 +1272,136 @@ pub mod lifecycle_port {
             );
             return cleanup;
         }
-        // Endpoint ownership is not sufficient authority to tear down a tmux
-        // server: an endpoint can be shared after launch.  Leave both the
-        // server and its socket file intact; only explicitly owned sessions
-        // are removed above.
+        // Empty enumeration is not server-death proof. Never kill-server:
+        // remove only the exact workspace socket after an independent refused
+        // nonblocking connection and fresh owned parent/socket inode fences.
+        #[cfg(unix)]
+        if let Some(path) = endpoint.socket_file.as_ref() {
+            use super::shutdown_socket::{remove_dead_socket, SocketCleanup};
+            match remove_dead_socket(path) {
+                Ok(SocketCleanup::Removed) => {
+                    cleanup.removed_files.push(path.display().to_string());
+                }
+                Ok(SocketCleanup::Absent) => {}
+                Ok(SocketCleanup::Preserved) => {
+                    cleanup.skipped_files.push(path.display().to_string());
+                    cleanup.residual_files.push(path.display().to_string());
+                }
+                Err(error) => {
+                    cleanup.skipped_files.push(path.display().to_string());
+                    cleanup.residual_files.push(path.display().to_string());
+                    cleanup.error = Some(format!("owned socket cleanup refused: {error}"));
+                }
+            }
+        }
         let _ = event_log.write(
-            "shutdown.owned_endpoint_cleanup_skipped",
+            "shutdown.owned_endpoint_cleanup",
             json!({
                 "endpoint": endpoint.endpoint,
-                "reason": "server_and_socket_cleanup_disabled_fail_closed",
+                "removed_files": cleanup.removed_files,
+                "skipped_files": cleanup.skipped_files,
+                "residual_files": cleanup.residual_files,
+                "error": cleanup.error,
             }),
         );
         cleanup
     }
 
+    #[cfg(all(test, unix))]
+    #[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+    mod shutdown_socket_tests {
+        use super::*;
+        use crate::transport::test_support::OfflineTransport;
+        use crate::transport::{PaneId, PaneInfo};
+        use std::os::unix::fs::PermissionsExt;
+        use std::os::unix::net::UnixListener;
+
+        #[test]
+        fn shutdown_socket_selection_rejects_shared_external_and_false_workspace_sources() {
+            let workspace = Path::new("/tmp").join(format!("ta-shutdown-select-{}-{}",
+                std::process::id(), chrono::Utc::now().timestamp_nanos_opt().unwrap()));
+            std::fs::create_dir(&workspace).unwrap();
+            let workspace = workspace.canonicalize().unwrap();
+            let name = crate::tmux_backend::socket_name_for_workspace(&workspace);
+            let transport = OfflineTransport::new();
+            let selected = json!({"tmux_socket": name, "tmux_socket_source": "workspace"});
+            assert!(owned_shutdown_endpoint(&workspace, &selected, &transport).is_some());
+            for delta in [
+                json!({"is_external_leader": true}),
+                json!({"tmux_socket_source": "leader_env"}),
+                json!({"tmux_socket": "default"}),
+                json!({"tmux_socket": "/foreign/ta-not-this-workspace"}),
+                json!({"tmux_socket_source": "shared"}),
+            ] {
+                let mut state = selected.clone();
+                state.as_object_mut().unwrap().extend(delta.as_object().unwrap().clone());
+                assert!(owned_shutdown_endpoint(&workspace, &state, &transport).is_none());
+            }
+            std::fs::remove_dir(workspace).unwrap();
+        }
+
+        #[test]
+        fn shutdown_socket_cleanup_removes_only_dead_socket_and_reports_live_residual() {
+            let root = Path::new("/tmp").join(format!("ta-root-shutdown-{}-{}",
+                std::process::id(), chrono::Utc::now().timestamp_nanos_opt().unwrap()));
+            std::fs::create_dir(&root).unwrap();
+            std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o700)).unwrap();
+            let root = root.canonicalize().unwrap();
+            let path = root.join("owned.sock");
+            let endpoint = OwnedShutdownEndpoint {
+                endpoint: path.display().to_string(), socket_file: Some(path.clone()),
+            };
+            let log = crate::event_log::EventLog::new(&root);
+            let transport = OfflineTransport::new();
+            let listener = UnixListener::bind(&path).unwrap();
+            let live = cleanup_owned_empty_endpoint(&transport, &endpoint, &log);
+            assert_eq!(live.residual_files, vec![path.display().to_string()]);
+            assert!(live.removed_files.is_empty());
+            assert!(path.exists());
+            drop(listener);
+            let dead = cleanup_owned_empty_endpoint(&transport, &endpoint, &log);
+            assert_eq!(dead.removed_files, vec![path.display().to_string()]);
+            assert!(dead.residual_files.is_empty());
+            assert!(dead.error.is_none());
+            assert!(!path.exists());
+            assert!(!transport.calls().contains(&"kill_server"));
+            std::fs::remove_dir_all(root).unwrap();
+        }
+
+        #[test]
+        fn shutdown_socket_cleanup_preserves_sibling_and_unknown_session_probe() {
+            let root = Path::new("/tmp").join(format!("ta-shutdown-sibling-{}-{}",
+                std::process::id(), chrono::Utc::now().timestamp_nanos_opt().unwrap()));
+            std::fs::create_dir(&root).unwrap();
+            std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o700)).unwrap();
+            let root = root.canonicalize().unwrap();
+            let path = root.join("owned.sock");
+            drop(UnixListener::bind(&path).unwrap());
+            let endpoint = OwnedShutdownEndpoint {
+                endpoint: path.display().to_string(), socket_file: Some(path.clone()),
+            };
+            let log = crate::event_log::EventLog::new(&root);
+            let sibling = OfflineTransport::new().with_targets(vec![PaneInfo {
+                pane_id: PaneId::new("%1"), session: crate::transport::SessionName::new("foreign"),
+                window_index: None, window_name: None, pane_index: None, tty: None,
+                current_command: None, current_path: None, active: true, pane_pid: None,
+                leader_env: std::collections::BTreeMap::new(),
+            }]);
+            let kept = cleanup_owned_empty_endpoint(&sibling, &endpoint, &log);
+            assert_eq!(kept.remaining_sessions, vec!["foreign".to_string()]);
+            assert!(kept.removed_files.is_empty());
+            assert!(path.exists());
+            let failed = OfflineTransport::new().with_list_targets_error("unknown");
+            let refused = cleanup_owned_empty_endpoint(&failed, &endpoint, &log);
+            assert!(refused.error.is_some());
+            assert_eq!(refused.residual_files, vec![path.display().to_string()]);
+            assert!(path.exists());
+            assert!(!sibling.calls().contains(&"kill_server"));
+            assert!(!failed.calls().contains(&"kill_server"));
+            std::fs::remove_dir_all(root).unwrap();
+        }
+    }
+
     pub fn shutdown_with_transport(
         workspace: &Path,
         keep_logs: bool,
@@ -3126,9 +3257,9 @@ pub mod lifecycle_port {
         session_converge_deadline_ms: Option<u64>,
     ) -> Result<Value, CliError> {
         #[cfg(unix)]
-        crate::contract_runtime::framework::require_legacy_lifecycle(
-            workspace, team, None, "restart",
-        )?;
+        if let Some(receipt) = crate::contract_runtime::commands::restart(workspace, team)? {
+            return Ok(receipt);
+        }
         match crate::lifecycle::restart_with_session_convergence_deadline(
             workspace,
             allow_fresh,
@@ -3149,6 +3280,10 @@ pub mod lifecycle_port {
         team: Option<&str>,
         role_config: &crate::lifecycle::role_config::RoleConfigPatch,
     ) -> Result<Value, CliError> {
+        #[cfg(unix)]
+        if let Some(receipt) = crate::contract_runtime::commands::start_agent(workspace, team, agent, role_config)? {
+            return Ok(receipt);
+        }
         #[cfg(unix)]
         {
             crate::contract_runtime::framework::require_legacy_lifecycle(
@@ -3228,13 +3363,14 @@ pub mod lifecycle_port {
         agent: &str,
         team: Option<&str>,
     ) -> Result<Value, CliError> {
+        #[cfg(unix)]
+        if let Some(receipt) = crate::contract_runtime::commands::stop_agent(workspace, team, agent)? {
+            return Ok(receipt);
+        }
         let agent_id = crate::model::ids::AgentId::new(agent);
         #[cfg(unix)]
         crate::contract_runtime::framework::require_legacy_lifecycle(
-            workspace,
-            team,
-            Some(agent),
-            "stop-agent",
+            workspace, team, Some(agent), "stop-agent",
         )?;
         match crate::lifecycle::stop_agent(workspace, &agent_id, team) {
             Ok(report) => Ok(json!({"ok": true, "agent_id": agent, "stopped": report.stopped})),

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

@@ -438,6 +438,57 @@ mod tests {
         assert_eq!(models[0]["default"], true);
     }
 
+    #[cfg(unix)]
+    #[test]
+    fn cursor_contract_catalog_uses_public_launcher_metadata_then_exact_ids() {
+        let program = fixture_program("cursor-agent", r#"
+test "$#" = 1 || exit 9
+case "$1" in
+  --version) printf '%s\n' '2026.10.01-a1b2c3' ;;
+  --list-models) exec /bin/cat "$TEAM_AGENT_MODELS_FIXTURE" ;;
+  *) exit 9 ;;
+esac"#);
+        let mut cursor = CliFixture::new(program);
+        let response = cursor.program.with_extension("stdout");
+        std::fs::write(&response, include_bytes!("../provider/testdata/cursor-list-models-native.stdout")).unwrap();
+        cursor.response = Some(response);
+        let output = run_public_models_cli(&cursor.program, cursor.response.as_deref(),
+            &["models", "--provider", "cursor", "--search", "gpt-5.6-luna-xhigh", "--json"]);
+        let text = public_cli_text(&output);
+        let calls = std::fs::read_to_string(cursor.program.with_extension("count")).unwrap();
+        assert!(output.status.success(), "{text}");
+        assert_eq!(calls, "1:--version\n1:--list-models\n");
+        let value: Value = serde_json::from_str(text.trim()).unwrap();
+        assert_eq!(value["provider"], "cursor");
+        assert_eq!(value["auth"], "unknown");
+        assert_eq!(value["source"]["schema"], "cursor-list-models-text-v1");
+        assert_eq!(value["source"]["identity_scope"], "catalog_only");
+        assert!(value["models"].as_array().unwrap().iter().any(|row| row["model_id"] == "gpt-5.6-luna-xhigh"));
+        assert!(value["models"].as_array().unwrap().iter().all(|row| row["role_model"] == row["model_id"]));
+        assert!(value["current_role_model"].is_null());
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn cursor_contract_bad_version_has_no_legacy_entrypoint_fallback() {
+        use std::os::unix::fs::PermissionsExt;
+        let cursor = CliFixture::new(fixture_program("cursor-agent", "printf '%s\\n' 'Cursor release unknown'"));
+        let legacy = cursor.program.parent().unwrap().join("agent");
+        std::fs::write(&legacy, "#!/bin/sh\nprintf 'called' > \"$0.called\"\nexit 9\n").unwrap();
+        std::fs::set_permissions(&legacy, std::fs::Permissions::from_mode(0o700)).unwrap();
+        let output = run_public_models_cli(&cursor.program, None,
+            &["models", "--provider", "cursor", "--json"]);
+        let text = public_cli_text(&output);
+        assert!(!output.status.success(), "{text}");
+        assert_eq!(std::fs::read_to_string(cursor.program.with_extension("count")).unwrap(), "1:--version\n");
+        assert!(!legacy.with_extension("called").exists());
+        let value: Value = serde_json::from_str(text.trim()).unwrap();
+        assert_eq!(value["provider"], "cursor");
+        assert_eq!(value["ok"], false);
+        assert_eq!(value["models"], json!([]));
+        assert!(value["error"].as_str().unwrap().contains("Cursor release unknown"));
+    }
+
     #[cfg(unix)]
     #[test]
     fn grok_public_cli_uses_native_catalog_and_keeps_shared_projection() {
@@ -1322,7 +1373,7 @@ mod tests {
             ),
             ExitCode::Error
         );
-        let usage = "team-agent models [--provider pi|cursor_agent|codex|claude|claude_code|grok|kiro] [QUERY|--search TEXT] [--json]";
+        let usage = "team-agent models [--provider pi|cursor|cursor_agent|codex|claude|claude_code|grok|kiro] [QUERY|--search TEXT] [--json]";
         assert_eq!(crate::cli::spec::command_spec("models").unwrap().usage, usage);
         assert!(crate::cli::emit::command_help(Some("models")).contains(usage));
     }

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

@@ -0,0 +1,288 @@
+//! Remove only a positively dead, owned Unix socket; never stop its server.
+use std::ffi::CString;
+use std::fs::{File, Metadata, OpenOptions};
+use std::io;
+use std::os::fd::{AsRawFd, FromRawFd, OwnedFd};
+use std::os::unix::ffi::OsStrExt;
+use std::os::unix::fs::{FileTypeExt, MetadataExt, OpenOptionsExt};
+use std::path::Path;
+
+#[derive(Debug, PartialEq, Eq)]
+pub(super) enum SocketCleanup {
+    Absent,
+    Removed,
+    Preserved,
+}
+
+pub(super) fn remove_dead_socket(path: &Path) -> io::Result<SocketCleanup> {
+    remove_with_probe(path, listener_refused)
+}
+
+fn identity(metadata: &Metadata) -> (u64, u64, u32, u32, u64) {
+    (
+        metadata.dev(),
+        metadata.ino(),
+        metadata.mode(),
+        metadata.uid(),
+        metadata.nlink(),
+    )
+}
+
+fn invalid(reason: &str) -> io::Error {
+    io::Error::new(io::ErrorKind::PermissionDenied, reason)
+}
+
+fn remove_with_probe(
+    path: &Path,
+    probe: impl FnOnce(&Path) -> io::Result<bool>,
+) -> io::Result<SocketCleanup> {
+    let socket = match std::fs::symlink_metadata(path) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(SocketCleanup::Absent),
+        Err(error) => return Err(error),
+    };
+    // SAFETY: geteuid has no pointer arguments or ownership effects.
+    let uid = unsafe { libc::geteuid() };
+    if !socket.file_type().is_socket() || socket.uid() != uid || socket.nlink() != 1 {
+        return Err(invalid("shutdown socket is not an owned single-link socket"));
+    }
+    let parent = path
+        .parent()
+        .ok_or_else(|| invalid("socket parent missing"))?;
+    let metadata = std::fs::symlink_metadata(parent)?;
+    if !metadata.is_dir()
+        || metadata.uid() != uid
+        || metadata.mode() & 0o077 != 0
+        || parent.canonicalize()? != parent
+    {
+        return Err(invalid(
+            "shutdown socket parent is not a canonical private owned directory",
+        ));
+    }
+    let directory: File = OpenOptions::new()
+        .read(true)
+        .custom_flags(libc::O_DIRECTORY | libc::O_NOFOLLOW)
+        .open(parent)?;
+    if identity(&directory.metadata()?) != identity(&metadata) {
+        return Err(invalid("shutdown socket parent changed"));
+    }
+    if !probe(path)? {
+        return Ok(SocketCleanup::Preserved);
+    }
+    if identity(&std::fs::symlink_metadata(parent)?) != identity(&metadata) {
+        return Err(invalid("shutdown socket parent changed after death probe"));
+    }
+    let name = CString::new(
+        path.file_name()
+            .ok_or_else(|| invalid("socket name missing"))?
+            .as_bytes(),
+    )
+    .map_err(|_| invalid("socket name contains NUL"))?;
+    // SAFETY: stat is an all-integer C record; directory/name are valid for the call.
+    let mut fresh: libc::stat = unsafe { std::mem::zeroed() };
+    let result = unsafe {
+        libc::fstatat(
+            directory.as_raw_fd(),
+            name.as_ptr(),
+            &mut fresh,
+            libc::AT_SYMLINK_NOFOLLOW,
+        )
+    };
+    if result != 0 {
+        let error = io::Error::last_os_error();
+        return if error.kind() == io::ErrorKind::NotFound {
+            Ok(SocketCleanup::Absent)
+        } else {
+            Err(error)
+        };
+    }
+    if fresh.st_dev as u64 != socket.dev()
+        || fresh.st_ino as u64 != socket.ino()
+        || fresh.st_mode as u32 != socket.mode()
+        || fresh.st_uid != socket.uid()
+        || fresh.st_nlink as u64 != socket.nlink()
+    {
+        return Err(invalid("shutdown socket identity changed after death probe"));
+    }
+    // SAFETY: unlink is relative to the pinned owned directory and freshly fenced socket.
+    if unsafe { libc::unlinkat(directory.as_raw_fd(), name.as_ptr(), 0) } != 0 {
+        return Err(io::Error::last_os_error());
+    }
+    Ok(SocketCleanup::Removed)
+}
+
+fn listener_refused(path: &Path) -> io::Result<bool> {
+    // SAFETY: socket has no borrowed pointer arguments; successful fd ownership moves below.
+    let fd = unsafe { libc::socket(libc::AF_UNIX, libc::SOCK_STREAM, 0) };
+    if fd < 0 {
+        return Err(io::Error::last_os_error());
+    }
+    // SAFETY: fd is newly created and exclusively owned here.
+    let fd = unsafe { OwnedFd::from_raw_fd(fd) };
+    // SAFETY: fcntl acts on our owned fd; no pointer arguments.
+    if unsafe { libc::fcntl(fd.as_raw_fd(), libc::F_SETFD, libc::FD_CLOEXEC) } < 0 {
+        return Err(io::Error::last_os_error());
+    }
+    let flags = unsafe { libc::fcntl(fd.as_raw_fd(), libc::F_GETFL) };
+    if flags < 0 || unsafe { libc::fcntl(fd.as_raw_fd(), libc::F_SETFL, flags | libc::O_NONBLOCK) } < 0 {
+        return Err(io::Error::last_os_error());
+    }
+    // SAFETY: sockaddr_un is a C integer/byte record; zero initializes all fields/padding.
+    let mut address: libc::sockaddr_un = unsafe { std::mem::zeroed() };
+    address.sun_family = libc::AF_UNIX as libc::sa_family_t;
+    let bytes = path.as_os_str().as_bytes();
+    if bytes.len() >= address.sun_path.len() || bytes.contains(&0) {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "shutdown socket path exceeds Unix address bounds",
+        ));
+    }
+    for (target, byte) in address.sun_path.iter_mut().zip(bytes) {
+        *target = *byte as libc::c_char;
+    }
+    #[cfg(any(
+        target_os = "macos",
+        target_os = "ios",
+        target_os = "freebsd",
+        target_os = "openbsd",
+        target_os = "netbsd",
+        target_os = "dragonfly"
+    ))]
+    {
+        address.sun_len = std::mem::size_of_val(&address) as u8;
+    }
+    // SAFETY: address points to the fully initialized sockaddr_un of the supplied size.
+    let result = unsafe {
+        libc::connect(
+            fd.as_raw_fd(),
+            (&address as *const libc::sockaddr_un).cast(),
+            std::mem::size_of_val(&address) as libc::socklen_t,
+        )
+    };
+    if result == 0 {
+        return Ok(false);
+    }
+    match io::Error::last_os_error().raw_os_error() {
+        Some(libc::ECONNREFUSED) => Ok(true),
+        Some(libc::EINPROGRESS | libc::EAGAIN | libc::ENOENT) => Ok(false),
+        _ => Err(io::Error::last_os_error()),
+    }
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+mod tests {
+    use super::*;
+    use std::os::unix::fs::{symlink, PermissionsExt};
+    use std::os::unix::net::UnixListener;
+
+    struct Fixture(std::path::PathBuf);
+    impl Fixture {
+        fn new() -> Self {
+            let path = Path::new("/tmp").join(format!(
+                "ta-shutdown-{}-{}",
+                std::process::id(),
+                std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)
+                    .unwrap()
+                    .as_nanos()
+            ));
+            std::fs::create_dir(&path).unwrap();
+            std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o700)).unwrap();
+            Self(path.canonicalize().unwrap())
+        }
+        fn socket(&self) -> std::path::PathBuf {
+            self.0.join("owned.sock")
+        }
+    }
+    impl Drop for Fixture {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.0);
+        }
+    }
+
+    #[test]
+    fn shutdown_socket_removes_dead_inode_and_repeated_cleanup_is_absent() {
+        let fixture = Fixture::new();
+        let path = fixture.socket();
+        drop(UnixListener::bind(&path).unwrap());
+        assert_eq!(remove_dead_socket(&path).unwrap(), SocketCleanup::Removed);
+        assert!(!path.exists());
+        assert_eq!(remove_dead_socket(&path).unwrap(), SocketCleanup::Absent);
+    }
+
+    #[test]
+    fn shutdown_socket_preserves_live_listener_and_unsafe_objects() {
+        let fixture = Fixture::new();
+        let path = fixture.socket();
+        let listener = UnixListener::bind(&path).unwrap();
+        assert_eq!(remove_dead_socket(&path).unwrap(), SocketCleanup::Preserved);
+        assert!(path.exists());
+        drop(listener);
+        std::fs::remove_file(&path).unwrap();
+        std::fs::write(&path, b"not a socket").unwrap();
+        assert!(remove_dead_socket(&path).is_err());
+        std::fs::remove_file(&path).unwrap();
+        std::fs::create_dir(&path).unwrap();
+        assert!(remove_dead_socket(&path).is_err());
+        std::fs::remove_dir(&path).unwrap();
+        let target = fixture.0.join("target.sock");
+        drop(UnixListener::bind(&target).unwrap());
+        symlink(&target, &path).unwrap();
+        assert!(remove_dead_socket(&path).is_err());
+        assert!(target.exists());
+        std::fs::remove_file(&path).unwrap();
+        std::fs::hard_link(&target, &path).unwrap();
+        assert!(remove_dead_socket(&path).is_err());
+        std::fs::remove_file(&path).unwrap();
+        std::fs::set_permissions(&fixture.0, std::fs::Permissions::from_mode(0o755)).unwrap();
+        assert!(remove_dead_socket(&target).is_err());
+        assert!(target.exists());
+    }
+
+    #[test]
+    fn shutdown_socket_refuses_failed_probe_and_inode_or_parent_replacement() {
+        let fixture = Fixture::new();
+        let path = fixture.socket();
+        drop(UnixListener::bind(&path).unwrap());
+        assert!(remove_with_probe(&path, |_| Err(io::Error::new(
+            io::ErrorKind::PermissionDenied,
+            "probe failed"
+        )))
+        .is_err());
+        assert!(path.exists());
+        let original = fixture.0.join("original.sock");
+        assert!(remove_with_probe(&path, |_| {
+            std::fs::rename(&path, &original)?;
+            drop(UnixListener::bind(&path)?);
+            Ok(true)
+        })
+        .is_err());
+        assert!(path.exists());
+        assert_ne!(
+            std::fs::symlink_metadata(&path).unwrap().ino(),
+            std::fs::symlink_metadata(&original).unwrap().ino()
+        );
+        std::fs::remove_file(&path).unwrap();
+        drop(UnixListener::bind(&path).unwrap());
+        assert!(remove_with_probe(&path, |_| {
+            std::fs::remove_file(&path)?;
+            std::fs::write(&path, b"replacement")?;
+            Ok(true)
+        })
+        .is_err());
+        assert_eq!(std::fs::read(&path).unwrap(), b"replacement");
+        std::fs::remove_file(&path).unwrap();
+        drop(UnixListener::bind(&path).unwrap());
+        let moved = fixture.0.with_extension("old");
+        assert!(remove_with_probe(&path, |_| {
+            std::fs::rename(&fixture.0, &moved)?;
+            std::fs::create_dir(&fixture.0)?;
+            std::fs::set_permissions(&fixture.0, std::fs::Permissions::from_mode(0o700))?;
+            Ok(true)
+        })
+        .is_err());
+        assert!(moved.join("owned.sock").exists());
+        std::fs::remove_dir_all(moved).unwrap();
+    }
+}

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

@@ -113,7 +113,7 @@ pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
     CommandSpec { name: "quick-start", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::QuickStart), summary: "Create a team from role files; use restart for an initialized team", usage: "team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--team TEAM] [--name NAME] [--team-id TEAM] [--yes] [--backend tmux|conpty] [--json] [--detail]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
     CommandSpec { name: "send", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::Send), summary: "Send a task to a specified agent", usage: "team-agent send <agent> MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--mailbox] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: Some("a future compatibility release"), action: Some("Use team-agent send <agent> 'task message'; select scope with --workspace and --team"), governance: None },
     CommandSpec { name: "status", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::Status), summary: "Check agent status without reading conversation content", usage: "team-agent status [<agent>] [--workspace WORKSPACE] [--team TEAM] [--json] [--summary|--detail]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
-    CommandSpec { name: "models", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::Models), summary: "Discover model names supported by the native provider", usage: "team-agent models [--provider pi|cursor_agent|codex|claude|claude_code|grok|kiro] [QUERY|--search TEXT] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
+    CommandSpec { name: "models", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::Models), summary: "Discover model names supported by the native provider", usage: "team-agent models [--provider pi|cursor|cursor_agent|codex|claude|claude_code|grok|kiro] [QUERY|--search TEXT] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
     CommandSpec { name: "inbox", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::Inbox), summary: "Read agent replies", usage: "team-agent inbox <agent> [-n N|--limit N] [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },
     CommandSpec { name: "restart", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Restart), summary: "Restart an existing team using saved sessions when available", usage: "team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json] [--detail]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, sunset: None, action: None, governance: None },
     CommandSpec { name: "shutdown", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Shutdown), summary: "Shut down the selected team and report residual resources", usage: "team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, sunset: None, action: None, governance: None },

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

@@ -720,11 +720,18 @@ fn shutdown_invocation_diagnostic(
         );
     }
     let terminal = &appended[terminals[0]];
-    let expected_socket = socket.to_string_lossy();
-    if terminal["owned_endpoint"].as_str() != Some(expected_socket.as_ref()) {
+    // These diagnostics use deliberately unverified fixture paths, not the
+    // computed workspace endpoint. A source label cannot grant ownership.
+    let workspace_socket = crate::tmux_backend::socket_name_for_workspace(ws);
+    assert_ne!(
+        socket.file_name(),
+        Some(std::ffi::OsStr::new(&workspace_socket)),
+        "diagnostic fixture unexpectedly uses the owned workspace socket"
+    );
+    if !terminal["owned_endpoint"].is_null() {
         panic!(
-            "shutdown diagnostic endpoint mismatch: iteration={iteration} socket={} \
-             {result_summary}; terminal={terminal}",
+            "shutdown diagnostic falsely claimed fixture endpoint ownership: \
+             iteration={iteration} socket={} {result_summary}; terminal={terminal}",
             socket.display()
         );
     }