From 945e0dd80948c77ae6042feb271488b9a9652c81 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Mon, 9 Nov 2026 09:47:28 -0800 Subject: [PATCH 1/2] docs(local): a supervisor kills the run's process group and retries a sandbox not fully gone Co-Authored-By: Claude Opus 5.5 --- .env.example | 3 ++- src/agent_env/bundle/run.py | 4 +++- .../providers/sandbox_providers/local_docker/provider.py | 6 +++--- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/.env.example b/.env.example index 676974f84..f47970aa4 100644 --- a/.env.example +++ b/.env.example @@ -28,7 +28,8 @@ AGENT_ENV_ENVIRONMENT=dev # Where local sandboxes keep their work folders (default ~/.agent-env-sandboxes; on macOS, a path Docker Desktop # shares). A sandbox's folder is made before anything it runs, so a supervisor that gives a run a folder of its own -# can clean up after killing it: terminate each id local_sandbox_ids() lists, then remove its folder. +# can clean up after killing its process group: terminate each id local_sandbox_ids() lists, then remove its folder. +# A terminate that raises means the sandbox isn't fully gone: keep its folder and retry. # AGENT_ENV_LOCAL_SANDBOX_DIR=~/.agent-env-sandboxes # Secret store backend (what secret: references in config resolve through): diff --git a/src/agent_env/bundle/run.py b/src/agent_env/bundle/run.py index 7efbd9008..3f76d0863 100644 --- a/src/agent_env/bundle/run.py +++ b/src/agent_env/bundle/run.py @@ -241,7 +241,9 @@ def run_bundle( ``keep`` leaves them up instead, for the caller to use and then remove with ``BundleRun.teardown()``. Ctrl-C or SIGTERM cancels the runs and tears down every one, kept or not, then raises ``RunInterrupted`` with the result. A process killed outright tears down nothing: a supervisor that may have to kill it gives it an - ``AGENT_ENV_LOCAL_SANDBOX_DIR`` of its own, then terminates what ``local_sandbox_ids`` finds there. + ``AGENT_ENV_LOCAL_SANDBOX_DIR`` of its own and kills its whole process group, which on macOS is all that stops the + commands it ran on this machine. It then terminates each sandbox ``local_sandbox_ids`` finds there, keeping one + whose termination raises, which isn't fully gone, to retry. It runs its own event loop, and turns namespace routing on for the whole process while it runs, so it suits the CLI and scripts, not a service. From async code, call it in a thread; there it can't take over diff --git a/src/agent_env/providers/sandbox_providers/local_docker/provider.py b/src/agent_env/providers/sandbox_providers/local_docker/provider.py index ee4491c17..a5c5bd4fc 100644 --- a/src/agent_env/providers/sandbox_providers/local_docker/provider.py +++ b/src/agent_env/providers/sandbox_providers/local_docker/provider.py @@ -685,9 +685,9 @@ def _copy_into_container(source: Path, container: str, destination: str) -> None def local_sandbox_ids() -> list[str]: - """The ids of the local sandboxes with a work folder under the sandbox root. A folder is made before anything its - sandbox runs, so a supervisor that gave a run its own ``AGENT_ENV_LOCAL_SANDBOX_DIR`` cleans up after killing it by - terminating each id here (``LocalSandboxProvider().terminate_sandbox``) and removing its folder.""" + """The ids of the local sandboxes with a work folder under the sandbox root, made before anything its sandbox runs: + a supervisor that gave a run its own ``AGENT_ENV_LOCAL_SANDBOX_DIR`` terminates each after killing it, removing its + folder, and keeps one whose ``LocalSandboxProvider().terminate_sandbox`` raises, not fully gone, to retry.""" root = _local_sandbox_root_path() if not root.is_dir(): return [] From b53028a4f98129a6eec127da56d32930f53fc1ea Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Mon, 9 Nov 2026 09:51:38 -0800 Subject: [PATCH 2/2] docs(local): a supervisor starts the run in a new session so killing its group spares the supervisor Co-Authored-By: Claude Opus 5.5 --- .env.example | 5 +++-- src/agent_env/bundle/run.py | 9 +++++---- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.env.example b/.env.example index f47970aa4..fe607aa4d 100644 --- a/.env.example +++ b/.env.example @@ -27,8 +27,9 @@ AGENT_ENV_ENVIRONMENT=dev # AGENT_ENV_IMAGE_STORE=local # Where local sandboxes keep their work folders (default ~/.agent-env-sandboxes; on macOS, a path Docker Desktop -# shares). A sandbox's folder is made before anything it runs, so a supervisor that gives a run a folder of its own -# can clean up after killing its process group: terminate each id local_sandbox_ids() lists, then remove its folder. +# shares). A sandbox's folder is made before anything it runs, so a supervisor that gives a run a folder of its own, +# and starts it in a new session so that killing the run's process group spares the supervisor, can clean up after +# that kill: terminate each id local_sandbox_ids() lists, then remove its folder. # A terminate that raises means the sandbox isn't fully gone: keep its folder and retry. # AGENT_ENV_LOCAL_SANDBOX_DIR=~/.agent-env-sandboxes diff --git a/src/agent_env/bundle/run.py b/src/agent_env/bundle/run.py index 3f76d0863..016cb6550 100644 --- a/src/agent_env/bundle/run.py +++ b/src/agent_env/bundle/run.py @@ -240,10 +240,11 @@ def run_bundle( Each run's sandboxes are torn down as it ends, so the contexts returned record sandboxes that are gone. ``keep`` leaves them up instead, for the caller to use and then remove with ``BundleRun.teardown()``. Ctrl-C or SIGTERM cancels the runs and tears down every one, kept or not, then raises ``RunInterrupted`` - with the result. A process killed outright tears down nothing: a supervisor that may have to kill it gives it an - ``AGENT_ENV_LOCAL_SANDBOX_DIR`` of its own and kills its whole process group, which on macOS is all that stops the - commands it ran on this machine. It then terminates each sandbox ``local_sandbox_ids`` finds there, keeping one - whose termination raises, which isn't fully gone, to retry. + with the result. A process killed outright tears down nothing: a supervisor that may have to kill it starts it + with an ``AGENT_ENV_LOCAL_SANDBOX_DIR`` of its own in a new session (``start_new_session=True``), so killing the + run's whole process group spares the supervisor; on macOS that kill is all that stops the commands the run started + on this machine. It then terminates each sandbox ``local_sandbox_ids`` finds there, keeping one whose termination + raises, which isn't fully gone, to retry. It runs its own event loop, and turns namespace routing on for the whole process while it runs, so it suits the CLI and scripts, not a service. From async code, call it in a thread; there it can't take over