feat(cli): introduce user-facing error presentation

cli/src/services/app_support.rs

@@ -143,7 +143,7 @@ where
     W: Write,
 {
     if let Some(log) = logger {
-        log.log_classified_error(error, None);
+        log.log_classified_error(error, None, error.user_facing_presentation().is_none());
     }
     write_error_diagnostic(stderr, error);
     ExitCode::from(error.class().exit_code())
@@ -159,6 +159,12 @@ fn write_stdout_payload<W: Write>(writer: &mut W, payload: &str) -> Result<(), C
 }
 
 fn write_error_diagnostic<W: Write>(writer: &mut W, error: &ClassifiedError) {
+    if let Some(presentation) = error.user_facing_presentation() {
+        let message = services::security::redact_sensitive_text(presentation.message());
+        writeln!(writer, "{message}").expect("writing error diagnostic to writer should not fail");
+        return;
+    }
+
     let rendered = if error.message().contains("Try:") {
         error.message().to_string()
     } else {

cli/src/services/error.rs

@@ -39,11 +39,42 @@ impl FailureClass {
     }
 }
 
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct UserFacingPresentation {
+    message: String,
+    reason: Option<String>,
+}
+
+impl UserFacingPresentation {
+    pub fn new(message: impl Into<String>) -> Self {
+        Self {
+            message: message.into(),
+            reason: None,
+        }
+    }
+
+    #[allow(dead_code)]
+    pub fn with_reason(mut self, reason: impl Into<String>) -> Self {
+        self.reason = Some(reason.into());
+        self
+    }
+
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    #[allow(dead_code)]
+    pub fn reason(&self) -> Option<&str> {
+        self.reason.as_deref()
+    }
+}
+
 #[derive(Debug)]
 pub struct ClassifiedError {
     class: FailureClass,
     code: &'static str,
     message: String,
+    user_facing_presentation: Option<UserFacingPresentation>,
 }
 
 impl ClassifiedError {
@@ -52,6 +83,7 @@ impl ClassifiedError {
             class: FailureClass::Parse,
             code: "SCE-ERR-PARSE",
             message: message.into(),
+            user_facing_presentation: None,
         }
     }
 
@@ -60,6 +92,7 @@ impl ClassifiedError {
             class: FailureClass::Validation,
             code: "SCE-ERR-VALIDATION",
             message: message.into(),
+            user_facing_presentation: None,
         }
     }
 
@@ -68,6 +101,7 @@ impl ClassifiedError {
             class: FailureClass::Runtime,
             code: "SCE-ERR-RUNTIME",
             message: message.into(),
+            user_facing_presentation: None,
         }
     }
 
@@ -76,9 +110,21 @@ impl ClassifiedError {
             class: FailureClass::Dependency,
             code: "SCE-ERR-DEPENDENCY",
             message: message.into(),
+            user_facing_presentation: None,
         }
     }
 
+    #[allow(dead_code)]
+    pub fn with_user_facing_message(mut self, message: impl Into<String>) -> Self {
+        self.user_facing_presentation = Some(UserFacingPresentation::new(message));
+        self
+    }
+
+    pub fn with_user_facing_presentation(mut self, presentation: UserFacingPresentation) -> Self {
+        self.user_facing_presentation = Some(presentation);
+        self
+    }
+
     pub fn class(&self) -> FailureClass {
         self.class
     }
