Report total emulated cycles at exit under --clock-mhz

[sidick]

Follow-up to #103.

--clock-mhz gave volamos a cycle counter, but only an indirect way to
read it: the guest program itself had to call ReadEClock and report its
own elapsed time. That works for an instrumented benchmark like
BenchWork, but it leaves an
uninstrumented binary unmeasurable.

vamos has not had that limitation — vamos -v prints a total cycles:
line for any run, straight out of its main loop
(amitools/vamos/main.py, summing Musashi's per-call cycle returns).
This closes the gap.

What it does

$ volamos --clock-mhz 25 ./bench
...program output...
volamos: 340020 emulated cycles, 0.013601 s at 25 MHz

Nothing is printed without --clock-mhz, because on the default
run_batch path there is no cycle count to print — BatchResult carries
only an instruction count. That's also why Runtime::emulated_cycles()
returns Option rather than u64: reporting 0 on the uncounted path
would read as "this run took no time" instead of "this run was never
counted".

Two deliberate choices:

• stderr, not stdout — a harness parsing the guest program's own
  output must never have this line spliced into it.
• printed even when the run ends in an error — a benchmark that died
  part-way still burned the cycles it burned, and "how far did it get" is
  usually the first question.

Cross-check against vamos

Same binary, same two runtimes:

CPU	volamos	vamos	delta
68000	340,020	339,044	+0.3%
--cpu 68020	157,436	155,855	+1.0%

These come from entirely independent cycle models — the m68k crate's
per-CPU timing tables (timing.rs, timing_020/040/060.rs) versus
Musashi's — so the agreement is mutual corroboration rather than a shared
assumption. Both are deterministic across repeated runs.

This doesn't make either accurate in absolute terms; the caveats from
#103 all still apply, the wait-state one especially. It does mean the two
oracles can now be compared on a directly equivalent number, which the
existing vamos comparison harness can use.

Changes

• dispatch.rs: Runtime::emulated_cycles() — the top-level run's count
  and the rate it was counted at. A nested System()/Execute() child
  keeps its own counter from 0, the same boundary ReadEClock already
  reports across, so its cycles aren't folded in here.
• main.rs: report_emulated_cycles at exit, with the formatting split
  into a pure format_emulated_cycles so the wording and arithmetic are
  testable without capturing stderr.
• userdocs/CLI-Reference.md: documents the line, and the vamos
  comparison above.

Testing

cargo test --workspace: 1038 passed, 0 failed. Build, clippy
(--all-targets) and fmt --check clean.

New tests cover the accessor's None/Some split, the seconds
conversion and quoted MHz (including a fractional rate), a zero-cycle
run still reporting, and a non-positive or NaN rate formatting to nothing
rather than to inf.

One incidental fix: restored a #[test] attribute on the existing
no_jit_flag_after_jit_wins, which this branch's first draft had
accidentally orphaned — it was silently not running. It passes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EHvk3UiKvgnG2xb71UJ67R