fix(sim): a single-rollout run_policy says how many frames sit in the open episode and that it closed none

[cagataycali]

Through the agent tool, start_recording -> run_policy -> run_policy -> stop_recording saves ONE 20-frame episode where the caller meant two. run_policy closes no episode; frames buffer into the open one until save_episode, reset or stop_recording. The merge was documented in the docstring and in a logger.info the agent never sees, and the result text said only "Policy complete ... 10 steps".

Measured on Thor (MuJoCo so101, mock policy, 10 steps/rollout @ 10 Hz), same probe run in a git worktree at upstream/main and on this branch:

	rollout 1 text	rollout 2 text	episode_open_frames	episode_merged_prior_frames
before	Policy complete ... 10 steps	identical	absent	absent
after	+10 frames buffered in the open episode (10 unsaved)	+10 frames APPENDED to the open episode, which already held 10 from an earlier rollout - now 20 unsaved frames in ONE episode	20	10

Recorder truth in both trees: 10 open frames after rollout 1, 20 after rollout 2, 0 episodes saved. Behaviour is unchanged - only what the caller is told.

The remedies have to be ones an agent can dial

verb	in _PUBLISHED_ACTIONS?	named by the new line as
reset	yes	the boundary between rollouts
n_episodes=N	yes (_PUBLISHED_PARAMS)	N distinct episodes in ONE call
save_episode	no	explicitly "From Python"
verify_dataset_episodes	no	not named

save_episode and verify_dataset_episodes are absent from the published enum ("deliberately not published in tool_spec"), so advice naming them as the remedy sends an agent into a refusal. start_recording's advice now names the boundary instead of the false "run_policy (one call per episode)" - a call is not an episode.

Correction to the original report

The finding said the advice named save_episode. It does not - main's start_recording text names it zero times (grep -c on the success literal). The save_episode dead-end is reached from run_policy's docstring and the logger.info, neither of which an agent sees; the advice's own defect is simply that "one call per episode" is false. The line this PR adds is therefore the first agent-visible mention of save_episode, and it labels it Python-only.

An unpinned change, now pinned

The recording.py advice edit was shipped ungraded: reverting it to main's wording left all 5 original cells green. Added a 6th cell that reads the success text out of the source with ast - the shape test_recording_advice_names_every_route_that_captures already uses, so no dataset and no lerobot are needed.

6 cells, 6/6 mutants caught (pre-fix control: 4 F / 1 P - the survivor is the not-recording cell, trivially true when no line exists):

mutant	result
revert recording.py advice wording	1 F (survived before cell 6)
open_before = 0 (never says APPENDED)	1 F
_open_episode_frames returns 0	3 F
_append_text no-op	3 F
drop the "From Python, save_episode" clause	1 F
read open_before after the rollout (ordering)	3 F

Gate

• tests/simulation + tests/simulation/mujoco -k "episode or record or run_policy or contract or advice": 2758 P / 140 F vs 2752 P / 140 F on a clean upstream/main worktree. Two-way comm on the FAILED-id sets is empty both ways - delta is exactly my 6 cells. All 140 are pre-existing lerobot drift (No module named 'lerobot.utils.feature_utils', lerobot 0.5.1 on this node); clean main fails identically, and no failing id names anything this PR touches.
• ruff check + ruff format --check strands_robots tests tests_integ: clean, 2133 files.
• mypy strands_robots tests tests_integ: 28 errors in 12 files = the clean-main baseline; 0 in the three files touched.
• check_changelog_fragment.py exit 0, assemble_changelog.py --check OK.
• check_merge_base_overlap.py names fix(simulation/isaac): Isaac Sim backend #3343, fix(hardware_robot): the approval prompt says how long the arm may move, and whether the words matter #3766, fix(sim): evaluate_benchmark names a benchmark written for another robot first, by id, with the robot's name #3795 on simulation/base.py - all different changes (Isaac backend, approval prompt, benchmark mismatch); none touch the single-rollout recorder path, so this is merge-order only.

LOC delta +248 / -2, of which 181 are the test file and 8 the fragment; 55 lines of product (a check, a describer and a text-append helper).

Closes #600

[yinsong1986]

Summary

When a single-rollout run_policy runs during a dataset recording, the result now tells the caller how many frames sit in the open (unsaved) episode, says APPENDED and names the prior count when an earlier rollout already left frames there, and points at the two boundaries an agent can actually reach (reset between rollouts, n_episodes=N in one call) while labelling save_episode as Python-only. Two new additive JSON fields (episode_open_frames, episode_merged_prior_frames) carry the same signal machine-readably, and start_recording's advice drops the false "one call per episode" promise. Recorder behaviour is unchanged - only what the caller is told. The implementation is defensive where it needs to be: _open_episode_frames() re-checks _is_recording() and reads episode_frame_count via getattr(..., 0), so the base _active_recorder() -> None path and backends whose recorders lack the counter degrade to a zero count instead of crashing; the new fields and text line are gated on recording, so non-recording callers see byte-identical results.

What's good

• The remedies named in the new text are cross-checked against _PUBLISHED_ACTIONS / _PUBLISHED_PARAMS in the tests, so the advice can't drift into naming a verb the tool refuses.
• The previously-ungraded recording.py advice edit is now pinned by an ast-based source-reading test, matching the existing test_recording_advice_names_every_route_that_captures pattern (no dataset or lerobot needed).
• All new user-facing strings are plain ASCII, tests use monkeypatch.setattr, and the changelog fragment ships in the same PR - consistent with AGENTS.md conventions.
• Mutation-tested (6/6 mutants caught) with a clean two-way comm against the main-worktree failure set.

[yinsong1986]

Summary

When a single-rollout run_policy (n_episodes=1) executes during a dataset recording, the result now carries a Recorder: text line and two additive JSON fields (episode_open_frames, episode_merged_prior_frames) telling the caller how many frames sit in the open unsaved episode, flagging APPENDED when a prior rollout already left frames there, and naming only remedies the agent can actually invoke (reset between rollouts, n_episodes=N in one call) while labelling save_episode as Python-only. start_recording's advice drops the false "one call per episode" claim. Recorder behaviour is unchanged - only what the caller is told - and the new fields are additive to the result payload, so nothing here is a one-way door.

What's good

• All 6 new tests pass on the head SHA; the AST-based advice test pins the recording.py wording change that was previously ungraded, and the _PUBLISHED_ACTIONS/_PUBLISHED_PARAMS cross-checks keep the advice honest against the actual tool spec.
• _open_episode_frames degrades safely (getattr(..., 0) on a None base-class recorder) and _append_text handles a missing/empty content list, so the non-recording and error paths cannot crash.
• Product strings are plain ASCII, no host paths in the test file, changelog fragment included - AGENTS.md hygiene throughout.
• Scope discipline: 55 product lines, the rest is the pinning test and the fragment; the mutant table in the description shows every line is graded.