[wangyinz]

Fixes #854

What changed

• forward the irregular-sampling abort option exactly
• honor median and caller-supplied initial stack seeds
• compute convergence with a stable relative L2 norm without aliasing the prior stack
• define zero, non-finite, success, and 20-iteration exhaustion behavior
• return a dead beam with exactly one Invalid diagnostic on exhaustion and avoid writing final shifts
• remove unexpected stdout and correct the user manual's option status

Root cause and impact

The convergence loop aliased stack state, had an unreachable exhaustion check, and ignored documented options. This could falsely report convergence, silently continue after exhaustion, or initialize from the wrong stack.

Validation

• focused contract plus existing MCXcor tests: 23 passed
• exact audited baseline: 7/7 contract tests failed
• Black, Python 3.12/3.13 py_compile, git diff --check, and Sphinx dummy build: passed
• independent agent review: REVIEW PASS

This PR is ready for human review and is intentionally not merged.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.50%. Comparing base (3ea520b) to head (650cec1).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #983      +/-   ##
==========================================
+ Coverage   71.48%   71.50%   +0.01%     
==========================================
  Files         182      182              
  Lines       35666    35667       +1     
  Branches     2532     2532              
==========================================
+ Hits        25496    25502       +6     
+ Misses       9264     9259       -5     
  Partials      906      906              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.