WS2

codetracer-python-recorder/src/monitoring/api.rs: 
codetracer-python-recorder/src/monitoring/install.rs: 
codetracer-python-recorder/src/monitoring/mod.rs: 
codetracer-python-recorder/src/runtime/tracer/events.rs: 
codetracer-python-recorder/src/runtime/tracer/runtime_tracer.rs: 
codetracer-python-recorder/src/session.rs: 
codetracer-python-recorder/tests/python/test_exit_payloads.py: 
design-docs/toplevel-exit-and-trace-gating-implementation-plan.status.md: 

Signed-off-by: Tzanko Matev <[email protected]>

Author: tzanko-matev

codetracer-python-recorder/src/monitoring/api.rs

@@ -107,6 +107,15 @@ pub trait Tracer: Send + Any {
         Ok(())
     }
 
+    /// Provide the process exit status ahead of tracer teardown.
+    fn set_exit_status(
+        &mut self,
+        _py: Python<'_>,
+        _exit_code: Option<i32>,
+    ) -> PyResult<()> {
+        Ok(())
+    }
+
     /// Called on resumption of a generator/coroutine (not via throw()).
     fn on_py_resume(
         &mut self,

codetracer-python-recorder/src/monitoring/install.rs

@@ -82,3 +82,11 @@ pub fn flush_installed_tracer(py: Python<'_>) -> PyResult<()> {
     }
     Ok(())
 }
+
+/// Provide the session exit status to the active tracer if one is installed.
+pub fn update_exit_status(py: Python<'_>, exit_code: Option<i32>) -> PyResult<()> {
+    if let Some(global) = GLOBAL.lock().unwrap().as_mut() {
+        global.tracer.set_exit_status(py, exit_code)?;
+    }
+    Ok(())
+}

codetracer-python-recorder/src/monitoring/mod.rs

@@ -10,7 +10,12 @@ pub(crate) mod install;
 pub mod tracer;
 
 pub use api::Tracer;
-pub use install::{flush_installed_tracer, install_tracer, uninstall_tracer};
+pub use install::{
+    flush_installed_tracer,
+    install_tracer,
+    uninstall_tracer,
+    update_exit_status,
+};
 
 const MONITORING_TOOL_NAME: &str = "codetracer";
 

codetracer-python-recorder/src/runtime/tracer/events.rs

@@ -439,8 +439,17 @@ impl Tracer for RuntimeTracer {
         )
     }
 
+    fn set_exit_status(
+        &mut self,
+        _py: Python<'_>,
+        exit_code: Option<i32>,
+    ) -> PyResult<()> {
+        self.record_exit_status(exit_code);
+        Ok(())
+    }
+
     fn notify_failure(&mut self, _py: Python<'_>) -> PyResult<()> {
-        self.mark_failure();
+        self.mark_disabled();
         Ok(())
     }
 
@@ -484,6 +493,8 @@ impl Tracer for RuntimeTracer {
             self.mark_event();
         }
 
