Match Mobile300 custom trainer microstep semantics

[bingran-you]

Summary

Fixes the BenchFlow Prime-RL SFT compatibility profile for the env-0 Mobile300 / PR828 reproduction path by matching the old custom PEFT trainer's step semantics.

The historical custom trainer counted max_steps=300 as batch-size-1 micro-batches and only applied optimizer updates every 8 micro-batches. That means the saved adapter had 37 applied optimizer updates, with the final 4 micro-batches accumulated but not stepped. Prime-RL max_steps counts optimizer/trainer steps, so the previous --target-examples 300 mapping generated max_steps=38 and over-exposed the run relative to the source-of-truth custom trainer.

Changes:

• Adds --target-micro-steps to derive Prime-RL max_steps from custom-trainer micro-batch semantics.
• Updates env0-mobile300-pr828 compat profile to use target_micro_steps=300, producing max_steps=37 and scheduler.decay_steps=37.
• Records effective_train_examples and unapplied_micro_steps in the run manifest for auditability.
• Keeps generic --target-examples behavior unchanged: sample-exposure derivation still rounds up.
• Updates CLI docs and regression tests.

Known caveat: this is a BenchFlow wrapper/profile fix only. It does not patch Prime-RL internals. Remaining exact-equivalence gaps, if performance still does not recover, are likely deeper token/loss/truncation semantics inside Prime-RL rather than results.jsonl conversion or BenchFlow CLI command construction.

Validation

• uv run pytest tests/test_train_cli.py -q -> 27 passed
• uv run ruff format --check src/benchflow/training/backends/prime_rl.py src/benchflow/cli/train.py tests/test_train_cli.py -> 3 files already formatted
• uv run ruff check -> All checks passed
• uv run ty check src/benchflow/training/backends/prime_rl.py src/benchflow/cli/train.py -> All checks passed
• uv run bench train run sft --help -> exposes --target-micro-steps
• Full suite before final formatting: uv run pytest -q -> 4704 passed, 14 skipped, 7 deselected

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5175ddbb48

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Name the guarded commit in this regression test

The repo-root AGENTS.md requires regression tests to name the PR or commit they guard. This newly added test is a regression guard for the microstep semantics, but the docstring only describes the behavior, so future maintainers lose the required traceability; please include the guarded PR/commit identifier in the docstring.

Useful? React with 👍 / 👎.

[bingran-you]

Users Simulation automation review (2026-06-30T12:45Z): ready for this simulation scope.

Reviewed current head 5175ddbb486c86af1cab62eb0c2bb319a1de79c1, including the newly added --target-micro-steps path for the Mobile300 / PR828 Prime-RL reproduction profile.

Evidence:

• Local isolated worktree validation passed:
  • uv sync --extra dev --locked
  • uv run pytest tests/test_train_cli.py -q (27 passed)
  • uv run ruff check src/benchflow/training/backends/prime_rl.py src/benchflow/cli/train.py tests/test_train_cli.py
  • uv run ty check src/benchflow/training/backends/prime_rl.py src/benchflow/cli/train.py
  • uv run bench train run sft --help exposes --target-micro-steps and updates scheduler help text.
  • CLI/SDK smoke passed for bench --help, bench train --help, bench agent list, bench eval --help, bench tasks --help, RolloutConfig, Scene.single(...), and PrimeRlSftSpec(target_micro_steps=300).
• GitHub meaningful checks are green: test, pip-audit, parity, rollout-smoke, and detect-scope.
• Thermo-nuclear review did not find a structural blocker: the change is localized to the training CLI/wrapper/docs/tests and keeps generic --target-examples rounding behavior separate from custom-trainer microstep semantics.

No model rollout artifacts were produced in this review because this PR only changes the trainer command-generation path, not BenchFlow task execution. For this scope, the relevant trainer-facing evidence is the manifest/test coverage showing target_micro_steps=300 -> max_steps=37, scheduler.decay_steps=37, effective_train_examples=296, and unapplied_micro_steps=4.

I am applying status:ready / review:pending.