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,17 @@ 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 ]; then
+			case "${container_manager}" in
+				*podman*)
+					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"
+					;;
+			esac
+		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,9 +401,10 @@ 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.
+	# 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 ]; then
 		case "${container_manager}" in
 			*podman*)

distrobox-stop

@@ -295,7 +295,11 @@ 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.
+			# 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 ]; then
 				case "${container_manager}" in
 					*podman*)