WS2

Author: tzanko-matev

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/tests/python/test_exit_payloads.py

@@ -44,7 +44,8 @@ def test_cli_records_exit_code_in_toplevel_return(tmp_path: Path) -> None:
         check=False,
     )
 
-    assert result.returncode == 3, result.stderr
+    assert result.returncode == 0, result.stderr
+    assert "status 3; returning 0" in result.stderr
     exit_value = _last_return_value(trace_dir)
     assert exit_value["kind"] == "Int"
     assert exit_value["i"] == 3
@@ -54,6 +55,43 @@ def test_cli_records_exit_code_in_toplevel_return(tmp_path: Path) -> None:
     assert status == {"code": 3, "label": None}
 
 
+def test_cli_can_propagate_script_exit(tmp_path: Path) -> None:
+    script = tmp_path / "exit_script.py"
+    script.write_text(
+        "import sys\n"
+        "sys.exit(5)\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",
+            "--propagate-script-exit",
+            str(script),
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    assert result.returncode == 5, result.stderr
+    assert "status 5; returning 0" not in result.stderr
+    exit_value = _last_return_value(trace_dir)
+    assert exit_value["kind"] == "Int"
+    assert exit_value["i"] == 5
+
+    metadata = json.loads((trace_dir / "trace_metadata.json").read_text(encoding="utf-8"))
+    status = metadata.get("process_exit_status")
+    assert status == {"code": 5, "label": None}
+
+
 def test_default_exit_payload_uses_placeholder(tmp_path: Path) -> None:
     trace_dir = tmp_path / "trace"
     trace_dir.mkdir()

design-docs/recorder-exit-code-policy-implementation-plan.status.md

@@ -6,8 +6,8 @@
 
 ## Workstream Progress
 - ✅ **WS1 – Policy & Configuration Plumbing:** Added `propagate_script_exit` across `RecorderPolicy`, `PolicyUpdate`, PyO3 bindings, env parsing, and Python helpers; introduced `CODETRACER_PROPAGATE_SCRIPT_EXIT`; updated Rust + Python unit coverage; rebuilt the dev wheel (`maturin develop --features integration-test`) and verified via `just test`.
-- ☐ **WS2 – CLI Behaviour & Warning Surface:** _Not started._
+- ✅ **WS2 – CLI Behaviour & Warning Surface:** CLI now defaults to returning `0` on successful recordings, exposes `--propagate-script-exit`/`--no-propagate-script-exit`, emits a warning when suppressing non-zero script exits, and preserves non-zero statuses for recorder failures; added regression coverage (`test_exit_payloads.py`) and executed `just dev test`.
 - ☐ **WS3 – Documentation, Tooling, and Release Notes:** _Not started._
 
 ## Current Focus
-- Confirm no downstream consumers rely on the legacy policy snapshot schema; prepare CLI changes for WS2.
+- Plan WS3 documentation updates and release notes covering the new default exit behaviour and configuration surfaces.