Recorder exit code policy

[tzanko-matev]

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.

[tzanko-matev]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Breezy!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Coverage Summary

Rust (lines)
82.1% covered (8,274 / 10,083 | 1,809 missed)

File	Lines	Miss	Cover
codetracer-python-recorder/src/logging/logger.rs	273	64	76.6%
codetracer-python-recorder/src/module_identity.rs	181	28	84.5%
codetracer-python-recorder/src/monitoring/api.rs	165	152	7.9%
codetracer-python-recorder/src/monitoring/callbacks.rs	589	68	88.5%
codetracer-python-recorder/src/runtime/frame_inspector.rs	148	63	57.4%
codetracer-python-recorder/src/runtime/io_capture/fd_mirror/unix.rs	376	79	79.0%
codetracer-python-recorder/src/runtime/io_capture/proxies/common.rs	159	62	61.0%
codetracer-python-recorder/src/runtime/io_capture/proxies/input.rs	128	91	28.9%
codetracer-python-recorder/src/runtime/io_capture/proxies/output.rs	41	27	34.1%
codetracer-python-recorder/src/runtime/tracer/events.rs	422	191	54.7%
codetracer-python-recorder/src/runtime/tracer/filtering.rs	144	38	73.6%
codetracer-python-recorder/src/runtime/tracer/io.rs	158	31	80.4%
codetracer-python-recorder/src/runtime/tracer/lifecycle.rs	279	72	74.2%
codetracer-python-recorder/src/runtime/tracer/runtime_tracer.rs	2,088	82	96.1%
codetracer-python-recorder/src/runtime/value_capture.rs	267	85	68.2%
codetracer-python-recorder/src/session.rs	85	85	0.0%
codetracer-python-recorder/src/session/bootstrap/filesystem.rs	90	32	64.4%
codetracer-python-recorder/src/trace_filter/engine.rs	585	52	91.1%
codetracer-python-recorder/src/trace_filter/loader.rs	445	202	54.6%
codetracer-python-recorder/src/trace_filter/selector.rs	258	66	74.4%
Showing top 20 entries by missed lines (of 53 total).

Python (statements)
74.7% covered (283 / 379 | 96 missed)

File	Stmts	Miss	Cover
codetracer-python-recorder/codetracer_python_recorder/__init__.py	7	0	100.0%
codetracer-python-recorder/codetracer_python_recorder/__main__.py	2	2	0.0%
codetracer-python-recorder/codetracer_python_recorder/api.py	5	0	100.0%
codetracer-python-recorder/codetracer_python_recorder/auto_start.py	24	2	91.7%
codetracer-python-recorder/codetracer_python_recorder/cli.py	165	80	51.5%
codetracer-python-recorder/codetracer_python_recorder/formats.py	13	1	92.3%
codetracer-python-recorder/codetracer_python_recorder/session.py	111	5	95.5%
codetracer-python-recorder/codetracer_python_recorder/trace_balance.py	52	6	88.5%

Generated automatically via generate_coverage_comment.py.