fix(bootstrap): surface diagnostics for K8s namespace not ready failures

The 'K8s namespace not ready' error had three gaps preventing diagnostic
information from reaching users:

1. The non-interactive (CI/piped) code path used bare error propagation
   with no diagnosis at all.
2. The interactive path's pattern matcher returned None for the common
   timeout case, and the generic_failure_diagnosis fallback existed but
   was never called.
3. Container logs were never passed to the diagnosis engine, so patterns
   only visible in logs (node pressure, corrupted state, etc.) could not
   match.

Fix all three by fetching container logs at the CLI error-handling site,
passing them to diagnose_failure, and falling back to
generic_failure_diagnosis when no specific pattern matches. Also add
container logs to the two wait_for_namespace error paths that were
missing them (timeout and exec-error-on-final-attempt), and update the
generic diagnosis to suggest 'openshell doctor' commands.

Author: drew

crates/openshell-bootstrap/src/errors.rs

@@ -449,16 +449,20 @@ pub fn generic_failure_diagnosis(gateway_name: &str) -> GatewayFailureDiagnosis
         summary: "Gateway failed to start".to_string(),
         explanation: "The gateway encountered an unexpected error during startup.".to_string(),
         recovery_steps: vec![
+            RecoveryStep::with_command(
+                "Check container logs for details",
+                format!("openshell doctor logs --name {gateway_name}"),
+            ),
+            RecoveryStep::with_command(
+                "Run diagnostics",
+                format!("openshell doctor check --name {gateway_name}"),
+            ),
             RecoveryStep::with_command(
                 "Try destroying and recreating the gateway",
                 format!(
                     "openshell gateway destroy --name {gateway_name} && openshell gateway start"
                 ),
             ),
-            RecoveryStep::with_command(
-                "Check container logs for details",
-                format!("docker logs openshell-cluster-{gateway_name}"),
-            ),
             RecoveryStep::new(
                 "If the issue persists, report it at https://github.com/nvidia/openshell/issues",
             ),

crates/openshell-bootstrap/src/lib.rs

@@ -638,6 +638,21 @@ pub async fn gateway_container_logs<W: std::io::Write>(
     Ok(())
 }
 
+/// Fetch the last `n` lines of container logs for a local gateway as a
+/// `String`.  This is a convenience wrapper for diagnostic call sites (e.g.
+/// failure diagnosis in the CLI) that do not hold a Docker client handle.
+///
+/// Returns an empty string on any Docker/connection error so callers don't
+/// need to worry about error handling.
+pub async fn fetch_gateway_logs(name: &str, n: usize) -> String {
+    let docker = match Docker::connect_with_local_defaults() {
+        Ok(d) => d,
+        Err(_) => return String::new(),
+    };
+    let container = container_name(name);
+    fetch_recent_logs(&docker, &container, n).await
+}
+
 fn default_gateway_image_ref() -> String {
     if let Ok(image) = std::env::var("OPENSHELL_CLUSTER_IMAGE")
         && !image.trim().is_empty()
@@ -984,7 +999,11 @@ async fn wait_for_namespace(
                 }
 
                 if attempt + 1 == attempts {
-                    return Err(err).wrap_err("K8s namespace not ready");
+                    let logs = fetch_recent_logs(docker, container_name, 40).await;
+                    return Err(miette::miette!(
+                        "exec failed on final attempt while waiting for namespace '{namespace}': {err}\n{logs}"
+                    ))
+                    .wrap_err("K8s namespace not ready");
                 }
                 tokio::time::sleep(backoff).await;
                 backoff = std::cmp::min(backoff.saturating_mul(2), max_backoff);
@@ -997,8 +1016,9 @@ async fn wait_for_namespace(
         }
 
         if attempt + 1 == attempts {
+            let logs = fetch_recent_logs(docker, container_name, 40).await;
             return Err(miette::miette!(
-                "timed out waiting for namespace '{namespace}' to exist: {output}"
+                "timed out waiting for namespace '{namespace}' to exist: {output}\n{logs}"
             ))
             .wrap_err("K8s namespace not ready");
         }

crates/openshell-cli/src/run.rs

@@ -1248,19 +1248,27 @@ pub(crate) async fn deploy_gateway_with_panel(
                     "x".red().bold(),
                     "Gateway failed:".red().bold(),
                 );
+                // Fetch container logs for pattern-based diagnosis
+                let container_logs = openshell_bootstrap::fetch_gateway_logs(name, 80).await;
+                let logs_opt = if container_logs.is_empty() {
+                    None
+                } else {
+                    Some(container_logs.as_str())
+                };
                 // Try to diagnose the failure and provide guidance
                 let err_str = format!("{err:?}");
-                if let Some(diagnosis) =
-                    openshell_bootstrap::errors::diagnose_failure(name, &err_str, None)
-                {
-                    print_failure_diagnosis(&diagnosis);
-                }
+                let diagnosis =
+                    openshell_bootstrap::errors::diagnose_failure(name, &err_str, logs_opt)
+                        .unwrap_or_else(|| {
+                            openshell_bootstrap::errors::generic_failure_diagnosis(name)
+                        });
+                print_failure_diagnosis(&diagnosis);
                 Err(err)
             }
         }
     } else {
         eprintln!("Deploying {location} gateway {name}...");
-        let handle = openshell_bootstrap::deploy_gateway_with_logs(options, |line| {
+        let result = openshell_bootstrap::deploy_gateway_with_logs(options, |line| {
             if let Some(status) = line.strip_prefix("[status] ") {
                 eprintln!("  {status}");
             } else if line.strip_prefix("[progress] ").is_some() {
@@ -1269,9 +1277,35 @@ pub(crate) async fn deploy_gateway_with_panel(
                 eprintln!("  {line}");
             }
         })
-        .await?;
-        eprintln!("Gateway {name} ready.");
-        Ok(handle)
+        .await;
+        match result {
+            Ok(handle) => {
+                eprintln!("Gateway {name} ready.");
+                Ok(handle)
+            }
+            Err(err) => {
+                eprintln!(
+                    "{} {} {name}",
+                    "x".red().bold(),
+                    "Gateway failed:".red().bold(),
+                );
+                // Fetch container logs for pattern-based diagnosis
+                let container_logs = openshell_bootstrap::fetch_gateway_logs(name, 80).await;
+                let logs_opt = if container_logs.is_empty() {
+                    None
+                } else {
+                    Some(container_logs.as_str())
+                };
+                let err_str = format!("{err:?}");
+                let diagnosis =
+                    openshell_bootstrap::errors::diagnose_failure(name, &err_str, logs_opt)
+                        .unwrap_or_else(|| {
+                            openshell_bootstrap::errors::generic_failure_diagnosis(name)
+                        });
+                print_failure_diagnosis(&diagnosis);
+                Err(err)
+            }
+        }
     }
 }