fix(agent): surface OpenClaw Gateway unreachable errors (#498)

## Summary
- Add the dedicated `USER_AGENT_OPENCLAW_GATEWAY_UNREACHABLE` agent
error code and backend-aware OpenClaw Gateway classification.
- Surface the structured error through ACP send, turn build, and warmup
paths without starting or supervising OpenClaw Gateway.
- Add low-volume diagnostic logs for Gateway classification and ACP idle
cleanup.

## Paired Frontend Change
- Paired with iOfficeAI/AionUi#3392.

## Test Plan
- [x] `just push -u origin openclaw-gateway-unreachable`
- [x] Local development verification with OpenClaw Gateway stopped: UI
shows the dedicated recovery tip and logs include
`error_kind=openclaw_gateway_unreachable`, `backend=openclaw`,
`port=18789`, and `phase=turn_build`.

## Release Notes
- Bug Fixes: OpenClaw ACP startup failures caused by an unreachable
Gateway now surface a dedicated actionable user-agent error.

---------

Co-authored-by: zynx <>

Author: piorpua

crates/aionui-ai-agent/src/idle_scanner.rs

@@ -1,7 +1,7 @@
 use std::sync::Arc;
 use std::time::Duration;
 
-use aionui_common::AgentKillReason;
+use aionui_common::{AgentKillReason, now_ms};
 use tracing::{debug, info};
 
 use crate::task_manager::IWorkerTaskManager;
@@ -55,14 +55,16 @@ pub fn start_idle_scanner(
 
 /// Perform one scan: find idle tasks and kill them.
 fn scan_and_cleanup(manager: &Arc<dyn IWorkerTaskManager>, threshold_ms: i64) {
+    let started_at = now_ms();
     let idle_ids = manager.collect_idle(threshold_ms);
 
     if idle_ids.is_empty() {
         debug!(active = manager.active_count(), "Idle scan: no idle agents found");
         return;
     }
 
-    info!(count = idle_ids.len(), "Idle scan: cleaning up idle agents");
+    let count = idle_ids.len();
+    info!(count, "Idle scan: cleaning up idle agents");
 
     for id in idle_ids {
         let manager = Arc::clone(manager);
@@ -71,4 +73,10 @@ fn scan_and_cleanup(manager: &Arc<dyn IWorkerTaskManager>, threshold_ms: i64) {
             manager.kill_and_wait(&id, Some(AgentKillReason::IdleTimeout)).await;
         });
     }
+
+    info!(
+        count,
+        elapsed_ms = now_ms().saturating_sub(started_at),
+        "Idle scan: cleanup completed"
+    );
 }

crates/aionui-ai-agent/src/manager/acp/agent.rs

@@ -23,7 +23,7 @@ use aionui_api_types::{
     SlashCommandCompletionBehavior, SlashCommandItem,
 };
 use aionui_common::{
-    AgentKillReason, AgentType, ConversationStatus, ErrorChain, TimestampMs, normalize_keys_to_snake_case,
+    AgentKillReason, AgentType, ConversationStatus, ErrorChain, TimestampMs, normalize_keys_to_snake_case, now_ms,
 };
 use serde_json::Value;
 use std::collections::HashMap;
@@ -935,6 +935,37 @@ impl AcpAgentManager {
     }
 }
 
