[yaoyu-33]

What changed

This PR tightens the resources sessions contract: the rules every stateful resources server must follow so single_agent_turn can drive it. It covers four foundational gaps in the environment server migration.

1. Closed-session records are bounded. ResourcesSessionFence in nemo_gym/base_resources_server.py gives each resources_session_id its own lock and remembers a closed session for the server's session_close_retry_window_seconds (300 s by default) instead of until the process exits. The records live in main's ClosedResourcesSessionRecords (fix(server): route a session's requests to the worker that holds it #3905), so with several workers a record never outlives the session's routing claim, and a retried close keeps the first record. Each server used to keep its own closed set, which grows by one entry per episode.
2. A close releases state even without the cookie. That case happens when the seed's reply is lost. The close must find the state by resources_session_id.
3. A refusal that no retry can fix is final. A seed or close used to raise a plain ValueError, which becomes a 500, and single_agent_turn dispatches the whole episode again. Now:
   • ResourcesSeedRejectedError (422) covers input that fails validation, such as task_data or a TaskId that does not match the task row;
   • ResourcesSessionConflictError (409) covers an ID already bound to another episode or task, a close that names another episode, and a seed for a closed session.
4. A lost session is masked, not scored 0.
   • /verify for a session the server no longer holds returns a masked sample built by lost_session_verification: reward 0, mask_sample=True, failure_kind session_lost (or session_expired). Before, servers returned an unmasked 0, which reads as a policy that solved nothing, or raised an error.
   • A tool call for such a session raises ResourcesSessionLostError (404) with a failure_kind, instead of an ordinary tool observation. What a harness does with it varies: simple_agent shows the body to the model and keeps going, Stirrup fails the run so the episode is dispatched again, and an MCP client reports a tool error. The masked verify is what keeps the episode out of the score.
   • Each masked verify logs a warning, so a wiring fault (for example a session cookie that never reaches /verify) does not show up only in coverage metrics.

check_resources_session_contract enforces the new rules, and every server that already ran it on main moves onto them in this PR, so none of their tests break:

• example_single_tool_call (the reference server);
• gdpval;
• partner_if mock tools (in-process and sandboxed): closed records retain the episode identity, so a close naming another episode or attempt returns 409 after the session is gone. Retried closes keep the first record and expiry; retirement of an unknown session keeps an ownerless fence;
• nemo_user_sim. It also gets an ID-to-state map, because the stricter check showed that a second episode could bind the same resources_session_id and that a cookie-less close missed its seed.

swebench_pro and interactive_browser move onto the contract in the stacked #4692.

Fixes found in review, also in this PR:

• GDPVal multistage: a masked lost-session row carries no failure class, so the orchestrator counted it as a judged success: a final stage with half its tasks judged reported complete with a headline ELO. tag_results now records it as the terminal verification failure the old 409 produced, and aggregate_metrics does not count it as an observed stage row.
• GDPVal seed cookie: the session cookie was bound before the 409/422 checks, so a refused seed's reply handed the caller the live session's cookie. It is now bound only after the checks pass.
• nemo_user_sim: a close of a closed session that names another episode gets 409, and a seed dropped after session_ttl_seconds verifies as session_expired instead of session_lost.

The contract

Where each rule applies in an episode

Teal steps are the resources sessions API. The notes show what this PR adds at each step.

sequenceDiagram
    autonumber
    participant A as Agent server
    participant E as Environment server (single_agent_turn)
    participant R as Resources server
    rect rgba(14,116,105,0.12)
    E->>R: POST /seed_session {resources_session_id, episode_id, task_id, task_data}
    R-->>E: 200 + session cookie (+ MCP tools, sandbox_access)
    Note over R,E: or 422 bad input / 409 conflict or closed: final, no retry
    end
    E->>A: POST /v1/agent_sessions (tool grants carry the cookie)
    E->>A: POST /v1/responses
    A->>R: tool calls (with cookie)
    Note over A,R: session gone: 404 failure_kind=session_lost
    E->>A: POST /v1/agent_sessions/close
    E->>R: POST /verify (with cookie)
    Note over E,R: session gone: 200, reward 0, mask_sample=true, failure_kind=session_lost
    rect rgba(14,116,105,0.12)
    E->>R: POST /close_session {resources_session_id, episode_id}
    Note over R: release by ID (cookie optional), fence the ID for session_close_retry_window_seconds
    end

Loading

The lost-seed-reply path

single_agent_turn registers the resources close before it sends the seed, so a seed whose reply is lost is still closed. But the environment server never received the cookie, so that close carries an empty cookie jar.

sequenceDiagram
    participant E as Environment server
    participant R as Resources server
    Note over E: register close(resources_session_id) first
    E->>R: POST /seed_session {resources_session_id: "s1"}
    Note over R: starts sandbox, sets cookie
    R--xE: reply lost (timeout, disconnect)
    E->>R: POST /close_session {resources_session_id: "s1"} with no cookie
    Note over R: find s1's state by ID, release it, fence s1
    E->>R: (late retry) POST /seed_session {resources_session_id: "s1"}
    R-->>E: 409 already closed (not retried)

Loading

How a resources server answers

The dividing line is whether a retry can change the result. single_agent_turn retries 5xx, 408, 425 and 429 by dispatching the episode again, and treats every other 4xx as final.

flowchart TD
    Seed["/seed_session"] --> V{"input valid?"}
    V -->|no: task_data, TaskId| R422["422 ResourcesSeedRejectedError<br/>final"]
    V -->|yes| C{"ID bound to another episode,<br/>or already closed?"}
    C -->|yes| R409["409 ResourcesSessionConflictError<br/>final"]
    C -->|no| P{"provider or dependency failed?"}
    P -->|yes| R5xx["5xx<br/>episode retried"]
    P -->|no| OK["200"]
    Tool["tool call"] --> G1{"session held?"}
    G1 -->|no| R404["404 ResourcesSessionLostError<br/>failure_kind=session_lost"]
    Verify["/verify"] --> G2{"session held?"}
    G2 -->|no| Masked["200 lost_session_verification<br/>reward 0, mask_sample=true"]
    G2 -->|yes| Score["score the episode"]

Loading

The rules

Call	Rule	Status
/seed_session	The same resources_session_id with the same episode and task returns the existing session (idempotent).	unchanged
/seed_session	Input that fails validation is refused with 422 (ResourcesSeedRejectedError).	new
/seed_session	An ID bound to another episode or task, or a session closed within the retention window, is refused with 409 (ResourcesSessionConflictError; ResourcesSessionFence.raise_if_closed raises it).	new (was any 4xx, in practice 500)
/seed_session	A failure a retry may fix, such as an unavailable sandbox provider, stays a 5xx.	unchanged
tool call	A call for a session the server no longer holds gets 404 with failure_kind (ResourcesSessionLostError).	new
/verify	A verify for a session the server no longer holds returns a masked sample (lost_session_verification), never a plain 0 and never an error.	new
/close_session	Succeeds when the session is already closed or was never seeded, and fences the ID either way. A close that names another episode gets 409.	409 is new
/close_session	Releases the session's state by resources_session_id, even with no cookie.	new
/close_session	If releasing fails, raises instead of fencing, so the caller can retry.	unchanged
retention	A closed record lasts the server's session_close_retry_window_seconds (300 s by default, the same setting agent sessions use), so callers must finish seed retries within that window. A retried close keeps the first close's record and expiry.	new (was "until shutdown")

A server whose score does not depend on per-rollout state, such as example_single_tool_call, needs no lost-session handling at verify.

Using the helpers

_fence: ResourcesSessionFence = PrivateAttr(default_factory=ResourcesSessionFence)

async def seed_session(self, body):
    async with self._fence.locked(body.resources_session_id):
        self._fence.raise_if_closed(body.resources_session_id)  # 409
        try:
            task = MyTask.model_validate(body.task_data)
        except ValidationError as error:
            raise ResourcesSeedRejectedError(f"task_data is not a task: {error}") from error  # 422
        ...  # create or reuse state keyed by resources_session_id; 409 on an episode mismatch

async def close_resources_session(self, body):
    async with self._fence.locked(body.resources_session_id):
        ...  # release state by resources_session_id; raise on failure
        self._fence.mark_closed(body.resources_session_id, body.episode_id)

async def verify(self, request, body):
    if (state := self._find(request)) is None:
        return BaseVerifyResponse(**body.model_dump(), **lost_session_verification("sandbox gone"))
    ...

Checking a server

check_resources_session_contract(
    app,
    seed,
    keeps_state=True,
    holds_state=lambda resources_session_id: resources_session_id in server._sessions,  # close released it
    verify_body=verify_request_json,  # verify after close is a masked lost session
)

With keeps_state, the check now also requires 409 for a seed that binds the open ID to another episode, for a close of the closed session that names another episode, and for every late seed.

TODO: sessions that are never closed (not in this PR)

When the environment server dies before its close, the session stays open. Nothing in the shared code expires it, and provider TTLs don't cover every case: apptainer ignores ttl_s. The agreed rule, to implement in ResourcesSessionFence:

• each open session gets a fixed lifetime from its seed: the sandbox ttl_s when set, otherwise 24 hours, configurable per server;
• the lifetime is checked on the next request, and open sandboxes are stopped at shutdown;
• an expired session is released, fenced like a close, and verifies as a masked session_expired sample.

Only resources sessions are in scope; agent sessions have the same gap and are tracked separately. The TODO in the ResourcesSessionFence docstring records this.

Relation to other PRs

• fix(server): route a session's requests to the worker that holds it #3905 (merged into main): routes each session's requests to the worker that holds it and adds ClosedResourcesSessionRecords with session_close_retry_window_seconds. ResourcesSessionFence keeps its per-session lock and stores closed records there. On a served resources server, a typed seed's cookie carries resources_session_id, and a cookie-less close is given that ID too; releasing by body.resources_session_id is still required for apps without session routing, such as tests.

• fix(resources): move swebench_pro and interactive_browser onto the session contract #4692 (stacked on this PR) moves swebench_pro and interactive_browser onto these rules.

• fix(agent): refuse unsupported agent session seeds with a final 422 #4680 is the agent side: AgentSeedRejectedError (422) for agent seeds. It also makes single_agent_turn put the refusing server's reason into failure_reason for every stage, so the 422 and 409 reasons from this PR reach the episode failure.

• feat(swe): serve typed resources sessions from SWE-Gym and R2E-Gym #4302: its SandboxSessionResourcesServer already keys sandboxes by resources_session_id and bounds its fence with its own 3600 s retention. It can replace _closed_task_sessions with ResourcesSessionFence, which keeps the record for session_close_retry_window_seconds, and use raise_if_closed (409) instead of its ValueError (500). Its open-session expiry is the sandbox-specific version of the TODO above.

Linked issues

• Bound closed-session records with one shared helper
• Release resources state when the seed response is lost

Follow-ups (not in this PR)

• The TODO above.
• openenv returns an unmasked 0 at verify when its session is gone. It is still on the legacy /run path and will get the rule when it migrates (feat(openenv): serve the typed resources sessions API #5483).
• Servers that only serve legacy /run seeds (deepswe, deepswe_external1, job_bench, workspace_bench, toolsandbox) get the refusal rules when they migrate to typed sessions.
• terminal_bench_2_1 and example_session_state_mgmt/nooa_app.py serve typed sessions but keep their own closed records, and terminal_bench_2_1 answers a verify for a lost session with 409 instead of a masked sample. Both should move onto ResourcesSessionFence and lost_session_verification.
• A close cancelled while it waits for the fence lock never fences the ID, so a slow seed's state can outlive it. Each server's own lock had the same gap before this PR; the fix belongs in ResourcesSessionFence (record the close before taking the lock, as terminal_bench_2_1 does).
• The resources checkpoint participant ends a session by the close request's cookie, so with checkpointing on, a cookie-less close leaves the session tracked. This predates the PR.

Validation

• Partner IF follow-up at 7ebecb5f759d20c5b00d0413fe525e9a411c078c: pytest resources_servers/partner_if/tests tests/unit_tests/test_base_resources_server.py tests/unit_tests/test_resources_sessions.py --import-mode=importlib -q -o addopts= -o log_cli=false --tb=short: 514 passed. Five additional lifecycle controls passed (failed-stop retry, wrong attempt, first-close expiry, known/unknown retirement). The three added regression cases fail against the original mock_tools_app.py. pre-commit run --all-files passed with Python 3.13.14; the private guardword catalog was unavailable, so that hook skipped its private scan.

• pytest tests/unit_tests/test_base_resources_server.py tests/unit_tests/test_session_contract_repo.py tests/unit_tests/test_resources_sessions.py tests/unit_tests/test_session_routing.py: 120 passed (after merging main). New tests:

  • closed records expire after the window and stay bounded over 1,000 closes; a retried close keeps the first close's episode and expiry;

  • the lock serializes one session and is dropped when unused, including for a cancelled waiter;

  • the refusal errors are 422 and 409 and still ValueErrors; ResourcesSessionLostError is 404 and names its failure_kind; lost_session_verification builds a valid masked response;

  • the contract check fails for a server that:

    • releases only by cookie (close left state for ...-lost-seed-reply);
    • answers a conflicting seed with 500;
    • scores a lost session 0 without masking.

    It passes for one that follows every rule. It also fails for a server that refuses a late seed with 500, or accepts a close of a closed session that names another episode.

  • one session's lock does not block another; clear() forgets closed records;

  • 422 and 404 refusals reach the wire through the SimpleServer middleware;

  • a masked sample built with the documented merge pattern survives an extra="allow" request carrying reward, logs a warning, and is kept for coverage and dropped from quality by select_measured.

• pytest resources_servers/example_single_tool_call/tests: 6 passed.

• pytest resources_servers/nullable_tool_args/tests: 4 passed (stateless caller of the check).

• pytest resources_servers/gdpval/tests in a venv built from its requirements.txt: 865 passed, 1 skipped. Includes the contract check with holds_state and verify_body; tests that pinned 400 or ValueError now assert 404, 409 or 422, and a verify with no session and no deliverables is a masked session_lost sample instead of a 409. New tests: a lost-session row is a terminal verification failure in the multistage orchestrator and does not complete the final stage; a gone session with an explicit deliverables_dir is still judged (not masked); task_data that is not a task gets 422; a refused seed does not hand out the live session's cookie.

• pytest resources_servers/nemo_user_sim/tests in a venv with nemo-usersim installed: 38 passed. Includes the contract check with holds_state and verify_body; a closed or unknown session now verifies as a masked session_lost sample and an expired one as session_expired, instead of a 404; a close finds the session by ID before the cookie.

• pytest tests/unit_tests -n 8: 8623 passed, 36 failed, 2 collection errors. All of the failures are in files this PR does not touch (opensandbox compose/cleanup/snapshots, the super35 batch launcher, CI environment, exporters, reward profile, telemetry). The same files fail the same way on unmodified origin/main in this local environment.

• pre-commit run --files <changed files>: passed.

Rollout evidence

Partner IF follow-up at 7ebecb5f759d20c5b00d0413fe525e9a411c078c: two real SingleAgentTurn → simple_agent → NIM nvidia/nemotron-3-ultra-550b-a55b episodes, one in-process and one in a real Docker sandbox, on the shipped greeting task. Each made three model calls, executed lookup and append, produced HELLO, and received unmasked reward 1 from the stock fixed-rule verifier. Both modes returned 200 for repeated same-episode close and 409 for a different episode or attempt. A second real seed in each mode had its reply replaced with 504 by a test wrapper: the environment closed it without a cookie, left no episode, and late seed returned 409. The Docker containers were removed. This is a bounded lifecycle smoke, not benchmark qualification.

The original three server smoke rollouts below have not been run yet; their results remain to be added before merge.

• example_single_tool_call under single_agent_turn with simple_agent: episodes verify and closes return 200.
• gdpval under single_agent_turn: episodes verify. A verify after a restart is masked session_lost, is not judged, and leaves the stage degraded rather than complete.
• nemo_user_sim under its environment server: closes return 200 and a healthy run has no masked samples.

Compatibility

• Status codes change for the servers in this PR. A conflicting or late seed and a mismatched close return 409, and bad task_data returns 422, where they used to return 500. A 500 was retried; these are now final.
• Lost sessions change for gdpval and nemo_user_sim. A verify for a lost session is a masked sample, so it counts toward coverage but not quality metrics. gdpval used to return a 409, and nemo_user_sim a 404, which produced no sample. A tool call for a lost gdpval session returns 404 instead of 400.
• The refusal errors are still ValueErrors, so direct callers that catch ValueError keep working.
• A refused gdpval seed no longer sets the session cookie. Before, a caller refused with 409 could act on another episode's live session.
• nemo_user_sim state: closed_resources_session_ids now holds (EpisodeId, expires_at), and an expired seed verifies as session_expired.
• Logging: each masked lost-session verify logs a warning.
• check_resources_session_contract is stricter: 409 for conflicting and late seeds where it accepted any 4xx, and 409 for a close of a closed session that names another episode. holds_state and verify_body are optional keyword arguments. Every caller in the repo passes.

🤖 Generated with Claude Code

[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]

/ok to test 6a1ac48

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-4679-7ebecb5f759d.docs.buildwithfern.com/nemo/gym

[yaoyu-33]

/ok to test ff3ecc4

[github-actions]

🔄 Merge queue validation started! You can track the progress here: https://github.com/NVIDIA-NeMo/Gym/actions/runs/40110947808