feat: add Docker container cleanup to prevent hanging containers

- Add cleanup_hanging_docker_containers function to handle interrupted test runs
- Check for existing containers with instance name before starting new tests
- Stop and remove hanging containers automatically during preflight cleanup
- Add structured logging to track container cleanup operations
- Handle graceful cleanup when containers are not running vs completely missing
- Prevent 'container name already in use' errors in E2E tests

This addresses the issue where testcontainers doesn't clean up containers
when test execution is interrupted abruptly (Ctrl+C, system crashes, etc).
Normal test completion still relies on testcontainers automatic cleanup.

Author: josecelano

src/e2e/tasks/container/preflight_cleanup.rs

@@ -9,14 +9,14 @@ use crate::e2e::environment::TestEnvironment;
 use crate::e2e::tasks::preflight_cleanup::{
     cleanup_build_directory, cleanup_templates_directory, PreflightCleanupError,
 };
-use tracing::info;
+use crate::shared::executor::CommandExecutor;
+use tracing::{info, warn};
 
 /// Performs pre-flight cleanup for Docker-based E2E tests
 ///
 /// This function is specifically designed for Docker-based E2E tests that use
-/// testcontainers for container lifecycle management. It only cleans directories
-/// since Docker containers are automatically cleaned up when testcontainer objects
-/// are dropped.
+/// testcontainers for container lifecycle management. It cleans up directories
+/// and any hanging Docker containers from previous interrupted test runs.
 ///
 /// # Arguments
 ///
@@ -41,8 +41,8 @@ pub fn cleanup_lingering_resources(env: &TestEnvironment) -> Result<(), Prefligh
     // Clean the templates directory to ensure fresh embedded template extraction for E2E tests
     cleanup_templates_directory(env)?;
 
-    // Note: Docker containers are automatically cleaned up by testcontainers when objects are dropped
-    // No need for explicit container cleanup like with LXD/OpenTofu
+    // Clean up any hanging Docker containers from interrupted test runs
+    cleanup_hanging_docker_containers(env);
 
     info!(
         operation = "preflight_cleanup_docker",
@@ -51,3 +51,109 @@ pub fn cleanup_lingering_resources(env: &TestEnvironment) -> Result<(), Prefligh
     );
     Ok(())
 }
+
+/// Clean up hanging Docker containers from interrupted test runs
+///
+/// This function handles the case where testcontainers didn't clean up properly
+/// due to abrupt test termination. It removes containers with the instance name
+/// to prevent container name conflicts in subsequent test runs.
+///
+/// # Safety
+///
+/// This function is only intended for E2E test environments and should never
+/// be called in production code paths. It specifically targets test containers.
+///
+/// # Arguments
+///
+/// * `env` - The test environment containing the instance name
+fn cleanup_hanging_docker_containers(env: &TestEnvironment) {
+    let instance_name = env.config.instance_name.as_str();
+    let command_executor = CommandExecutor::new();
+
+    info!(
+        operation = "hanging_container_cleanup",
+        container_name = instance_name,
+        "Checking for hanging Docker containers from previous test runs"
+    );
+
+    // First, check if the container exists
+    let check_result = command_executor.run_command(
+        "docker",
+        &["ps", "-aq", "--filter", &format!("name={}", instance_name)],
+        None,
+    );
+
+    match check_result {
+        Ok(output) => {
+            if output.trim().is_empty() {
+                info!(
+                    operation = "hanging_container_cleanup",
+                    container_name = instance_name,
+                    status = "clean",
+                    "No hanging containers found"
+                );
+                return;
+            }
+
+            info!(
+                operation = "hanging_container_cleanup",
+                container_name = instance_name,
+                "Found hanging container, attempting cleanup"
+            );
+
+            // Try to stop the container (in case it's running)
+            match command_executor.run_command("docker", &["stop", instance_name], None) {
+                Ok(_) => {
+                    info!(
+                        operation = "hanging_container_cleanup",
+                        container_name = instance_name,
+                        action = "stop",
+                        status = "success",
+                        "Container stopped successfully"
+                    );
+                }
+                Err(e) => {
+                    // Container might not be running, which is okay
+                    warn!(
+                        operation = "hanging_container_cleanup",
+                        container_name = instance_name,
+                        action = "stop",
+                        status = "skipped",
+                        error = %e,
+                        "Could not stop container (probably not running)"
+                    );
+                }
+            }
+
+            // Remove the container
+            match command_executor.run_command("docker", &["rm", instance_name], None) {
+                Ok(_) => {
+                    info!(
+                        operation = "hanging_container_cleanup",
+                        container_name = instance_name,
+                        status = "success",
+                        "Hanging container cleaned up successfully"
+                    );
+                }
+                Err(e) => {
+                    warn!(
+                        operation = "hanging_container_cleanup",
+                        container_name = instance_name,
+                        status = "failed",
+                        error = %e,
+                        "Failed to remove hanging container (this may cause test failures)"
+                    );
+                }
+            }
+        }
+        Err(e) => {
+            warn!(
+                operation = "hanging_container_cleanup",
+                container_name = instance_name,
+                status = "check_failed",
+                error = %e,
+                "Could not check for hanging containers"
+            );
+        }
+    }
+}