Skip to content

feat(sandboxes): attach to a live process by session - #1147

Merged
mikasenghaas merged 6 commits into
mainfrom
feat/attach-process
Nov 19, 2026
Merged

mikasenghaas merged 6 commits into
mainfrom
feat/attach-process

Conversation

@mikasenghaas

@mikasenghaas mikasenghaas commented Nov 3, 2026 •

Copy link
Copy Markdown
Member

Summary

A live process outlives its handle in sandboxd. It keeps running when the client that started it goes away, through a pause and resume of its sandbox, and in a sandbox created from a memory checkpoint of that sandbox. The SDK re-attached only inside the handle that started the process, so another client had no way back to it. aclose() was also the only way to release a handle, and it signals the process.

  • AsyncSandboxProcess.session_uuid names the process's sandboxd session.
  • AsyncSandboxClient.attach_process(sandbox_id, session_uuid, timeout=None) streams the process again over CommandSession/Connect, from any client. timeout mirrors open_process, because sandboxd applies the stream's deadline to the process. A failed or cancelled attach detaches from the process; it never stops the process it was recovering.
  • The attach asks for the output from sequence 0. A sandboxd with output replay sends the output it retains from the start of the process, and the handle applies the same completeness checks as a started one (ProcessOutputLostError). An older sandboxd sends only the output from the attach on.
  • AsyncSandboxProcess.detach() releases the stream and transport and sends no signal. The stream reports its own cancellation as a dropped stream, so a detaching handle does not re-attach it.
  • open_process and attach_process share one stream setup (_live_process), which includes the pooled command connection.
  • README: a "Reattach a Live Process" section.

Use case: verifiers continues a rollout in a sandbox forked from a memory checkpoint, from a new host process (PrimeIntellect-ai/verifiers#3141). The harness program is a live process of the box. With this change it can run in a session like every other command, and the new host attaches to it by session id.

Limits

  • A handle that started a process still fails when its sandbox is paused: sandboxd answers the reconnect with failed_precondition ("The sandbox is paused"), which the SDK treats as fatal. Without output replay the handle fails before that with ProcessOutputLostError. The caller must detach() that handle and attach again when the sandbox runs. A reconnect that waits for a paused sandbox is not in this PR.
  • An attach from sequence 0 fails with ProcessOutputLostError when sandboxd no longer retains the start of the output (4 MiB per command). An attach that takes only new output is not in this PR.

Verification

  • Unit: tests/test_live_process_attach.py covers the exposed session_uuid, attach over Connect from sequence 0, a re-attach after a drop, detach() sending no signal, a detach whose cancelled stream fails like a dropped one, and an attach cancelled while the pid arrives. I did not run the suite locally after the merge with main; CI runs it.
  • Live (prod, VM sandbox, sandboxd without output replay). A shell loop prints tick 1 to tick 45, one per second, and exits with code 7.
    1. open_process starts it and exposes session_uuid. The handle reads ticks 1 to 7.
    2. The sandbox is paused (memory checkpoint) and resumed. The first handle fails with ProcessOutputLostError, and detach() releases it.
    3. attach_process on the same sandbox gets the same pid, ticks 8 to 45 and exit code 7.
    4. A second sandbox is created from the checkpoint with restore_memory=True. attach_process with the new sandbox id and the same session_uuid gets the same pid, ticks 9 to 45 and exit code 7. Tick 8 is lost, since this sandboxd has no replay.
  • Live (verifiers checkpoint tests on this SDK): a rollout saved by one owner continues in a forked sandbox and finishes with reward 1.0, and a rollout survives four snapshots of its own sandbox while its harness program runs in a session.

🤖 Generated with Claude Code


Note

Medium Risk
Changes live process lifecycle, stream reconnect, and close-vs-detach behavior; mistakes could leak processes or stop them unintentionally, but scope is confined to the async command-session client.

Overview
Adds AsyncSandboxClient.attach_process and AsyncSandboxProcess.detach so a long-running sandbox process can outlive its starting client. open_process now exposes session_uuid; detach drops the stream without sending signals (unlike aclose), and another client can re-stream the same session via Connect from sequence 0 (with output replay when sandboxd supports it).

open_process and attach_process share a refactored _live_process path for auth, pooled command connections, and reconnect logic (attach paths always use Connect). Attach handles call detach on failed or cancelled setup so the remote process is not terminated.

README documents the reattach flow (including checkpointed sandboxes). New unit tests cover session exposure, attach/reconnect, detach semantics, and cancellation edge cases.

Reviewed by Cursor Bugbot for commit 8f796bd. Bugbot is set up for automated code reviews on this repo. Configure here.

A live process outlives its handle in sandboxd: it keeps running when
the client that started it goes away, and through a pause and resume
of its sandbox. The SDK could re-attach only within the handle that
started it, so another client had no way back to the process, and
`aclose()` was the only way to release a handle, which signals the
process.

- `AsyncSandboxProcess.session_uuid` names the process's session.
- `AsyncSandboxClient.attach_process(sandbox_id, session_uuid)`
  streams it again over `CommandSession/Connect`.
- `AsyncSandboxProcess.detach()` releases the stream and transport
  without a signal. A detaching handle does not re-attach the stream
  its own cancel ends.

Output emitted while no client is attached is not replayed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-03T00:14:09.188513Z 3eb8dfe PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3eb8dfeaec

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 3eb8dfe. Configure here.

`attach_process` built its handle through the cleanup `open_process`
needs: a cancelled or failed creation stopped the process, so an
attach that timed out while sandboxd re-announced the pid sent SIGTERM
to the very process it was recovering. An attached handle now detaches
instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mikasenghaas and others added 3 commits November 13, 2026 00:42
Main added output replay and pooled streams to live processes. The
attach now asks for the output sandboxd retains from the start of the
process, so a handle attached to a replay-capable sandboxd gets the
same completeness check as the one that started the process. An older
sandboxd sends only the output from the attach on.

Co-Authored-By: Claude <noreply@anthropic.com>
A handle that reconnects accepts only a sandboxd that announces
output replay, so the fake Connect stream now announces it and
numbers its output.

Co-Authored-By: Claude <noreply@anthropic.com>
@mikasenghaas
mikasenghaas merged commit 76041ab into main Nov 19, 2026
33 checks passed
@mikasenghaas
mikasenghaas deleted the feat/attach-process branch November 19, 2026 01:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants