WS1

codetracer-python-recorder/codetracer_python_recorder/cli.py: 
codetracer-python-recorder/codetracer_python_recorder/session.py: 
codetracer-python-recorder/src/session.rs: 
codetracer-python-recorder/tests/python/unit/test_auto_start.py: 
codetracer-python-recorder/tests/python/unit/test_session_helpers.py: 
design-docs/toplevel-exit-and-trace-gating-implementation-plan.status.md: 
pytest.log: 
pytest_case.log: 

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

Author: tzanko-matev

codetracer-python-recorder/codetracer_python_recorder/cli.py

@@ -287,7 +287,7 @@ def main(argv: Iterable[str] | None = None) -> int:
         try:
             flush()
         finally:
-            stop()
+            stop(exit_code=exit_code)
             sys.argv = old_argv
 
     _serialise_metadata(trace_dir, script=script_path)

codetracer-python-recorder/codetracer_python_recorder/session.py

@@ -38,10 +38,17 @@ def __init__(self, path: Path, format: str) -> None:
         self.path = path
         self.format = format
 
-    def stop(self) -> None:
-        """Stop this trace session."""
+    def stop(self, *, exit_code: int | None = None) -> None:
+        """Stop this trace session.
+
+        Parameters
+        ----------
+        exit_code:
+            Optional process exit status to forward to the recorder backend.
+            When ``None``, the session shutdown reason remains unspecified.
+        """
         if _active_session is self:
-            stop()
+            stop(exit_code=exit_code)
 
     def flush(self) -> None:
         """Flush buffered trace data for this session."""
@@ -51,6 +58,7 @@ def __enter__(self) -> "TraceSession":
         return self
 
     def __exit__(self, exc_type, exc, tb) -> None:  # pragma: no cover - thin wrapper
+        # Exit codes are not tracked for context-managed sessions; report unknown.
         self.stop()
 
 
@@ -121,12 +129,18 @@ def start(
     return session
 
 
-def stop() -> None:
-    """Stop the active trace session if one is running."""
+def stop(*, exit_code: int | None = None) -> None:
+    """Stop the active trace session if one is running.
+
+    Parameters
+    ----------
+    exit_code:
+        Optional process exit status to forward to the backend.
+    """
     global _active_session
     if not _is_tracing_backend():
         return
-    _stop_backend()
+    _stop_backend(exit_code)
     _active_session = None
 
 

codetracer-python-recorder/src/session.rs

@@ -73,9 +73,10 @@ pub fn start_tracing(
 }
 
 /// Stop tracing by resetting the global flag.
-#[pyfunction]
-pub fn stop_tracing() -> PyResult<()> {
+#[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| {
             // Uninstall triggers finish() on tracer implementation.
             uninstall_tracer(py)?;

codetracer-python-recorder/tests/python/unit/test_auto_start.py

@@ -38,7 +38,7 @@ def fake_start_backend(
         state["active"] = True
         captured_filters.append(filters)
 
-    def fake_stop_backend() -> None:
+    def fake_stop_backend(exit_code: int | None = None) -> None:
         state["active"] = False
 
     monkeypatch.setenv(auto_start.ENV_TRACE_PATH, str(trace_dir))

codetracer-python-recorder/tests/python/unit/test_session_helpers.py

@@ -63,13 +63,13 @@ def clear_active_session() -> None:
 
 
 def test_trace_session_stop_clears_global(monkeypatch: pytest.MonkeyPatch) -> None:
-    called = {"stop": False, "start": False}
+    called = {"stop_exit_codes": [], "start": False}
 
     def fake_start(*args, **kwargs) -> None:
         called["start"] = True
 
-    def fake_stop() -> None:
-        called["stop"] = True
+    def fake_stop(exit_code: int | None = None) -> None:
+        called["stop_exit_codes"].append(exit_code)
 
     monkeypatch.setattr(session, "_start_backend", fake_start)
     monkeypatch.setattr(session, "_stop_backend", fake_stop)
@@ -78,7 +78,7 @@ def fake_stop() -> None:
     session._active_session = session.TraceSession(path=Path("/tmp"), format="json")
     session.stop()
     assert session._active_session is None
-    assert called["stop"] is True
+    assert called["stop_exit_codes"] == [None]
 
 
 def test_trace_session_flush_noop_when_inactive(monkeypatch: pytest.MonkeyPatch) -> None:
@@ -107,9 +107,9 @@ def fake_start(
         trace_state["active"] = True
         calls["start"].append((Path(path), fmt, activation, filters))
 
-    def fake_stop() -> None:
+    def fake_stop(exit_code: int | None = None) -> None:
         trace_state["active"] = False
-        calls["stop"].append(True)
+        calls["stop"].append(exit_code)
 
     monkeypatch.setattr(session, "_start_backend", fake_start)
     monkeypatch.setattr(session, "_stop_backend", fake_stop)
@@ -124,7 +124,19 @@ def fake_stop() -> None:
         assert handle.format == "binary"
 
     assert calls["start"] == [(target, "binary", None, None)]
-    assert calls["stop"] == [True]
+    assert calls["stop"] == [None]
+
+
+def test_stop_forwards_exit_code(monkeypatch: pytest.MonkeyPatch) -> None:
+    captured: list[int | None] = []
+
+    monkeypatch.setattr(session, "_is_tracing_backend", lambda: True)
+    monkeypatch.setattr(session, "_stop_backend", lambda code=None: captured.append(code))
+
+    session._active_session = session.TraceSession(path=Path("/tmp"), format="json")
+    session.stop(exit_code=123)
+    assert captured == [123]
+    assert session._active_session is None
 
 
 def test_normalize_trace_filter_handles_none() -> None:

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

@@ -0,0 +1,38 @@
+# Toplevel Exit & Trace Gating – Status
+
+## Relevant Design Docs
+- `design-docs/adr/0015-balanced-toplevel-lifecycle-and-trace-gating.md`
+- `design-docs/toplevel-exit-and-trace-gating-implementation-plan.md`
+
+## Key Source Files
+- `codetracer-python-recorder/src/session.rs`
+- `codetracer_python_recorder/session.py`
+- `codetracer_python_recorder/cli.py`
+- `codetracer-python-recorder/src/monitoring/install.rs`
+- `codetracer-python-recorder/src/monitoring/mod.rs`
+- `codetracer-python-recorder/tests/python` (planned additions)
+
+## Workstream Progress
+
+### WS1 – Public API & Session Plumbing
+- **Scope recap:** Teach `stop_tracing` to accept an optional exit code and propagate it through the Python helpers and CLI while keeping backwards compatibility.
+- **Status:** _Completed_
+  - `stop_tracing` now accepts an optional `exit_code` argument, and the Python session helpers/CLI forward the value.
+  - Added unit coverage ensuring `stop(exit_code=...)` forwards the value downstream while `stop()` remains valid.
+  - 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).
+
+### WS3 – Unified Trace Gate Abstraction
+- **Status:** _Not Started_.
+
+### WS4 – Lifecycle & Metadata Updates
+- **Status:** _Not Started_.
+
+### WS5 – Validation & Parity Follow-Up
+- **Status:** _Not Started_.
+
+## Notes
+- API changes will require a minor version bump once runtime support lands; capture release planning tasks after WS2.
+- Remember to bootstrap the dev build (`just dev`) before Python suites so integration-test hooks stay enabled.