+fn log_idle_acp_shutdown_started(conversation_id: &str, backend: &str, session_id: Option<&str>, pid: u32) {
+    info!(
+        conversation_id = %conversation_id,
+        backend = %backend,
+        session_id = %session_id.unwrap_or("none"),
+        pid,
+        reason = %"IdleTimeout",
+        "Idle kill: ACP shutdown started"
+    );
+}
+
+fn log_idle_acp_cancel_sent(conversation_id: &str, backend: &str, session_id: &str, pid: u32) {
+    info!(
+        conversation_id = %conversation_id,
+        backend = %backend,
+        session_id = %session_id,
+        pid,
+        "Idle kill: ACP session cancel sent"
+    );
+}
+
+fn log_idle_acp_cancel_skipped(conversation_id: &str, backend: &str, pid: u32) {
+    info!(
+        conversation_id = %conversation_id,
+        backend = %backend,
+        pid,
+        reason = %"no_session_id",
+        "Idle kill: ACP session cancel skipped"
+    );
+}
+
 #[async_trait::async_trait]
 impl crate::agent_task::IAgentTask for AcpAgentManager {
     fn agent_type(&self) -> AgentType {
@@ -1017,7 +1048,8 @@ impl crate::agent_task::IAgentTask for AcpAgentManager {
                 Ok(())
             }
             Err(err) => {
-                let send_error = err.to_agent_send_error();
+                let backend = self.params.metadata.backend.as_deref();
+                let send_error = err.to_agent_send_error_for_backend(backend);
                 let agent_err = err.into_agent_error();
                 // Build a CloseReason that captures whatever context we still
                 // have. Two cases matter:
@@ -1082,34 +1114,65 @@ impl crate::agent_task::IAgentTask for AcpAgentManager {
         // Mark closing to prevent reconnect attempts
         self.permission_router.set_closing();
 
-        // Cancel the current session if active
-        if let Ok(session) = self.session.try_read()
-            && let Some(sid) = session.session_id()
-        {
+        let backend = self.params.metadata.backend.as_deref().unwrap_or("unknown");
+        let pid = self.process.pid();
+        let idle_timeout = matches!(reason, Some(AgentKillReason::IdleTimeout));
+        let session_id = self
+            .session
+            .try_read()
+            .ok()
+            .and_then(|session| session.session_id().map(ToOwned::to_owned));
+
+        if idle_timeout {
+            log_idle_acp_shutdown_started(&self.params.conversation_id, backend, session_id.as_deref(), pid);
+        }
+
+        if let Some(sid) = session_id.as_deref() {
             self.protocol.cancel(CancelNotification::new(SessionId::new(sid)));
+            if idle_timeout {
+                log_idle_acp_cancel_sent(&self.params.conversation_id, backend, sid, pid);
+            }
+        } else if idle_timeout {
+            log_idle_acp_cancel_skipped(&self.params.conversation_id, backend, pid);
         }
 
         let process = Arc::clone(&self.process);
         let grace = Duration::from_millis(ACP_KILL_GRACE_MS);
         let conversation_id = self.params.conversation_id.clone();
-        let pid = process.pid();
+        let process_group_id = process.process_group_id();
+        let backend = backend.to_owned();
+        let idle_timeout = matches!(reason, Some(AgentKillReason::IdleTimeout));
 
         tokio::spawn(async move {
-            if let Err(e) = process.kill(grace).await {
-                // Tag the failure with conversation_id + pid so Sentry can
-                // group these and ops can correlate with the matching
-                // "Killing ACP agent" log line. ELECTRON-1E9: an unannotated
-                // failure here on Windows left the CLI subprocess running
-                // while the manager believed it had been torn down,
-                // producing the "no reply / second send hangs" symptom.
-                error!(
-                    %conversation_id,
-                    pid,
-                    error = %ErrorChain(&e),
-                    "Failed to kill ACP process"
-                );
-            } else {
-                debug!(%conversation_id, pid, "ACP process kill completed");
+            let started_at = now_ms();
+            match process.kill(grace).await {
+                Ok(()) => {
+                    if idle_timeout {
+                        info!(
+                            %conversation_id,
+                            backend,
+                            pid,
+                            process_group_id,
+                            elapsed_ms = now_ms().saturating_sub(started_at),
+                            result = "ok",
+                            "Idle kill: ACP process shutdown completed"
+                        );
+                    } else {
+                        debug!(%conversation_id, pid, process_group_id, "ACP process kill completed");
+                    }
+                }
+                Err(e) => {
+                    error!(
+                        %conversation_id,
+                        backend,
+                        pid,
+                        process_group_id,
+                        elapsed_ms = now_ms().saturating_sub(started_at),
+                        result = "error",
+                        error = %ErrorChain(&e),
+                        "Idle kill: ACP process shutdown completed"
+                    );
+                }
             }
         });
 
@@ -1189,6 +1252,42 @@ mod tests {
     use serde_json::json;
     use std::collections::HashMap;
 
+    fn capture_logs(max_level: tracing::Level, f: impl FnOnce()) -> String {
+        use std::io::Write;
+        use std::sync::{Arc, Mutex};
+        use tracing_subscriber::fmt;
+
+        #[derive(Clone)]
+        struct SharedBuf(Arc<Mutex<Vec<u8>>>);
+
+        impl Write for SharedBuf {
+            fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+                self.0.lock().unwrap().extend_from_slice(buf);
+                Ok(buf.len())
+            }
+
+            fn flush(&mut self) -> std::io::Result<()> {
+                Ok(())
+            }
+        }
+
+        let buffer = Arc::new(Mutex::new(Vec::<u8>::new()));
+        let make_writer = {
+            let buffer = Arc::clone(&buffer);
+            move || SharedBuf(Arc::clone(&buffer))
+        };
+
+        let subscriber = fmt::Subscriber::builder()
+            .with_max_level(max_level)
+            .with_writer(make_writer)
+            .with_ansi(false)
+            .finish();
+
+        tracing::subscriber::with_default(subscriber, f);
+
+        String::from_utf8(buffer.lock().unwrap().clone()).unwrap()
+    }
+
     #[test]
     fn exit_status_parts_handles_missing_status() {
         assert_eq!(exit_status_parts(None), (None, None));
@@ -1225,6 +1324,33 @@ mod tests {
         assert_eq!(user_facing_message(&err), "Rate limited");
     }
 
+    #[test]
+    fn idle_acp_shutdown_started_log_contains_diagnostic_context() {
+        let captured = capture_logs(tracing::Level::INFO, || {
+            super::log_idle_acp_shutdown_started("conv_openclaw", "openclaw", Some("session_123"), 4242);
+        });
+
+        assert!(captured.contains("Idle kill: ACP shutdown started"));
+        assert!(captured.contains("conversation_id=conv_openclaw"));
+        assert!(captured.contains("backend=openclaw"));
+        assert!(captured.contains("session_id=session_123"));
+        assert!(captured.contains("pid=4242"));
+        assert!(captured.contains("reason=IdleTimeout"));
+    }
+
+    #[test]
+    fn idle_acp_cancel_skipped_log_contains_reason() {
+        let captured = capture_logs(tracing::Level::INFO, || {
+            super::log_idle_acp_cancel_skipped("conv_openclaw", "openclaw", 4242);
+        });
+
+        assert!(captured.contains("Idle kill: ACP session cancel skipped"));
+        assert!(captured.contains("conversation_id=conv_openclaw"));
+        assert!(captured.contains("backend=openclaw"));
+        assert!(captured.contains("pid=4242"));
+        assert!(captured.contains("reason=no_session_id"));
+    }
+
     #[test]
     fn warmup_does_not_mark_opened_when_protocol_disconnected_after_open() {
         let mut session = AcpSession::new(None, None, Default::default());

crates/aionui-ai-agent/src/manager/acp/error_mapping.rs

@@ -9,13 +9,21 @@ pub(super) enum AcpSendFailure {
 }
 
 impl AcpSendFailure {
+    #[allow(dead_code)]
     pub(super) fn to_agent_send_error(&self) -> AgentSendError {
         match self {
             AcpSendFailure::Agent(err) => AgentSendError::from_agent_error_ref(err),
             AcpSendFailure::Acp(err) => AgentSendError::from_acp_error_ref(err),
         }
     }
 
+    pub(super) fn to_agent_send_error_for_backend(&self, backend: Option<&str>) -> AgentSendError {
+        match self {
+            AcpSendFailure::Agent(err) => AgentSendError::from_agent_error_ref_for_backend(err, backend),
+            AcpSendFailure::Acp(err) => AgentSendError::from_acp_error_ref_for_backend(err, backend),
+        }
+    }
+
     pub(super) fn into_agent_error(self) -> AgentError {
         match self {
             AcpSendFailure::Agent(err) => err,