+        self.emit_session_exit(py);
+
         if self.lifecycle.encountered_failure() {
             if policy.keep_partial_trace {
                 if let Err(err) = self.lifecycle.finalise(&mut self.writer, &self.filter) {

codetracer-python-recorder/src/runtime/tracer/runtime_tracer.rs

@@ -9,15 +9,92 @@ use crate::policy::RecorderPolicy;
 use crate::runtime::io_capture::{IoCaptureSettings, ScopedMuteIoCapture};
 use crate::runtime::line_snapshots::LineSnapshotStore;
 use crate::runtime::output_paths::TraceOutputPaths;
+use crate::runtime::value_encoder::encode_value;
 use crate::trace_filter::engine::TraceFilterEngine;
 use pyo3::prelude::*;
+use pyo3::types::{PyAny, PyInt, PyString};
 use runtime_tracing::NonStreamingTraceWriter;
 use runtime_tracing::{Line, TraceEventsFileFormat, TraceWriter};
+use std::borrow::Cow;
 use std::collections::HashMap;
 use std::path::Path;
 use std::sync::Arc;
 use std::thread::ThreadId;
 
+#[derive(Debug)]
+enum ExitPayload {
+    Code(i32),
+    Text(Cow<'static, str>),
+}
+
+impl ExitPayload {
+    fn is_code(&self) -> bool {
+        matches!(self, ExitPayload::Code(_))
+    }
+
+    #[cfg(test)]
+    fn is_text(&self, text: &str) -> bool {
+        matches!(self, ExitPayload::Text(current) if current.as_ref() == text)
+    }
+}
+
+#[derive(Debug)]
+struct SessionExitState {
+    payload: ExitPayload,
+    emitted: bool,
+}
+
+impl Default for SessionExitState {
+    fn default() -> Self {
+        Self {
+            payload: ExitPayload::Text(Cow::Borrowed("<exit>")),
+            emitted: false,
+        }
+    }
+}
+
+impl SessionExitState {
+    fn set_exit_code(&mut self, exit_code: Option<i32>) {
+        if self.can_override_with_code() {
+            self.payload = exit_code
+                .map(ExitPayload::Code)
+                .unwrap_or_else(|| ExitPayload::Text(Cow::Borrowed("<exit>")));
+        }
+    }
+
+    fn mark_disabled(&mut self) {
+        if !self.payload.is_code() {
+            self.payload = ExitPayload::Text(Cow::Borrowed("<disabled>"));
+        }
+    }
+
+    #[cfg(test)]
+    fn mark_failure(&mut self) {
+        if !self.payload.is_code() && !self.payload.is_text("<disabled>") {
+            self.payload = ExitPayload::Text(Cow::Borrowed("<failure>"));
+        }
+    }
+
+    fn can_override_with_code(&self) -> bool {
+        matches!(&self.payload, ExitPayload::Text(current) if current.as_ref() == "<exit>")
+    }
+
+    fn as_bound<'py>(&self, py: Python<'py>) -> Bound<'py, PyAny> {
+        match &self.payload {
+            ExitPayload::Code(value) => PyInt::new(py, *value).into_any(),
+            ExitPayload::Text(text) => PyString::new(py, text.as_ref()).into_any(),
+        }
+    }
+
+    fn mark_emitted(&mut self) {
+        self.emitted = true;
+    }
+
+    fn is_emitted(&self) -> bool {
+        self.emitted
+    }
+}
+
 /// Minimal runtime tracer that maps Python sys.monitoring events to
 /// runtime_tracing writer operations.
 pub struct RuntimeTracer {
@@ -28,6 +105,7 @@ pub struct RuntimeTracer {
     pub(super) io: IoCoordinator,
     pub(super) filter: FilterCoordinator,
     pub(super) module_names: ModuleIdentityCache,
+    session_exit: SessionExitState,
 }
 
 impl RuntimeTracer {
@@ -49,6 +127,7 @@ impl RuntimeTracer {
             io: IoCoordinator::new(),
             filter: FilterCoordinator::new(trace_filter),
             module_names: ModuleIdentityCache::new(),
+            session_exit: SessionExitState::default(),
         }
     }
 
@@ -78,6 +157,18 @@ impl RuntimeTracer {
         }
     }
 
+    pub(super) fn emit_session_exit(&mut self, py: Python<'_>) {
+        if self.session_exit.is_emitted() {
+            return;
+        }
+
+        self.flush_pending_io();
+        let value = self.session_exit.as_bound(py);
+        let record = encode_value(py, &mut self.writer, &value);
+        TraceWriter::register_return(&mut self.writer, record);
+        self.session_exit.mark_emitted();
+    }
+
     /// Configure output files and write initial metadata records.
     pub fn begin(&mut self, outputs: &TraceOutputPaths, start_line: u32) -> PyResult<()> {
         self.lifecycle
@@ -95,10 +186,21 @@ impl RuntimeTracer {
         self.lifecycle.mark_event();
     }
 
+    #[cfg(test)]
     pub(super) fn mark_failure(&mut self) {
+        self.session_exit.mark_failure();
         self.lifecycle.mark_failure();
     }
 
+    pub(super) fn mark_disabled(&mut self) {
+        self.session_exit.mark_disabled();
+        self.lifecycle.mark_failure();
+    }
+
+    pub(super) fn record_exit_status(&mut self, exit_code: Option<i32>) {
+        self.session_exit.set_exit_code(exit_code);
+    }
+
     pub(super) fn ensure_function_id(
         &mut self,
         py: Python<'_>,
@@ -1326,6 +1428,45 @@ initializer("omega")
         });
     }
 
+    #[test]
+    fn finish_emits_toplevel_return_with_exit_code() {
+        Python::with_gil(|py| {
+            reset_policy(py);
+
+            let script_dir = tempfile::tempdir().expect("script dir");
+            let program_path = script_dir.path().join("program.py");
+            std::fs::write(&program_path, "print('hi')\n").expect("write program");
+
+            let outputs_dir = tempfile::tempdir().expect("outputs dir");
+            let outputs = TraceOutputPaths::new(outputs_dir.path(), TraceEventsFileFormat::Json);
+
+            let mut tracer = RuntimeTracer::new(
+                program_path.to_string_lossy().as_ref(),
+                &[],
+                TraceEventsFileFormat::Json,
+                None,
+                None,
+            );
+            tracer.begin(&outputs, 1).expect("begin tracer");
+            tracer.record_exit_status(Some(7));
+
+            tracer.finish(py).expect("finish tracer");
+
+            let mut exit_value: Option<ValueRecord> = None;
+            for event in &tracer.writer.events {
+                if let TraceLowLevelEvent::Return(record) = event {
+                    exit_value = Some(record.return_value.clone());
+                }
+            }
+
+            let exit_value = exit_value.expect("expected toplevel return value");
+            match exit_value {
+                ValueRecord::Int { i, .. } => assert_eq!(i, 7),
+                other => panic!("expected integer exit value, got {other:?}"),
+            }
+        });
+    }
+
     #[test]
     fn trace_filter_metadata_includes_summary() {
         Python::with_gil(|py| {

codetracer-python-recorder/src/session.rs

@@ -10,7 +10,12 @@ use recorder_errors::{usage, ErrorCode};
 
 use crate::ffi;
 use crate::logging::init_rust_logging_with_default;
-use crate::monitoring::{flush_installed_tracer, install_tracer, uninstall_tracer};
+use crate::monitoring::{
+    flush_installed_tracer,
+    install_tracer,
+    uninstall_tracer,
+    update_exit_status,
+};
 use crate::policy::policy_snapshot;
 use crate::runtime::{RuntimeTracer, TraceOutputPaths};
 use bootstrap::TraceSessionBootstrap;
@@ -76,8 +81,8 @@ pub fn start_tracing(
 #[pyfunction(signature = (exit_code=None))]
 pub fn stop_tracing(exit_code: Option<i32>) -> PyResult<()> {
     ffi::wrap_pyfunction("stop_tracing", || {
-        let _ = exit_code;
         Python::with_gil(|py| {
+            update_exit_status(py, exit_code)?;
             // Uninstall triggers finish() on tracer implementation.
             uninstall_tracer(py)?;
             ACTIVE.store(false, Ordering::SeqCst);

codetracer-python-recorder/tests/python/test_exit_payloads.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from codetracer_python_recorder.trace_balance import load_trace_events
+
+
+def _last_return_value(trace_dir: Path) -> dict[str, object]:
+    events = load_trace_events(trace_dir / "trace.json")
+    for event in reversed(events):
+        payload = event.get("Return")
+        if payload is not None:
+            return payload["return_value"]
+    raise AssertionError("trace did not contain any Return events")
+
+
+def test_cli_records_exit_code_in_toplevel_return(tmp_path: Path) -> None:
+    script = tmp_path / "exit_script.py"
+    script.write_text(
+        "import sys\n"
+        "sys.exit(3)\n",
+        encoding="utf-8",
+    )
+
+    trace_dir = tmp_path / "trace"
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "codetracer_python_recorder",
+            "--trace-dir",
+            str(trace_dir),
+            "--format",
+            "json",
+            str(script),
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    assert result.returncode == 3, result.stderr
+    exit_value = _last_return_value(trace_dir)
+    assert exit_value["kind"] == "Int"
+    assert exit_value["i"] == 3
+
+
+def test_default_exit_payload_uses_placeholder(tmp_path: Path) -> None:
+    trace_dir = tmp_path / "trace"
+    trace_dir.mkdir()
+
+    # Directly call the start/stop API without providing an exit code.
+    script = (
+        "import json\n"
+        "from pathlib import Path\n"
+        "import codetracer_python_recorder as codetracer\n"
+        f"trace_dir = Path({json.dumps(str(trace_dir))!s})\n"
+        "session = codetracer.start(trace_dir, format='json')\n"
+        "session.stop()\n"
+    )
+    subprocess.run([sys.executable, "-c", script], check=True)
+
+    exit_value = _last_return_value(trace_dir)
+    assert exit_value["kind"] == "String"
+    assert exit_value["text"] == "<exit>"

design-docs/toplevel-exit-and-trace-gating-implementation-plan.status.md

@@ -22,7 +22,10 @@
   - Verification: `just dev` (editable build with `integration-test` feature) and `just py-test` (Python suites across both recorders) pass.
 
 ### WS2 – Runtime Exit State & `<toplevel>` Return Emission
-- **Status:** _Not Started_ (blocked on WS1 API plumbing).
+- **Status:** _Completed_
+  - `RuntimeTracer` now tracks a `SessionExitState`, emits the `<toplevel>` return during `finish`, and differentiates between explicit exit codes, default exits, and policy-driven disables.
+  - Added trait plumbing (`Tracer::set_exit_status`) plus installer wiring so `stop_tracing` can forward the exit code before teardown.
+  - Verification: `just cargo-test` (workspace) and `just py-test` exercises the new Rust test (`finish_emits_toplevel_return_with_exit_code`) and Python integration tests (`test_exit_payloads`).
 
 ### WS3 – Unified Trace Gate Abstraction
 - **Status:** _Not Started_.