[ananthsub]

What does this PR do?

Gives every partial-rollout checkpoint concept one name before the feature ships in a release, and moves the policy model's checkpoint settings into a nested checkpoint: block.

The checkpoint code grew across several PRs, and the same concept ended up with different names on different servers:

• What a server's code can save was declared three ways: checkpoint_mode on resources servers, checkpoint_sessions_supported: bool on agents, and checkpoint_boundaries: bool on environment servers.
• Whether a checkpoint waits for a running step was called StepMode, verify_mode, "verify mode" and "step mode" in different places.
• Restored state that no next attempt has used yet was restored_pending in code and "unclaimed" in the design.
• A cut model call that cannot continue its prefix was said to "restart", the word already used for a whole rollout that starts over from its input.
• The policy model's two settings sat flat on its config, as checkpoint_policy and checkpoint_generation_cuts.

Nothing here has been released, so every rename is a straight rename, with no aliases. NeMo RL is the main consumer and changes in step; the list is below.

One term per concept. The names follow the partial-rollout checkpoint design's terms. Where the design and the code used two names for one thing, this PR keeps one:

Concept	Name now	Earlier names
What a server's code can save	checkpoint_mode: restart_only, stateless, exported	checkpoint_sessions_supported, checkpoint_boundaries, ResourcesCheckpointMode
Whether a checkpoint waits for a running step	step type, wait or replay; StepType	StepMode, verify_mode, "verify mode", "step mode"
Restored state no next attempt has used yet	unclaimed; unclaimed(), status key unclaimed	restored_pending
A cut call with no usable cut	regenerated; cut_regenerate_reason	"restarts", cut_restart_reason
An agent answering a run it already finished	saved reply; answered_from_saved_reply()	replayed(), _completed_activation_reply

Declarations. Agents and environment servers now declare checkpoint_mode, exactly as resources servers do. An agent that implements the session hooks declares "exported"; an environment server whose run records boundaries declares "exported"; the default stays "restart_only". Agents and environment servers accept only restart_only and exported, and a misspelled value fails at startup, as it already does on resources servers.

Policy model config. A model server instance's checkpoint settings are now one block:

policy_model:
  responses_api_models:
    vllm_model:
      checkpoint:
        policy: true
        generation_cuts: true

ModelCheckpointConfig forbids unknown fields, so a misspelled setting fails at startup instead of being ignored.
The startup check that refuses a model server outside the checkpoint gate now names checkpoint.policy.

Wire names. The resources server's step type keeps the class variable checkpoint_verify, the status key verify and the x-ng-checkpoint-verify header. The environment server's status reply now reports unclaimed instead of restored_pending. The step type the environment server and Simple Agent record in their boundaries is now resources_verify_step_type, which changes their exported record schema.

Test servers. The checkpoint end-to-end suite's slow-verify resources server read its step type from an environment variable. It is now two servers with constant declarations, slow_verify_server (wait) and replay_verify_server (replay), because a step type is a property of the code.

Docs. The agent harness guide names checkpoint_mode = "exported". The Hermes agent README says that its checkpoints_enabled turns on Hermes' own checkpoints, which are unrelated to Gym's partial-rollout checkpoints.

Error codes. A checkpoint refusal reaches callers of /run, /seed_session and model calls as a plain {"error": {"code", "detail"}} body, so every checkpoint error code now carries the checkpoint_ prefix and says where it came from.
stale_checkpoint becomes checkpoint_stale, invalid_checkpoint_state becomes checkpoint_invalid_state, and every other code gains the prefix: checkpoint_invalid_phase, checkpoint_deadline_exceeded, checkpoint_stale_attempt, checkpoint_admission_closed, checkpoint_retire_incomplete, checkpoint_export_failed, checkpoint_restart_in_scope, checkpoint_rollout_id_required, checkpoint_invalid_rollout_id, checkpoint_unauthorized and checkpoint_activation_out_of_order.
checkpoint_conflict, checkpoint_error and checkpoint_coordinator_unavailable already had it.

Marking. A participant marks a retired attempt, and only the capture ledger and the complete-record store keep a fence, so the resources participant's fence_retired becomes mark_retired_sessions.

Unchanged by decision: the participant phases, mark_retired and RetiredAttempts (retire marks an attempt, and forget ends the mark), PrepareResult.continued, the legacy_run names for an agent's own /run, and rollout re-verification's ReverifyMode.

Issue

