Recorder exit code policy (#66)

## Context

`ct record` invokes the Rust-backed `codetracer_python_recorder` CLI
when capturing Python traces. The CLI currently returns the traced
script's process exit code (`codetracer_python_recorder/cli.py:165`).
When the target program exits with a non-zero status—whether via
`SystemExit`, a failed assertion, or an explicit `sys.exit()`—the
recorder propagates that status. The desktop CLI treats any non-zero
exit as a fatal recording failure, so trace uploads and follow-on
automation abort even though the trace artefacts are valid and the
recorder itself completed successfully.

Our recorder already captures the script's exit status in session
metadata (`runtime/tracer/lifecycle.rs:143`) and exposes it through
trace viewers. Downstream consumers that need to assert on the original
program outcome can read that field. However, other integrations (CI
pipelines, `ct record` automations, scripted data collection) rely on
the CLI process exit code to decide whether to continue, and they expect
Codetracer to return `0` when recording succeeded.

We must let callers control whether the recorder propagates the script's
exit status or reports recorder success independently. The default
should favour Codetracer success (exit `0`) to preserve `ct record`
expectations, while still allowing advanced users and direct CLI
invocations to opt back into passthrough semantics.

## Decision

Introduce a recorder exit-code policy with the following behaviour:

1. **Default:** When tracing completes without recorder errors (start,
flush, stop, and write phases succeed and `require_trace` did not
trigger), the CLI exits with status `0` regardless of the traced
script's exit code. The recorder still records the script's status in
trace metadata.

2. **Opt-in passthrough:** Expose a CLI flag `--propagate-script-exit`
and environment override `CODETRACER_PROPAGATE_SCRIPT_EXIT`. When
enabled, the CLI mirrors the traced script's exit code (the current
behaviour). Both configuration surfaces resolve through the recorder
policy layer so other entry points (e.g., embedded integrations) can opt
in.

3. **User feedback:** If passthrough is disabled and the script exits
non-zero, emit a one-line warning on stderr indicating the script's exit
status and how to re-enable propagation.

4. **Recorder failure precedence:** Recorder failures (startup errors,
policy violations such as `--require-trace`, flush/stop exceptions)
continue to exit non-zero irrespective of the propagation setting to
ensure automation can detect recorder malfunction.

This policy applies uniformly to `python -m codetracer_python_recorder`,
`ct record`, and any embedding that drives the same CLI module.

Author: tzanko-matev

README.md

@@ -41,12 +41,13 @@ All subclasses carry the same attributes, so existing handlers can migrate by ca
 
 `python -m codetracer_python_recorder` returns:
 
-- `0` when tracing and the target script succeed.
-- The script's own exit code when it calls `sys.exit()`.
-- `1` when a `RecorderError` bubbles out of startup or shutdown.
-- `2` when the CLI arguments are incomplete.
+- `0` when the recorder finishes cleanly, even if the traced script exits non-zero. The script's status is still recorded in `trace_metadata.json`, and a warning on stderr highlights the suppressed status.
+- `1` when a `RecorderError` bubbles out of startup or shutdown (policy failures, `require_trace`, flush/stop issues).
+- `2` when the CLI arguments are incomplete or invalid.
 
-Pass `--codetracer-json-errors` (or set the policy via `configure_policy(json_errors=True)`) to stream a one-line JSON trailer on stderr. The payload includes `run_id`, `trace_id`, `error_code`, `error_kind`, `message`, and the `context` map so downstream tooling can log failures without scraping text.
+Opt into mirroring the script's exit code with `--propagate-script-exit` (or `CODETRACER_PROPAGATE_SCRIPT_EXIT=true`). Use `--no-propagate-script-exit` to force suppression, even if the environment enables mirroring.
+
+Pass `--json-errors` (or set the policy via `configure_policy(json_errors=True)`) to stream a one-line JSON trailer on stderr. The payload includes `run_id`, `trace_id`, `error_code`, `error_kind`, `message`, and the `context` map so downstream tooling can log failures without scraping text.
 
 ### IO capture configuration
 

codetracer-python-recorder/CHANGELOG.md

@@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ### Changed
 - Module-level call events now prefer the frame's `__name__`, fall back to filter hints, `sys.path`, and package markers, and no longer depend on the legacy resolver/cache. The globals-derived naming flag now defaults to enabled so direct scripts record `<__main__>` while package imports emit `<pkg.mod>`, with CLI and environment overrides available for the legacy resolver.
+- The CLI now exits with `0` when recording succeeds regardless of the traced script’s status, records a warning when suppressing non-zero script exits, and exposes `--propagate-script-exit` / `CODETRACER_PROPAGATE_SCRIPT_EXIT` / `configure_policy(propagate_script_exit=True)` to restore passthrough semantics.
 
 ## [0.2.0] - 2025-10-17
 ### Added

