> This page is for version Main (default).
> For other versions, use one of these documentation indexes:
> - Main (default): https://docs.nvidia.com/nemo/gym/main/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo/gym/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo/gym/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo/gym/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo/gym/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo/gym/v0.3.0/llms.txt
> - 0.2.1: https://docs.nvidia.com/nemo/gym/v0.2.1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/gym/_mcp/server.

# nemo_gym.agent_utils.supervisor_client

Controller-side transport for the shared sandbox process supervisor.

Session ownership and cancellation live in sandbox\_session.py; output parsing stays with the adapter.
Unlike process\_supervisor.py, this module is not uploaded to the task sandbox.

Session control files (all paths are relative to session\_dir):

\===================== ==================== ===========================================
Filename              Writer               When
\===================== ==================== ===========================================
process\_supervisor.py Session              Uploaded before launch
launch.claim          Launch or stop shell Atomically claims launch or fences it
supervisor.pid        Launch shell         After claiming launch, before exec
stop.request          Stop shell           Before signalling the supervisor
cleanup.json          Supervisor or stop   After cleanup, or when stop fences launch
output.log            Launch shell         Captures supervisor and harness diagnostics
\===================== ==================== ===========================================

## Module Contents

### Functions

| Name                                                                                             | Description                                                                            |
| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| [`parse_cleanup_receipt`](#nemo_gym-agent_utils-supervisor_client-parse_cleanup_receipt)         | Require positive cleanup evidence, tolerating malformed optional diagnostics.          |
| [`remove_session_directory`](#nemo_gym-agent_utils-supervisor_client-remove_session_directory)   | Remove adapter-owned files after cleanup, keeping delayed launches fenced.             |
| [`stop_and_confirm_cleanup`](#nemo_gym-agent_utils-supervisor_client-stop_and_confirm_cleanup)   | Fence a pending launch or require explicit supervisor acknowledgement before teardown. |
| [`supervised_launch_command`](#nemo_gym-agent_utils-supervisor_client-supervised_launch_command) | Fence delayed launches and run a harness command under the shared supervisor.          |
| [`supervision_timeouts`](#nemo_gym-agent_utils-supervisor_client-supervision_timeouts)           | Return the per-cleanup-phase and provider execution deadlines.                         |

### Data

[`CLEANUP_RECEIPT_FILE`](#nemo_gym-agent_utils-supervisor_client-CLEANUP_RECEIPT_FILE)

[`LAUNCH_CLAIM_FILE`](#nemo_gym-agent_utils-supervisor_client-LAUNCH_CLAIM_FILE)

[`LOG`](#nemo_gym-agent_utils-supervisor_client-LOG)

[`OUTPUT_LOG_FILE`](#nemo_gym-agent_utils-supervisor_client-OUTPUT_LOG_FILE)

[`STOP_REQUEST_FILE`](#nemo_gym-agent_utils-supervisor_client-STOP_REQUEST_FILE)

[`SUPERVISOR_FILE`](#nemo_gym-agent_utils-supervisor_client-SUPERVISOR_FILE)

[`SUPERVISOR_PID_FILE`](#nemo_gym-agent_utils-supervisor_client-SUPERVISOR_PID_FILE)

[`_CLEANUP_RECEIPT`](#nemo_gym-agent_utils-supervisor_client-_CLEANUP_RECEIPT)

### API

```python
nemo_gym.agent_utils.supervisor_client.parse_cleanup_receipt(
    payload: object
) -> nemo_gym.agent_utils.process_supervisor.CleanupReceipt
```

Require positive cleanup evidence, tolerating malformed optional diagnostics.

```python
nemo_gym.agent_utils.supervisor_client.remove_session_directory(
    sandbox: nemo_gym.sandbox.AsyncSandbox,
    session_dir: str,
    workdir: str | None,
    timeout: float,
    harness: str
) -> None
```

async

Remove adapter-owned files after cleanup, keeping delayed launches fenced.

Retire the directory atomically before unlinking its claim. Otherwise a
delayed launch could win the claim while recursive deletion is in progress.
A failed removal leaves the retired path available for a close retry.

```python
nemo_gym.agent_utils.supervisor_client.stop_and_confirm_cleanup(
    sandbox: nemo_gym.sandbox.AsyncSandbox,
    session_dir: str,
    workdir: str | None,
    timeout: float,
    harness: str
) -> nemo_gym.agent_utils.process_supervisor.CleanupReceipt
```

async

Fence a pending launch or require explicit supervisor acknowledgement before teardown.

A stop that wins the launch claim writes the same receipt shape as the
supervisor, with no return code because no harness process ran.

```python
nemo_gym.agent_utils.supervisor_client.supervised_launch_command(
    session_dir: str,
    command: list[str],
    timeout: float,
    cleanup_timeout: float,
    python: str
) -> str
```

Fence delayed launches and run a harness command under the shared supervisor.

The adapter must install or select the interpreter explicitly. Check that it
can load the supervisor before claiming a launch: a failed bootstrap cannot
write a cleanup receipt. Supervisor and harness diagnostics share output.log.

```python
nemo_gym.agent_utils.supervisor_client.supervision_timeouts(
    timeout: float,
    close_timeout: float
) -> tuple[float, float]
```

Return the per-cleanup-phase and provider execution deadlines.

Divide the close budget across TERM grace, harness process reaping, and
descendant draining. The provider deadline reserves all three phases after
the harness timeout, plus 30 seconds for startup, polling, and receipt I/O.

```python
nemo_gym.agent_utils.supervisor_client.CLEANUP_RECEIPT_FILE = 'cleanup.json'
```

```python
nemo_gym.agent_utils.supervisor_client.LAUNCH_CLAIM_FILE = 'launch.claim'
```

```python
nemo_gym.agent_utils.supervisor_client.LOG = logging.getLogger(__name__)
```

```python
nemo_gym.agent_utils.supervisor_client.OUTPUT_LOG_FILE = 'output.log'
```

```python
nemo_gym.agent_utils.supervisor_client.STOP_REQUEST_FILE = 'stop.request'
```

```python
nemo_gym.agent_utils.supervisor_client.SUPERVISOR_FILE = 'process_supervisor.py'
```

```python
nemo_gym.agent_utils.supervisor_client.SUPERVISOR_PID_FILE = 'supervisor.pid'
```

```python
nemo_gym.agent_utils.supervisor_client._CLEANUP_RECEIPT = TypeAdapter(CleanupReceipt)
```