@@ -90,6 +136,10 @@ impl ClassifiedError {
     pub fn message(&self) -> &str {
         &self.message
     }
+
+    pub fn user_facing_presentation(&self) -> Option<&UserFacingPresentation> {
+        self.user_facing_presentation.as_ref()
+    }
 }
 
 impl std::fmt::Display for ClassifiedError {

cli/src/services/observability.rs

@@ -122,7 +122,7 @@ impl Logger {
         fields: &[(&str, &str)],
         session_id: Option<&str>,
     ) {
-        self.log_forced(LogLevel::Warn, event_id, message, fields, session_id);
+        self.log_forced(LogLevel::Warn, event_id, message, fields, session_id, true);
     }
 
     #[cfg_attr(not(test), allow(dead_code))]
@@ -136,9 +136,14 @@ impl Logger {
         self.log(LogLevel::Error, event_id, message, fields, session_id);
     }
 
-    pub fn log_classified_error(&self, error: &ClassifiedError, session_id: Option<&str>) {
+    pub(crate) fn log_classified_error(
+        &self,
+        error: &ClassifiedError,
+        session_id: Option<&str>,
+        emit_stderr: bool,
+    ) {
         let event_id = format!("sce.error.{}", error.code());
-        self.log(
+        self.log_forced(
             LogLevel::Error,
             &event_id,
             error.message(),
@@ -147,6 +152,7 @@ impl Logger {
                 ("error_class", error.class().as_str()),
             ],
             session_id,
+            emit_stderr,
         );
     }
 
@@ -162,7 +168,7 @@ impl Logger {
             return;
         }
 
-        self.log_forced(level, event_id, message, fields, session_id);
+        self.log_forced(level, event_id, message, fields, session_id, true);
     }
 
     fn log_forced(
@@ -172,19 +178,18 @@ impl Logger {
         message: &str,
         fields: &[(&str, &str)],
         session_id: Option<&str>,
+        emit_stderr: bool,
     ) {
         emit_tracing_event(level, event_id, message, fields);
 
         let line = self.render_line(level, event_id, message, fields);
         let redacted_line = redact_sensitive_text(&line);
-        emit_stderr_line(&redacted_line);
 
-        if let Err(error) = self.write_log_line(&redacted_line, session_id) {
-            let diagnostic = redact_sensitive_text(&format!(
-                "Failed to write SCE log file: {error}. Logging continues on stderr."
-            ));
-            emit_stderr_line(&diagnostic);
+        if emit_stderr {
+            emit_stderr_line(&redacted_line);
         }
+
+        let _ = self.write_log_line(&redacted_line, session_id);
     }
 
     fn write_log_line(&self, redacted_line: &str, session_id: Option<&str>) -> Result<()> {
@@ -388,12 +393,7 @@ where
 {
     if write_target == LogWriteTarget::Created {
         if let Some(parent) = path.parent() {
-            if let Err(error) = cleanup(parent) {
-                let diagnostic = redact_sensitive_text(&format!(
-                    "Failed to clean up SCE log files: {error}. Logging continues on stderr."
-                ));
-                emit_stderr_line(&diagnostic);
-            }
+            let _ = cleanup(parent);
         }
     }
 }

cli/src/services/observability/traits.rs

@@ -33,7 +33,12 @@ pub trait Logger: Send + Sync {
         session_id: Option<&str>,
     );
 
-    fn log_classified_error(&self, error: &ClassifiedError, session_id: Option<&str>);
+    fn log_classified_error(
+        &self,
+        error: &ClassifiedError,
+        session_id: Option<&str>,
+        emit_stderr: bool,
+    );
 }
 
 pub trait Telemetry: Send + Sync {
@@ -84,7 +89,13 @@ impl Logger for NoopLogger {
     ) {
     }
 
-    fn log_classified_error(&self, _error: &ClassifiedError, _session_id: Option<&str>) {}
+    fn log_classified_error(
+        &self,
+        _error: &ClassifiedError,
+        _session_id: Option<&str>,
+        _emit_stderr: bool,
+    ) {
+    }
 }
 
 impl Logger for super::Logger {
@@ -128,8 +139,13 @@ impl Logger for super::Logger {
         super::Logger::error(self, event_id, message, fields, session_id);
     }
 
-    fn log_classified_error(&self, error: &ClassifiedError, session_id: Option<&str>) {
-        super::Logger::log_classified_error(self, error, session_id);
+    fn log_classified_error(
+        &self,
+        error: &ClassifiedError,
+        session_id: Option<&str>,
+        emit_stderr: bool,
+    ) {
+        super::Logger::log_classified_error(self, error, session_id, emit_stderr);
     }
 }
 

cli/src/services/sync/command.rs

@@ -1,7 +1,8 @@
 use std::io::Write;
 
 use crate::app::ContextWithRepoRoot;
-use crate::services::error::ClassifiedError;
+use crate::services::agent_trace_sync::control_plane::ControlPlaneError;
+use crate::services::error::{ClassifiedError, UserFacingPresentation};
 use crate::services::sync::progress::{
     IndicatifProgressReporter, NoopProgressReporter, ProgressReporter,
 };
@@ -31,7 +32,22 @@ where
 
 #[allow(clippy::needless_pass_by_value)]
 fn classify_sync_error(err: TraceSyncError) -> ClassifiedError {
-    ClassifiedError::runtime(format!("{err}"))
+    let is_unauthenticated = matches!(
+        &err,
+        TraceSyncError::ControlPlane(
+            ControlPlaneError::MissingCredentials | ControlPlaneError::AuthenticationFailed(_)
+        )
+    );
+    let classified = ClassifiedError::runtime(format!("{err}"));
+
+    if is_unauthenticated {
+        classified.with_user_facing_presentation(UserFacingPresentation::new(format!(
+            "You are not logged in. Please log in using the {} command.",
+            crate::services::style::success("sce auth login")
+        )))
+    } else {
+        classified
+    }
 }
 
 impl SyncCommand {