codetracer-python-recorder/codetracer_python_recorder/cli.py

@@ -11,7 +11,7 @@
 from pathlib import Path
 from typing import Iterable, Sequence
 
-from . import flush, start, stop
+from . import flush, policy_snapshot, start, stop
 from .auto_start import ENV_TRACE_FILTER
 from .formats import DEFAULT_FORMAT, SUPPORTED_FORMATS, normalize_format
 
@@ -129,6 +129,15 @@ def _parse_args(argv: Sequence[str]) -> RecorderCLIConfig:
             "Use '--no-module-name-from-globals' to fall back to the legacy resolver."
         ),
     )
+    parser.add_argument(
+        "--propagate-script-exit",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help=(
+            "Mirror the traced script's exit status when the recorder succeeds (default: disabled). "
+            "Use '--no-propagate-script-exit' to force a zero exit status."
+        ),
+    )
 
     known, remainder = parser.parse_known_args(argv)
     pending: list[str] = list(remainder)
@@ -192,6 +201,8 @@ def _parse_args(argv: Sequence[str]) -> RecorderCLIConfig:
                 parser.error(f"unsupported io-capture mode '{other}'")
     if known.module_name_from_globals is not None:
         policy["module_name_from_globals"] = known.module_name_from_globals
+    if known.propagate_script_exit is not None:
+        policy["propagate_script_exit"] = known.propagate_script_exit
 
     return RecorderCLIConfig(
         trace_dir=trace_dir,
@@ -286,7 +297,11 @@ def main(argv: Iterable[str] | None = None) -> int:
         sys.argv = old_argv
         return 1
 
+    snapshot = policy_snapshot()
+    propagate_script_exit = bool(snapshot.get("propagate_script_exit"))
+
     exit_code: int | None = None
+    recorder_failed = False
     try:
         try:
             runpy.run_path(str(script_path), run_name="__main__")
@@ -297,13 +312,35 @@ def main(argv: Iterable[str] | None = None) -> int:
     finally:
         try:
             flush()
+        except Exception as exc:
+            recorder_failed = True
+            sys.stderr.write(f"Failed to flush Codetracer session: {exc}\n")
         finally:
-            stop(exit_code=exit_code)
-            sys.argv = old_argv
+            try:
+                stop(exit_code=exit_code)
+            except Exception as exc:
+                recorder_failed = True
+                sys.stderr.write(f"Failed to stop Codetracer session: {exc}\n")
+            finally:
+                sys.argv = old_argv
 
     _serialise_metadata(trace_dir, script=script_path)
 
-    return exit_code if exit_code is not None else 0
+    script_exit_code = exit_code if exit_code is not None else 0
+
+    if recorder_failed:
+        return 1
+
+    if propagate_script_exit:
+        return script_exit_code
+
+    if script_exit_code != 0:
+        sys.stderr.write(
+            f"Script exited with status {script_exit_code}; returning 0. "
+            "Use '--propagate-script-exit' to mirror the script exit code.\n"
+        )
+
+    return 0
 
 
 __all__ = ("main", "RecorderCLIConfig")

codetracer-python-recorder/codetracer_python_recorder/session.py

@@ -89,7 +89,8 @@ def start(
     policy:
         Optional mapping of runtime policy overrides forwarded to
         :func:`configure_policy` before tracing begins. Keys match the policy
-        keyword arguments (``on_recorder_error``, ``require_trace``, etc.).
+        keyword arguments (``on_recorder_error``, ``require_trace``,
+        ``propagate_script_exit``, etc.).
     apply_env_policy:
         When ``True`` (default), refresh policy settings from environment
         variables via :func:`configure_policy_from_env` prior to applying

codetracer-python-recorder/src/policy.rs

@@ -8,7 +8,7 @@ mod model;
 pub use env::{
     configure_policy_from_env, ENV_CAPTURE_IO, ENV_JSON_ERRORS, ENV_KEEP_PARTIAL_TRACE,
     ENV_LOG_FILE, ENV_LOG_LEVEL, ENV_MODULE_NAME_FROM_GLOBALS, ENV_ON_RECORDER_ERROR,
-    ENV_REQUIRE_TRACE,
+    ENV_PROPAGATE_SCRIPT_EXIT, ENV_REQUIRE_TRACE,
 };
 #[allow(unused_imports)]
 pub use ffi::{configure_policy_py, py_configure_policy_from_env, py_policy_snapshot};
@@ -43,6 +43,7 @@ mod tests {
         assert!(snap.io_capture.line_proxies);
         assert!(!snap.io_capture.fd_fallback);
         assert!(snap.module_name_from_globals);
+        assert!(!snap.propagate_script_exit);
     }
 
     #[test]
@@ -58,6 +59,7 @@ mod tests {
         update.io_capture_line_proxies = Some(true);
         update.io_capture_fd_fallback = Some(true);
         update.module_name_from_globals = Some(true);
+        update.propagate_script_exit = Some(true);
 
         apply_policy_update(update);
 
@@ -71,6 +73,7 @@ mod tests {
         assert!(snap.io_capture.line_proxies);
         assert!(snap.io_capture.fd_fallback);
         assert!(snap.module_name_from_globals);
+        assert!(snap.propagate_script_exit);
         reset_policy();
     }
 
@@ -86,6 +89,7 @@ mod tests {
         std::env::set_var(ENV_JSON_ERRORS, "yes");
         std::env::set_var(ENV_CAPTURE_IO, "proxies,fd");
         std::env::set_var(ENV_MODULE_NAME_FROM_GLOBALS, "true");
+        std::env::set_var(ENV_PROPAGATE_SCRIPT_EXIT, "true");
 
         configure_policy_from_env().expect("configure from env");
 
@@ -101,6 +105,7 @@ mod tests {
         assert!(snap.io_capture.line_proxies);
         assert!(snap.io_capture.fd_fallback);
         assert!(snap.module_name_from_globals);
+        assert!(snap.propagate_script_exit);
         reset_policy();
     }
 
@@ -163,6 +168,7 @@ mod tests {
                 ENV_JSON_ERRORS,
                 ENV_CAPTURE_IO,
                 ENV_MODULE_NAME_FROM_GLOBALS,
+                ENV_PROPAGATE_SCRIPT_EXIT,
             ] {
                 std::env::remove_var(key);
             }

codetracer-python-recorder/src/policy/env.rs

@@ -21,6 +21,8 @@ pub const ENV_JSON_ERRORS: &str = "CODETRACER_JSON_ERRORS";
 pub const ENV_CAPTURE_IO: &str = "CODETRACER_CAPTURE_IO";
 /// Environment variable toggling globals-based module name resolution.
 pub const ENV_MODULE_NAME_FROM_GLOBALS: &str = "CODETRACER_MODULE_NAME_FROM_GLOBALS";
+/// Environment variable toggling whether the recorder mirrors script exit codes.
+pub const ENV_PROPAGATE_SCRIPT_EXIT: &str = "CODETRACER_PROPAGATE_SCRIPT_EXIT";
 
 /// Load policy overrides from environment variables.
 pub fn configure_policy_from_env() -> RecorderResult<()> {
@@ -66,6 +68,10 @@ pub fn configure_policy_from_env() -> RecorderResult<()> {
         update.module_name_from_globals = Some(parse_bool(&value)?);
     }
 
+    if let Ok(value) = env::var(ENV_PROPAGATE_SCRIPT_EXIT) {
+        update.propagate_script_exit = Some(parse_bool(&value)?);
+    }
+
     apply_policy_update(update);
     Ok(())
 }
@@ -148,6 +154,7 @@ mod tests {
         std::env::set_var(ENV_JSON_ERRORS, "yes");
         std::env::set_var(ENV_CAPTURE_IO, "proxies,fd");
         std::env::set_var(ENV_MODULE_NAME_FROM_GLOBALS, "true");
+        std::env::set_var(ENV_PROPAGATE_SCRIPT_EXIT, "true");
 
         configure_policy_from_env().expect("configure from env");
         let snap = policy_snapshot();
@@ -163,17 +170,20 @@ mod tests {
         assert!(snap.io_capture.line_proxies);
         assert!(snap.io_capture.fd_fallback);
         assert!(snap.module_name_from_globals);
+        assert!(snap.propagate_script_exit);
     }
 
     #[test]
     fn configure_policy_from_env_disables_module_name_from_globals() {
         let _guard = EnvGuard;
         reset_policy_for_tests();
         std::env::set_var(ENV_MODULE_NAME_FROM_GLOBALS, "false");
+        std::env::set_var(ENV_PROPAGATE_SCRIPT_EXIT, "false");
 
         configure_policy_from_env().expect("configure from env");
         let snap = policy_snapshot();
         assert!(!snap.module_name_from_globals);
+        assert!(!snap.propagate_script_exit);
     }
 
     #[test]
@@ -202,6 +212,7 @@ mod tests {
                 ENV_JSON_ERRORS,
                 ENV_CAPTURE_IO,
                 ENV_MODULE_NAME_FROM_GLOBALS,
+                ENV_PROPAGATE_SCRIPT_EXIT,
             ] {
                 std::env::remove_var(key);
             }

codetracer-python-recorder/src/policy/ffi.rs

@@ -11,7 +11,7 @@ use std::path::PathBuf;
 use std::str::FromStr;
 
 #[pyfunction(name = "configure_policy")]
-#[pyo3(signature = (on_recorder_error=None, require_trace=None, keep_partial_trace=None, log_level=None, log_file=None, json_errors=None, io_capture_line_proxies=None, io_capture_fd_fallback=None, module_name_from_globals=None))]
+#[pyo3(signature = (on_recorder_error=None, require_trace=None, keep_partial_trace=None, log_level=None, log_file=None, json_errors=None, io_capture_line_proxies=None, io_capture_fd_fallback=None, module_name_from_globals=None, propagate_script_exit=None))]
 pub fn configure_policy_py(
     on_recorder_error: Option<&str>,
     require_trace: Option<bool>,
@@ -22,6 +22,7 @@ pub fn configure_policy_py(
     io_capture_line_proxies: Option<bool>,
     io_capture_fd_fallback: Option<bool>,
     module_name_from_globals: Option<bool>,
+    propagate_script_exit: Option<bool>,
 ) -> PyResult<()> {
     let mut update = PolicyUpdate::default();
 
@@ -69,6 +70,10 @@ pub fn configure_policy_py(
         update.module_name_from_globals = Some(value);
     }
 
+    if let Some(value) = propagate_script_exit {
+        update.propagate_script_exit = Some(value);
+    }
+
     apply_policy_update(update);
     Ok(())
 }
@@ -106,6 +111,7 @@ pub fn py_policy_snapshot(py: Python<'_>) -> PyResult<PyObject> {
         "module_name_from_globals",
         snapshot.module_name_from_globals,
     )?;
+    dict.set_item("propagate_script_exit", snapshot.propagate_script_exit)?;
 
     let io_dict = PyDict::new(py);
     io_dict.set_item("line_proxies", snapshot.io_capture.line_proxies)?;
@@ -133,6 +139,7 @@ mod tests {
             Some(true),
             Some(true),
             Some(true),
+            Some(true),
         )
         .expect("configure policy via PyO3 facade");
 
@@ -152,6 +159,7 @@ mod tests {
         assert!(snap.io_capture.line_proxies);
         assert!(snap.io_capture.fd_fallback);
         assert!(snap.module_name_from_globals);
+        assert!(snap.propagate_script_exit);
         reset_policy_for_tests();
     }
 
@@ -168,6 +176,7 @@ mod tests {
             None,
             None,
             None,
+            None,
         )
         .expect_err("invalid variant should error");
         // Ensure the error maps through map_recorder_error by checking the display text.
@@ -208,6 +217,7 @@ mod tests {
             Some(false),
             Some(false),
             Some(false),
+            Some(true),
         )
         .expect("configure policy");
 
@@ -224,6 +234,11 @@ mod tests {
                 dict.contains("io_capture").expect("check io_capture key"),
                 "expected io_capture in snapshot"
             );
+            assert!(
+                dict.contains("propagate_script_exit")
+                    .expect("check propagate_script_exit key"),
+                "expected propagate_script_exit in snapshot"
+            );
         });
         reset_policy_for_tests();
     }
@@ -241,6 +256,7 @@ mod tests {
                 super::super::env::ENV_JSON_ERRORS,
                 super::super::env::ENV_CAPTURE_IO,
                 super::super::env::ENV_MODULE_NAME_FROM_GLOBALS,
+                super::super::env::ENV_PROPAGATE_SCRIPT_EXIT,
             ] {
                 std::env::remove_var(key);
             }

codetracer-python-recorder/src/policy/model.rs

@@ -72,6 +72,7 @@ pub struct RecorderPolicy {
     pub json_errors: bool,
     pub io_capture: IoCapturePolicy,
     pub module_name_from_globals: bool,
+    pub propagate_script_exit: bool,
 }
 
 impl Default for RecorderPolicy {
@@ -85,6 +86,7 @@ impl Default for RecorderPolicy {
             json_errors: false,
             io_capture: IoCapturePolicy::default(),
             module_name_from_globals: true,
+            propagate_script_exit: false,
         }
     }
 }
@@ -128,6 +130,9 @@ impl RecorderPolicy {
         if let Some(module_name_from_globals) = update.module_name_from_globals {
             self.module_name_from_globals = module_name_from_globals;
         }
+        if let Some(propagate_script_exit) = update.propagate_script_exit {
+            self.propagate_script_exit = propagate_script_exit;
+        }
     }
 }
 
@@ -150,6 +155,7 @@ pub(crate) struct PolicyUpdate {
     pub(crate) io_capture_line_proxies: Option<bool>,
     pub(crate) io_capture_fd_fallback: Option<bool>,
     pub(crate) module_name_from_globals: Option<bool>,
+    pub(crate) propagate_script_exit: Option<bool>,
 }
 
 /// Snapshot the current policy.