[ananthsub]

What does this PR do?

Stops two words from meaning two things across session routing and partial-rollout checkpoints. Stacked on #5083, which gave each session lifecycle concept one name; review the diff against that parent branch.

"Claim" meant two things. Session routing recorded which uvicorn worker holds a session's state, so that every request for the session is forwarded to that worker, and called that record a claim (SessionClaims, the claimant). The checkpoint stack uses claim for something else: the worker that receives a replacement attempt's /run takes the restored record for that attempt, and a restored record no attempt has taken yet is unclaimed. #4997 settled those checkpoint names, and NeMo RL reads unclaimed as a status key. The two senses meet in the restore code, where a worker installs restored sessions and then rewrites their routing claims. The module docstring of nemo_gym/_checkpoint/participant_workers.py used both senses a few lines apart.

Session routing already called that worker the owner, in the x-ng-session-owner header and in routes_sessions_to_owner. Routing now says owner everywhere, and claim keeps only its checkpoint meaning. The owner is the worker that currently holds the session, which is not always the worker that created it: a checkpoint restore installs a session on another worker and moves ownership there.

"Free" and "release" meant the same thing. #5083 made release the session code's word for freeing a session's state, but the checkpoint stack still said a retire frees a session, and its callback was on_session_freed. The checkpoint stack now says release too.

Concept	Name now	Earlier names
The worker that holds a session's state and serves its requests	owner; SessionOwners, "owns the session", "takes ownership", owner file	claim, claimant, "claims the session", claim file, routing claim
The record on disk that names a session's owner	owner file, in the session-owners directory	claim file, session-claims
A worker taking the restored record for its replacement attempt	claim, unclaimed (unchanged)
Freeing a session's or an episode's state	release; on_session_released, SessionReleased	free, on_session_freed, SessionFreed, "unfreed"
The fields of an MCP session token	claims (unchanged, the standard token sense)

flowchart TD
    request["Request for a session"] --> lookup["Look up the session's owner file"]
    lookup -->|"another worker owns it"| forward["Forward to the owner's private socket"]
    lookup -->|"this worker owns it, or nobody does"| serve["Serve it here"]
    serve -->|"a seed, or the handler used the session"| acquire["Take ownership: write the owner file"]
    serve -->|"its last record is gone"| release["Release ownership: remove the owner file"]
    restore["Checkpoint restore installs a session"] --> rewrite["Rewrite the owner file to name the installing worker"]
    run["Replacement attempt's /run"] --> claim["Claim the restored record from the coordinator"]
    retire["Checkpoint retire"] --> released["Release the attempt's state; ownership lasts until the forget"]

Loading

Error messages. A request refused because another worker took ownership of the same new ID now reads "This new session's ID is already owned by another worker. Retry it." (and "This session's ID ..." from the session middleware) instead of "... is already claimed". A forget refused while a retire is unfinished, and a /run told to wait for a rolled-back install, now say "releasing" instead of "freeing". Status codes and error codes do not change.

Episode session names in tests. A few session routing and resources server tests still called an episode seed "typed"; they now use the names #5083 settled.

Renamed names

For open PRs and downstream servers:

• SessionClaims → SessionOwners; its claimant() → owner() and claim() → acquire(). rewrite(), rewrite_all(), disown(), mine(), serving() and release() keep their names.
• SESSION_CLAIMS_DIR ("session-claims") → SESSION_OWNERS_DIR ("session-owners")
• SESSION_CLAIM_SCOPE_KEY ("nemo_gym.claim_session") → SESSION_ACQUIRE_SCOPE_KEY ("nemo_gym.acquire_session")
• app.state.nemo_gym_session_claims → app.state.nemo_gym_session_owners
• claimed_session_routing() → owned_session_routing(), which servers override to route their sessions
• SessionRoutingMiddleware(claims=...) → SessionRoutingMiddleware(owners=...)
• AgentSessionHolder.use_agent_session_claims() → use_agent_session_owners()
• SimpleResponsesAPIAgent._agent_session_claims → _agent_session_owners, and _release_agent_session_claim() → _release_agent_session_ownership()
• CheckpointParticipant.on_session_freed → on_session_released, typed SessionFreed → SessionReleased

Unchanged by decision: every checkpoint claim name (unclaimed(), claim_restored, ClaimRestored, claim_key, claim_cut, ClaimSettlingError, the checkpoint_restored_claim_settling error code), MCPTokenClaims, the harness supervisor's launch.claim file, and the directory claims gdpval keeps for its persisted deliverables.

Issue

No issue. A follow-up to #5083: lining its terms up against the checkpoint stack's found these two words used in two senses.

Validation

• Core unit tests: pytest -n 16 tests/unit_tests, in a venv synced with CI's extras.
• 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".
• Server tests for the servers that use the renamed routing and checkpoint names: simple_agent, example_session_state_mgmt, example_single_tool_call, single_agent_turn, and gdpval in its own venv built from its requirements.txt.
• pre-commit run --files on the changed files.

The only unit test that fails locally is the benchmark-listing test, which fails on this host on main too because its host name resolves to 127.0.1.1.

Rollouts

N/A: the change renames identifiers, a runtime directory, a scope key and messages. Routing, ownership and checkpoint behavior do not change, and the checkpoint end-to-end suite, which restores sessions across several workers, covers the renamed paths.

Compatibility

• Breaking for unreleased APIs only: none of these names has shipped in a release.
• A server that overrides claimed_session_routing() must rename it to owned_session_routing().
• The owner files move from session-claims to session-owners inside each server's runtime directory, which is created fresh for every server process, so nothing on disk needs migrating.
• Three refusal messages change wording; their status codes and error codes do not.

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-5087-e73d7711a0c3.docs.buildwithfern.com/nemo/gym

[svcnvidia-nemo-ci]

SHIP — LGTM — no reliability concerns.

Reviewed all 28 changed files and directly affected routing/checkpoint paths. The renamed contracts remain consistent across routing installation, server adapters, and checkpoint ownership hooks. No material defects identified in acquisition, forwarding, restore/rollback, or retire-until-forget behavior.

Static inspection only; tests were not executed.

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.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[yaoyu-33]

LGTM for the naming/terminology scope. Clarified current session ownership (not creator or cookie ownership) and brought in the parent fix without rewriting history. Validation: 393 targeted tests passed, 6 Linux-only skips; pre-commit --all-files and Fern check passed. Fern skipped the authenticated redirects check. Merge after #5083; CI still applies.