[kvnloo]

Scope

Closes no issue automatically. Tracks #266.

Base: dev at 1660a83372f1cba1fb34003a1af9d9847a7609bf
Head: chatgpt/n27-z0int-freefanout

Changed files

• Added tests/test_free_fanout_units.py (10 hermetic pytest tests).
• No production module, dependency, lockfile or CI changes.

Tests / acceptance map

• test_plan_for_shape — Exact single-candidate plan metadata

• test_fanout_plan_inserts_root_once_and_calls_build_fanout — Fake Kerdoios import, root insertion without duplication, 3/default-5 workers

• test_one_passes_free_only_task_to_execute_plan — Free-only task arguments, policy/provider identity, plan and receipt sink

• test_one_projects_attempts — Attempt-field projection, absent extras, missing/None attempts and refusal passthrough

• test_one_maps_execute_plan_exception_to_class_name — RuntimeError class-only mapping without leaking message/model

• test_one_refuses_when_no_free_route_without_executing — No validated route refuses before dispatch

• test_run_report_fields — Full report schema, requested worker count, ordered rows, plan identity, working count

• test_run_with_no_slots — Zero-slot pool clamp and empty report

• test_main_parses_workers_flag_and_exit_codes — Explicit/default/sys.argv workers, JSON stdout and both exit codes

• test_main_bad_workers_value — ValueError/IndexError for bad/missing flag without run

• All 10 named tests authored, using stdlib + pytest + z0int.free_fanout.

• Error/edge-path coverage: missing attempt metadata, execution exceptions, no validated route, empty slots, invalid CLI worker values.

• External calls replaced by fakes: blocked_provider, configuration, free_route, execute_plan, and plan builder (or fanout_plan where relevant); Z0INT_HOME isolated; sys.modules/sys.path patched for import handling. No network or real receipts.

• Diff verified through connector: only tests/test_free_fanout_units.py changed.

• Runtime test results require execution by maintainer/CI.

Verification

tests NOT RUN - ChatGPT cannot execute code
tests NOT RUN (written via connector)

Run from repository root:

pip install -e '.[test]' && python -m pytest -q tests/test_free_fanout_units.py

Optional existing regression suite:

python -m pytest -q tests/test_free_fanout_free_only.py

No pass counts, CI status or runtime evidence are claimed.