Skip to content

feat(checkpoint): hold-pause a harness when the sandbox snapshot keeps its processes - #5411

Draft
pthombre wants to merge 2 commits into
pranav/envckpt-7-agentenv-providerfrom
pranav/envckpt-8-hold-pause
Draft

pthombre wants to merge 2 commits into
pranav/envckpt-7-agentenv-providerfrom
pranav/envckpt-8-hold-pause

Conversation

@pthombre

@pthombre pthombre commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

What changed and why

At a checkpoint, the process supervisor (#5268) freezes the harness with SIGSTOP and continues it with SIGCONT afterwards. That is needed when the snapshot copies only files, as on OpenSandbox. But a process in uninterruptible sleep cannot be stopped, so the pause is then not confirmed and the harness is killed and relaunched.

A VM memory snapshot (AgentENV, #5410) captures the whole sandbox at one instant, processes included, so the harness does not need to be frozen for a consistent copy. This PR adds a pause that holds the harness without signalling it, and records what a later restore needs to find the paused launch again.

Hold pause

What each acknowledgement records

Every pause and continue acknowledgement now carries:

  • mode: stop or hold.
  • identity: the supervisor's PID and process start time.

SandboxSession.checkpoint_state() records the held pause and the supervisor's identity. After a restore of a process-keeping snapshot, #5412 uses these to recognise the same launch.

Checkpointer record

The sandbox checkpointer (#5265) records whether the provider's snapshots keep processes (keeps_processes). Older records read as false.

How it works

sequenceDiagram
  participant G as Gym (prepare and resume)
  participant S as Process supervisor
  participant H as Harness (OpenCode)
  G->>S: pause N
  alt stop mode (OpenSandbox)
    S->>H: SIGSTOP
    S-->>G: ack with seq N, mode stop, identity
  else hold mode (AgentENV)
    Note over H: keeps running, model calls held by the relay (PR 5412)
    S-->>G: ack with seq N, mode hold, identity
  end
  Note over G: snapshot the sandbox
  G->>S: continue N
  S->>H: SIGCONT (stop mode only)
Loading

Where this sits in the stack

This stack checkpoints environment-server episodes whose agent harness runs in a sandbox the resources server lends. #5264 has merged, and the rest of the stack is rebased onto main after it. #5265 to #5331 add checkpoints for OpenCode and the SWE servers on OpenSandbox. #5410 to #5413 add AgentENV (E2B API, VM memory snapshots), where a restored sandbox still runs the harness's processes, so OpenCode continues in place instead of being relaunched. Each PR's diff shows only that PR's change.

  1. feat(checkpoint): protocol for harnesses that borrow a sandbox #5264: feat(checkpoint): protocol for harnesses that borrow a sandbox (merged)
  2. feat(sandbox): snapshot, fork and delete for OpenSandbox, with a checkpointer #5265: feat(sandbox): snapshot, fork and delete for OpenSandbox, with a checkpointer
  3. feat(swebench): checkpoint the task sandboxes of episode sessions #5266: feat(resources): sandbox owner base for resources servers
  4. feat(swebench): typed sessions on the owner base with capture-once verify #5267: feat(swebench): typed sessions on the owner base with capture-once verify
  5. feat(opencode): pause at checkpoints and resume after a crash #5268: feat(opencode): pause at checkpoints and resume after a crash
  6. test(checkpoint): end-to-end harness scenarios, SWE-bench recipe, docs #5269: test(checkpoint): end-to-end harness scenarios, SWE-bench recipe, docs
  7. feat(swe): repository-task servers on the sandbox owner base #5331: feat(swe): repository-task servers on the sandbox owner base
  8. feat(sandbox): AgentENV snapshots, lease and kill-at-timeout for the E2B provider #5410: feat(sandbox): AgentENV snapshots, lease and kill-at-timeout for the E2B provider
  9. feat(checkpoint): hold-pause a harness when the sandbox snapshot keeps its processes #5411: feat(checkpoint): hold-pause a harness when the sandbox snapshot keeps its processes (this PR)
  10. feat(agent-utils): resume a supervised harness in place after a restore that kept its processes #5412: feat(agent-utils): resume a supervised harness in place after a restore that kept its processes
  11. feat(opencode): resume OpenCode in place on sandboxes whose snapshots keep processes #5413: feat(opencode): resume OpenCode in place on sandboxes whose snapshots keep processes

Issue

No tracking issue exists. This is the checkpoint-side half of AgentENV in-place resume. #5412 and #5413 build on the pause mode and the recorded identity.

Validation

  • Unit tests for the hold pause (immediate acknowledgement, no signal, deadline credited), the new acknowledgement fields, checkpoint_state(), unchanged stop mode, and the keeps_processes record; existing suites pass; lint is clean.
  • Live tests against AgentENV: a held harness kept running through the snapshot, and the continue was acknowledged in the forked sandbox.
  • Rebased onto main after feat(checkpoint): protocol for harnesses that borrow a sandbox #5264 merged: the unit, server and process-level checkpoint suites fail only where main itself does, apart from intermittent failures in tests that pass when run alone or that fail the same way on main.
  • No training run yet on the stack as it is now. The results below are from RL training runs on AgentENV with the previous version of the stack, which set the clock back inside the sandbox where this version relies on the provider (feat(sandbox): AgentENV snapshots, lease and kill-at-timeout for the E2B provider #5410):
    • Checkpoint and resume at 8 and 16 nodes: checkpoints committed at scale, sessions resumed in place, no corrupted token history, and training continued.
    • Two 16-node runs, a checkpoint run and a restore from its checkpoint, committed every checkpoint with no sandbox loss; the restore resumed every held session in place, on images with or without Python.

Compatibility

  • Default unchanged. pause_mode defaults to stop, so OpenSandbox and every existing harness behave as before.
  • New acknowledgement fields are additive; readers ignore fields they do not know.
  • Checkpoint state gains the optional held pause and supervisor identity. Checkpointer records gain keeps_processes, which reads as false when absent.

🤖 Generated with Claude Code

@pthombre pthombre added feature New capabilities, enhancements, or enablement work area:env-infra Shared environment framework, lifecycle, registry, scaffolding, and validation complexity:medium Single-domain change with interacting parts or a moderate review surface labels Oct 31, 2026
@copy-pr-bot

copy-pr-bot Bot commented Oct 31, 2026

Copy link
Copy Markdown

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.

@pthombre

pthombre commented Nov 7, 2026

Copy link
Copy Markdown
Contributor Author

Being rebased onto current main, after #5264 and #5265 (already rebased). Until this branch is pushed, its diff still shows their old commits. Not ready for review yet.

@pthombre
pthombre force-pushed the pranav/envckpt-8-hold-pause branch 2 times, most recently from 33acd80 to 8ddbaa7 Compare November 12, 2026 20:35
pthombre and others added 2 commits November 15, 2026 05:55
…s its processes

A VM memory snapshot (AgentENV) captures the whole sandbox at one instant, processes included, so a checkpoint
does not need the harness frozen to get a consistent copy; freezing it there only adds the pause failures a
process in uninterruptible sleep causes. The supervisor gains `--pause-mode hold`: a pause is acknowledged at
once without signalling anything, the deadline stops counting until the continue as before, and the checkpoint
holds the harness's model calls instead. The default stays `stop` (SIGSTOP/SIGCONT), which a files-only snapshot
still needs.

Each acknowledgement now names the pause mode and the supervisor's identity (`PID.START`, the marker it gives the
processes it launches). `SandboxSession(pause_mode=...)` launches in that mode, and `checkpoint_state()` records
the pause the supervisor holds and its identity, so a restore of a process-keeping snapshot can find the launch
again. The sandbox checkpointer records whether the provider's snapshots keep processes (`keeps_processes`,
false for older records), and the docs say what a restore keeps is provider-dependent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Pranav Thombre <pthombre@nvidia.com>
…les, and record the pause a new supervisor holds

Found in a review of the hold pause.

- A server that declares `restore_policy = "before_agent_close"` no longer sends it on a provider whose snapshots
  keep the sandbox's processes: a fork of such a snapshot has the processes its grader needs, so the episode
  continues at every step. Until now only the documentation said so.
- `SandboxSession.checkpoint_state()` reports a held pause only while the launch runs. A launch that was stopped
  while paused kept reporting it, and a restore would have looked for a supervisor that is gone.
- A pause that reaches the sandbox after the launch command was sent, but before its supervisor started, is asked
  once more. The supervisor reads the request as it starts and holds the launch, and its acknowledgement names it;
  without the second request the checkpoint recorded a started launch and no supervisor holding it.
- The supervisor's header says that it does not watch the harness during a hold: one that exits is reaped after
  the continue. Its usage text lists the pause options.
- Docstrings and the two tutorial pages say what `confirmed` means in hold mode and that `reattach` takes the pause
  mode.
- Tests: the hold-mode session test ends its harness itself and no longer leaves it behind when it fails; the
  supervisor's hold test checks the child and a detached service too and no longer races the deadline; a harness
  that ends during a hold, a stop during a hold, a hold before the launch, the branches of `checkpoint_state()`,
  `reattach` with a held pause, the pause mode in the launch command, and both provider kinds for the restore
  policy.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: Pranav Thombre <pthombre@nvidia.com>
@pthombre
pthombre force-pushed the pranav/envckpt-8-hold-pause branch from 8ddbaa7 to 7c2b211 Compare November 16, 2026 21:44

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:env-infra Shared environment framework, lifecycle, registry, scaffolding, and validation complexity:medium Single-domain change with interacting parts or a moderate review surface feature New capabilities, enhancements, or enablement work

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant