Repository navigation
feat(sandboxes): attach to a live process by session - #1147
Conversation
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>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 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".
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ 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>
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>

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_uuidnames the process's sandboxd session.AsyncSandboxClient.attach_process(sandbox_id, session_uuid, timeout=None)streams the process again overCommandSession/Connect, from any client.timeoutmirrorsopen_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.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_processandattach_processshare one stream setup (_live_process), which includes the pooled command connection.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
failed_precondition("The sandbox is paused"), which the SDK treats as fatal. Without output replay the handle fails before that withProcessOutputLostError. The caller mustdetach()that handle and attach again when the sandbox runs. A reconnect that waits for a paused sandbox is not in this PR.ProcessOutputLostErrorwhen 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
tests/test_live_process_attach.pycovers the exposedsession_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.tick 1totick 45, one per second, and exits with code 7.open_processstarts it and exposessession_uuid. The handle reads ticks 1 to 7.ProcessOutputLostError, anddetach()releases it.attach_processon the same sandbox gets the same pid, ticks 8 to 45 and exit code 7.restore_memory=True.attach_processwith the new sandbox id and the samesession_uuidgets the same pid, ticks 9 to 45 and exit code 7. Tick 8 is lost, since this sandboxd has no replay.🤖 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_processandAsyncSandboxProcess.detachso a long-running sandbox process can outlive its starting client.open_processnow exposessession_uuid;detachdrops the stream without sending signals (unlikeaclose), and another client can re-stream the same session via Connect from sequence 0 (with output replay when sandboxd supports it).open_processandattach_processshare a refactored_live_processpath for auth, pooled command connections, and reconnect logic (attach paths always use Connect). Attach handles calldetachon 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.