feat(cli): surface panic payloads in debug diagnostics

Allow ADR-T-010 panic control-plane records to include string panic payloads
when debug diagnostics are enabled, while continuing to omit the payload field
for normal runs.

Wire the debug flag through the shared CLI runners and config probe, and add
coverage for the payload gate, JSON serialization, and string payload extraction.

Author: peer-cat

packages/index-cli-common/src/lib.rs

@@ -31,6 +31,7 @@ pub const CONTROL_PLANE_SCHEMA: u32 = 1;
 pub const REDACTED: &str = "[redacted]";
 
 static PANIC_REPORTED: AtomicBool = AtomicBool::new(false);
+static PANIC_PAYLOAD_REPORTING_ENABLED: AtomicBool = AtomicBool::new(true);
 static STDERR_WRITE_LOCK: Mutex<()> = Mutex::new(());
 
 /// Baseline exit-code classes shared by ADR-T-010 command-line tools.
@@ -116,11 +117,13 @@ pub enum ControlPlaneFields {
     UsageError { exit_code: u8, clap_error_kind: String },
     /// Details for stdout TTY refusal.
     TtyRefusal { exit_code: u8, stream: StandardStream },
-    /// Details for a panic diagnostic. The panic payload is deliberately omitted.
+    /// Details for a panic diagnostic. The panic payload is only exposed when debug diagnostics are enabled.
     Panic {
         exit_code: u8,
         thread: Option<String>,
         location: Option<String>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        payload: Option<String>,
     },
 }
 
@@ -207,7 +210,7 @@ impl ControlPlaneRecord {
 
     /// Build a panic diagnostic record.
     #[must_use]
-    pub fn panic(command: &str, thread: Option<&str>, location: Option<&str>) -> Self {
+    pub fn panic(command: &str, thread: Option<&str>, location: Option<&str>, payload: Option<&str>) -> Self {
         Self::new(
             command,
             ControlPlaneRecordKind::Panic,
@@ -216,6 +219,7 @@ impl ControlPlaneRecord {
                 exit_code: CommandExit::Failure.code(),
                 thread: thread.map(str::to_string),
                 location: location.map(str::to_string),
+                payload: payload.map(str::to_string),
             }),
         )
     }
@@ -421,6 +425,9 @@ fn level_directive(level: tracing::Level) -> String {
 ///
 /// Returns [`CliExit`] when parsing should stop and the caller should write the
 /// enclosed record to stderr before exiting with the enclosed exit class.
+/// The error value is intentionally returned by value because this path is only
+/// used when parsing stops, and boxing it would complicate the public helper API.
+#[allow(clippy::result_large_err)]
 pub fn parse_args_from<T, I, A>(args: I) -> Result<T, CliExit>
 where
     T: Parser,
@@ -531,14 +538,41 @@ pub fn install_json_panic_hook(command_name: &str) {
             let location = panic_info
                 .location()
                 .map(|location| format!("{}:{}:{}", location.file(), location.line(), location.column()));
-            let record = ControlPlaneRecord::panic(&command_name, thread_name, location.as_deref());
+            let payload = panic_payload_reporting_enabled()
+                .then(|| panic_payload_message(panic_info))
+                .flatten();
+            let record = ControlPlaneRecord::panic(&command_name, thread_name, location.as_deref(), payload);
             let _ignored = try_emit_control_plane_record(&record);
         }
 
         exit_with(CommandExit::Failure);
     }));
 }
 
