docs: add warning about orphaned child processes with --pid host

Add documentation and warning about a limitation of --pid host mode:
orphaned child processes may remain after container stop/rm.

This is a known podman limitation (containers/podman#11888), not something
introduced by our workaround. The workaround only kills the init process;
child processes that daemonized or backgrounded will persist.

Changes:
- Add warning in distrobox-create for rootless podman without --unshare-process
- Document the limitation in distrobox-stop and distrobox-rm comments
- Recommend --unshare-process for full process cleanup

Signed-off-by: xz-dev <xiangzhedev@gmail.com>

Author: xz-dev

distrobox-create

@@ -692,6 +692,13 @@ generate_create_command()
 	if [ "${unshare_process}" -eq 0 ]; then
 		result_command="${result_command}
 			--pid host"
+		# Warn about --pid host limitation in rootless podman mode.
+		# See: https://github.com/containers/podman/issues/11888
+		if [ "${rootful}" -eq 0 ] && echo "${container_manager}" | grep -q "podman"; then
+			printf >&2 "Warning: using --pid host with rootless podman.\n"
+			printf >&2 "Warning: orphaned child processes may remain after container stop.\n"
+			printf >&2 "Warning: consider using --unshare-process for full process cleanup.\n"
+		fi
 	fi
 	# Mount useful stuff inside the container.
 	# We also mount host's root filesystem to /run/host, to be able to syphon

distrobox-rm

@@ -401,15 +401,12 @@ delete_container()
 	# This sends the signal directly to the container's init process PID, bypassing
 	# the cgroup lookup issue.
 	#
-	# Note: distrobox-rm does not call distrobox-stop (by design, it relies on
-	# "podman rm --force" to handle stopping). A similar fix exists in distrobox-stop
-	# for the "distrobox stop" command.
-	if [ "${container_status}" = "running" ] && [ "${rootful}" -eq 0 ]; then
-		case "${container_manager}" in
-			*podman*)
-				${container_manager} kill "${container_name}" > /dev/null 2>&1 || :
-				;;
-		esac
+	# Note: This only kills the init process, not any orphaned child processes - this is
+	# a limitation of --pid host mode (see https://github.com/containers/podman/issues/11888).
+	# To ensure all processes are cleaned up, use --unshare-process when creating the container.
+	# distrobox-rm does not call distrobox-stop by design; a similar fix exists there.
+	if [ "${container_status}" = "running" ] && [ "${rootful}" -eq 0 ] && echo "${container_manager}" | grep -q "podman"; then
+		${container_manager} kill "${container_name}" > /dev/null 2>&1 || :
 	fi
 	# shellcheck disable=SC2086,SC2248
 	${container_manager} rm ${force_flag} --volumes "${container_name}"

distrobox-stop

@@ -295,13 +295,13 @@ case "${response}" in
 			# In rootless mode, podman stop uses "crun kill --all" which fails when
 			# cgroup-path is empty (which happens with --pid host, the distrobox default).
 			# Using "kill" first (which uses "crun kill" without --all) ensures the
-			# container is terminated.
-			if [ "${rootful}" -eq 0 ]; then
-				case "${container_manager}" in
-					*podman*)
-						${container_manager} kill "${container_name}" 2> /dev/null || :
-						;;
-				esac
+			# container's init process is terminated.
+			#
+			# Note: This only kills the init process, not any orphaned child processes - this is
+			# a limitation of --pid host mode (see https://github.com/containers/podman/issues/11888).
+			# To ensure all processes are cleaned up, use --unshare-process when creating the container.
+			if [ "${rootful}" -eq 0 ] && echo "${container_manager}" | grep -q "podman"; then
+				${container_manager} kill "${container_name}" 2> /dev/null || :
 			fi
 			${container_manager} stop "${container_name}" 2> /dev/null || :
 		done