feat(trace): add JSONL timing traces to helix evolve

[KE7]

What

helix evolve --trace PATH and helix resume --trace PATH (or HELIX_TRACE=PATH) append a JSON Lines timing trace of the run, so you can see where the wall clock went: proposals vs. sequential validation, evaluator vs. agent time, per generation.

Design: one decorator, no splits

The whole feature is helix.trace.traced(span), a functools.wraps decorator applied to functions that already exist on main and whose whole body is exactly the span we want:

span	decorated function	measures
run	run_evolution	the whole run; its end is always the last line
proposal	_run_proposal_worker	one proposal slot (parent eval, mutation, child eval)
evaluate	run_evaluator	one evaluator invocation
validate	_run_full_val_eval	one sequential full-validation stage
agent	invoke_claude_code	one agent-backend call (mutation inside a proposal, seed generation inside seed, otherwise a merge)
seed	generate_seed	seedless-mode seed generation

Why this shape:

• No function splits, no signature drift. The core change is 9 added / 2 changed lines in executor.py, evolution.py, mutator.py (merger.py untouched): three import edits and six @traced("...") lines. Nothing to keep in sync when a signature changes.
• Exception-safe. The decorator's finally classifies any BaseException (KeyboardInterrupt included), writes the end record, and re-raises untouched. A failing sink is reported once via logger.error("Trace unavailable: ...") and can never mask the exception in flight.
• Near-zero cost when disabled. The wrapper checks one module-level flag and calls through; attrs extraction does not even run.
• Thread-safe append-and-flush sink. Opened once by trace.enable(), a threading.Lock around each write, flushed per record. No footer protocol, no counters, no loader.

Event schema

{"event": "start", "span": "evaluate", "span_id": 7, "wall_time": 1757400000.1, "monotonic": 1234.5, "thread_id": 6199, "attrs": {"candidate_id": "g1-s2", "split": "train", "evaluation_phase": null}}
{"event": "end",   "span": "evaluate", "span_id": 7, "wall_time": 1757400012.3, "monotonic": 1246.7, "thread_id": 6199, "attrs": {...}, "duration_seconds": 12.2, "outcome": "ok"}

outcome is "ok" or "error"; on error error_type carries the exception class name only (never the message). attrs is a small per-span identity dict: candidate id and generation for proposal, candidate id / split / evaluation phase for evaluate, candidate id for validate, the prompt artifact name for agent. Match start to end on span_id (proposal workers interleave).

Truncation

A trace is complete iff its last line is {"event": "end", "span": "run", ...}. Anything else means the process died mid-run and later spans are missing; every record before it is still whole (each is flushed as written).

Gates

• uv run python -m pytest -q — 1003 passed
• uv run ruff check src/ tests/ — clean
• uv run mypy --strict src/helix/ — clean
• git diff --stat origin/main -- src/helix/{executor,evolution,mutator,merger}.py — 3 files, 9 insertions(+), 2 deletions(-)

Previous implementation (wrapper-based) preserved at commit 93ef401 for reference.

🤖 Generated with Claude Code

https://claude.ai/code/session_015HBBoDVQK7baNMQBhgRkh4