+/// Enable or disable string panic payloads in JSON panic diagnostics.
+///
+/// Payload reporting starts enabled so panics before argument parsing still
+/// include their string payload. Call this with the parsed `--debug` value once
+/// arguments are available.
+pub fn set_panic_payload_reporting_enabled(enabled: bool) {
+    PANIC_PAYLOAD_REPORTING_ENABLED.store(enabled, Ordering::SeqCst);
+}
+
+fn panic_payload_reporting_enabled() -> bool {
+    PANIC_PAYLOAD_REPORTING_ENABLED.load(Ordering::SeqCst)
+}
+
+fn panic_payload_message<'a>(info: &'a std::panic::PanicHookInfo<'_>) -> Option<&'a str> {
+    panic_payload_message_from_payload(info.payload())
+}
+
+fn panic_payload_message_from_payload(payload: &(dyn std::any::Any + Send)) -> Option<&str> {
+    payload
+        .downcast_ref::<&str>()
+        .copied()
+        .or_else(|| payload.downcast_ref::<String>().map(String::as_str))
+}
+
 /// Exit the current process with an ADR-T-010 exit class.
 #[allow(clippy::exit)]
 pub fn exit_with(exit: CommandExit) -> ! {
@@ -633,6 +667,7 @@ where
     CommandError: std::fmt::Display,
     Run: FnOnce() -> Result<Output, CommandError>,
 {
+    set_panic_payload_reporting_enabled(debug);
     install_json_panic_hook(command_name);
     init_json_tracing_with_debug(debug, default_level);
 
@@ -671,6 +706,7 @@ where
     CommandError: std::fmt::Display,
     Run: FnOnce() -> Result<(), CommandError>,
 {
+    set_panic_payload_reporting_enabled(debug);
     install_json_panic_hook(command_name);
     init_json_tracing_with_debug(debug, default_level);
 
@@ -699,6 +735,7 @@ where
     Run: FnOnce() -> RunFuture,
     RunFuture: Future<Output = Result<(), CommandError>>,
 {
+    set_panic_payload_reporting_enabled(debug);
     install_json_panic_hook(command_name);
     init_json_tracing_with_debug(debug, default_level);
 

packages/index-cli-common/src/tests/mod.rs

@@ -13,7 +13,10 @@
 //! | `json_line_writer_appends_newline`      | JSON record helper writes one complete line.     |
 //! | `usage_error_record_carries_fields`    | Usage records include exit code and clap kind.   |
 //! | `tty_refusal_record_carries_fields`    | TTY refusal records identify stdout and code 2.  |
-//! | `panic_record_omits_payload`           | Panic records avoid serialising panic payloads.  |
+//! | `panic_record_omits_payload_without_debug` | Panic records hide payloads without debug.    |
+//! | `panic_record_carries_debug_payload`    | Panic records can expose string payloads.        |
+//! | `panic_payload_reporting_defaults_enabled_then_follows_debug_flag` | Startup payload gate behavior. |
+//! | `panic_payload_message_extracts_string_payloads` | String panic payloads are downcast.     |
 //! | `parse_args_from_returns_help_record`  | Clap help becomes JSON stderr control data.      |
 //! | `parse_args_from_returns_version_record` | Clap version becomes JSON stderr control data. |
 //! | `parse_args_from_returns_usage_record` | Clap argv errors become JSON usage records.      |
@@ -42,8 +45,8 @@ use serde_json::json;
 
 use crate::{
     BaseArgs, CONTROL_PLANE_SCHEMA, CommandExit, ControlPlaneFields, ControlPlaneRecord, ControlPlaneRecordKind, REDACTED,
-    StandardStream, TracingFilterSource, parse_args_from, redact_database_url, redact_field_value, tracing_filter_from_rust_log,
-    write_json_line,
+    StandardStream, TracingFilterSource, panic_payload_message_from_payload, panic_payload_reporting_enabled, parse_args_from,
+    redact_database_url, redact_field_value, set_panic_payload_reporting_enabled, tracing_filter_from_rust_log, write_json_line,
 };
 
 /// A `Write` that fails every call with `BrokenPipe`.
@@ -235,8 +238,8 @@ fn tty_refusal_record_carries_fields() {
 }
 
 #[test]
-fn panic_record_omits_payload() {
-    let record = ControlPlaneRecord::panic("fixture", Some("main"), Some("src/main.rs:12:34"));
+fn panic_record_omits_payload_without_debug() {
+    let record = ControlPlaneRecord::panic("fixture", Some("main"), Some("src/main.rs:12:34"), None);
     let value = serde_json::to_value(record).unwrap();
 
     assert_eq!(value["kind"], json!("panic"));
@@ -246,6 +249,44 @@ fn panic_record_omits_payload() {
     assert!(value["fields"].get("payload").is_none());
 }
 
+#[test]
+fn panic_record_carries_debug_payload() {
+    let record = ControlPlaneRecord::panic(
+        "fixture",
+        Some("main"),
+        Some("src/main.rs:12:34"),
+        Some("panic with \"quoted\" detail"),
+    );
+    let line = serde_json::to_string(&record).unwrap();
+
+    assert!(line.contains(r#""payload":"panic with \"quoted\" detail""#));
+
+    let value: serde_json::Value = serde_json::from_str(&line).unwrap();
+    assert_eq!(value["fields"]["payload"], json!("panic with \"quoted\" detail"));
+}
+
+#[test]
+fn panic_payload_reporting_defaults_enabled_then_follows_debug_flag() {
+    assert!(panic_payload_reporting_enabled());
+
+    set_panic_payload_reporting_enabled(false);
+    assert!(!panic_payload_reporting_enabled());
+
+    set_panic_payload_reporting_enabled(true);
+    assert!(panic_payload_reporting_enabled());
+}
+
+#[test]
+fn panic_payload_message_extracts_string_payloads() {
+    let borrowed_payload: &(dyn std::any::Any + Send) = &"borrowed panic";
+    let owned_payload: &(dyn std::any::Any + Send) = &String::from("owned panic");
+    let numeric_payload: &(dyn std::any::Any + Send) = &1_u8;
+
+    assert_eq!(panic_payload_message_from_payload(borrowed_payload), Some("borrowed panic"));
+    assert_eq!(panic_payload_message_from_payload(owned_payload), Some("owned panic"));
+    assert_eq!(panic_payload_message_from_payload(numeric_payload), None);
+}
+
 #[test]
 fn parse_args_from_returns_help_record() {
     let Err(exit) = parse_args_from::<FixtureCli, _, _>(["fixture-helper", "--help"]) else {

packages/index-config-probe/src/bin/torrust-index-config-probe.rs

@@ -10,6 +10,7 @@ use std::process::ExitCode;
 use clap::Parser;
 use torrust_index_cli_common::{
     BaseArgs, emit, init_json_tracing_with_debug, install_json_panic_hook, parse_args_or_exit, refuse_if_stdout_is_tty,
+    set_panic_payload_reporting_enabled,
 };
 use torrust_index_config::{DEFAULT_CONFIG_TOML_PATH, Info, load_settings};
 use torrust_index_config_probe::{ProbeError, probe};
@@ -32,6 +33,7 @@ fn main() -> ExitCode {
     install_json_panic_hook(COMMAND_NAME);
 
     let args = parse_args_or_exit::<Args>();
+    set_panic_payload_reporting_enabled(args.base.debug);
     init_json_tracing_with_debug(args.base.debug, tracing::Level::INFO);
     refuse_if_stdout_is_tty(COMMAND_NAME);