No issue. The names were settled while reviewing #4957, which adds a status field that NeMo RL reads; settling them first keeps that field and NeMo RL's setup check from shipping against names that would change.

NeMo RL changes

NVIDIA-NeMo/RL#4500 (head 8ddf203f30):

• nemo_rl/environments/nemo_gym.py: policy_overrides["checkpoint_policy"] = True becomes policy_overrides["checkpoint"] = {"policy": True}.
• tests/unit/environments/test_nemo_gym_utils.py: the expected vllm_model config becomes {"uses_reasoning_parser": False, "checkpoint": {"policy": True}}, and the lookup of ["checkpoint_policy"] reads ["checkpoint"]["policy"].
• tests/unit/environments/test_gym_checkpoint_adapter.py: restored_agent.restored_pending() becomes restored_agent.unclaimed().
• tests/unit/experience/test_failures.py: the refusal bodies' codes become checkpoint_admission_closed and checkpoint_stale_attempt.
  The code that recognizes a refusal compares against AdmissionClosedError.code, so it follows the new value without a change.

NVIDIA-NeMo/RL#4506 (head 039c525985):

• nemo_rl/environments/nemo_gym.py: policy_overrides["checkpoint_generation_cuts"] = True becomes policy_overrides["checkpoint"]["generation_cuts"] = True, merged into the same block as policy.
• tests/unit/environments/test_nemo_gym_utils.py: the assertions on model["checkpoint_policy"] and model["checkpoint_generation_cuts"] read model["checkpoint"]["policy"] and model["checkpoint"]["generation_cuts"].

Rollout collection (#3893), Gym's own controller, compares against AdmissionClosedError.code, so its code follows without a change.
Its collection test that expects a refusal with admission_closed expects checkpoint_admission_closed instead, and its docstrings say the new code.

Open PRs that rebase onto this

#3909 (rebuilt on this branch), #4957, #4792, the sandbox stack (#4220, #4221, #4222, #4274, #4576), and the drafts #3897, #3898, #4451 and #4778. Each needs only the renames above.

Validation

• Core unit tests: pytest -n 16 tests/unit_tests. Every checkpoint, environment server, model server and token-capture test passes. The failures that remain are in sandbox, reward-profile, benchmark-listing and dataset-orchestrator tests that need optional packages or services absent from the local environment; the sandbox, reward-profile and benchmark-listing ones fail the same way on main.
• Server tests, one directory at a time: responses_api_agents/simple_agent, responses_api_agents/tool_simulation_agent, environment_servers/single_agent_turn, resources_servers/blackjack.
• Checkpoint end-to-end suite with real server processes and the fake backend: NEMO_GYM_CHECKPOINT_E2E=1 pytest tests/e2e/checkpoint -k "not real_model".
• pre-commit run --files on the changed files.

Rollouts

N/A: the change renames declarations, config fields and internal names and moves two config fields into a block. No rollout, verifier or checkpoint behavior changes. The checkpoint end-to-end suite, which checkpoints, kills and restores real Gym processes, covers the renamed paths.

Compatibility

• Breaking for unreleased code only.
• Model servers, agents and environment servers use the new names. No released server or config uses the old ones, so nothing checks for them.
• Every checkpoint error code changes, so a caller that matches a literal code must use the checkpoint_ name; callers that compare against an error class's code follow automatically.
• Checkpoints written before this change cannot be restored after it, because the environment server's and Simple Agent's boundary records rename the step-type field. No released Gym writes checkpoints.

Checklist

• I have read the contributing guidelines.
• The change is focused; unrelated "drive-by" edits are tracked as separate issues/PRs.
• Tests added or updated and pass locally.
• Documentation added or updated.
• Pre-commit checks pass locally (pre-commit run --files on the changed files).
• New source files include the required Apache-2.0 SPDX header.
• All commits have DCO sign-off (git commit -s).

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-4997-839e617babff.docs.buildwithfern.com/nemo/gym

[svcnvidia-nemo-ci]

SHIP — LGTM — no reliability concerns.

Reviewed all 30 changed files and traced the affected checkpoint declaration, nested model-config, boundary serialization, restored-state cleanup, saved-reply, and worker-message paths. No material defects found. The intentional unreleased API and checkpoint-format breaks are documented.

Validation was source-only, including inspection of the relevant regression tests; tests were not executed in this read-only review.

Note: formal approval is not available for this request, so this review is posted as a comment only.

Review generated by codex. This was a full review. Request a full review with /review reset=true.