> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution, workers, and recovery

> Preserve original command receipts, distinguish confirmed exits from unknown outcomes, replay output safely, and supervise background workers.

Commands, execution receipts, supervised processes, and task results have separate lifetimes.
Retain original identities before dispatch and inspect evidence before repeating work that
may already have changed state.

## One bounded command

`POST /api/v1/sandbox/{id}/execute` accepts argv or a supported string command,
`working_dir`, environment, `stream`, and a **1,000–600,000 millisecond** timeout.
Use argv for literal arguments; strings deliberately invoke shell interpretation.

```json theme={null}
{
  "command": ["python3", "/workspace/check.py"],
  "working_dir": "/workspace",
  "timeout": 120000
}
```

Save the supported `Idempotency-Key`, exact body/path, sandbox, and returned `execution_id`.
Do not wrap SDK mutations in another generic retry loop. The candidate CLI removes those
outer retries while preserving original SDK request identity.

## Interpret the result

| Observation | Meaning and action |
| - | - |
| Confirmed exit zero | Process success; validate the requested task separately |
| Confirmed nonzero exit | Inspect output/exit; do not claim shell success |
| `system_error: exec_stream_lost`, `outcome: unknown` | Work may have run; inspect the original receipt and external effects |
| `record_pending: true` | Result retained but receipt-summary publication needs recovery; do not resubmit |
| 409 `execution_result_unconfirmed` | Result storage unconfirmed; retain `details.execution_id` and reserved key |
| Documented not-started 503 | Admission/start/recovery failure before execution, with its retry hint |
| Local timeout without definitive receipt | Remote outcome remains uncertain |

HTTP success is not command success: 200 can retain an unknown outcome. Output truncation
is separate from observed exit; a missing exit or malformed output cannot become success.

## Read the original receipt

| Route under `/api/v1` | Purpose |
| - | - |
| `GET /sandbox/{id}/executions` | Recent receipts |
| `GET /sandbox/{id}/executions/{executionId}` | Original status/outcome |
| `GET /sandbox/{id}/executions/{executionId}/stream` | SSE replay |
| `POST /sandbox/{id}/executions/{executionId}/cancel` | Request cancellation |

Preserve event IDs as opaque cursors after consuming complete events. A replay reset replaces
accumulated output with the retained snapshot. Incomplete frames do not advance the cursor.
SDK receipt waits/reconnection observe the original command rather than submit a new one.

A terminal receipt can be `outcome_unknown`. Local wait expiry/abort stops observation and
can leave the command running. Cancellation acknowledgement is not termination proof; inspect
the eventual receipt and relevant side effects. Agent/pod ownership fences prevent stale
handles from controlling another worker.

## Supervised processes

Use `/sandbox/{id}/processes` for background workers. Start/get/list, result, logs, binary
stdin, signals, and deletion/termination are separate operations. Restart policy is explicit.
Enable stdin at start if later input is required, and preserve its exact base64 bytes.

`GET /processes/{processId}/result` returns `outcome`, nullable `exit_code`/signal, `complete`,
output-capture state, timestamps, and bounded streams. Outcomes include pending, succeeded,
failed, cancelled, timed\_out, and unknown. `complete` verifies terminal process/log ends;
output can still be truncated and task quality remains separate.

Logs use returned `next_offset`; retain stream/process/sandbox identity and rotation flags.
The workbench validates binary output and bounded tails, preserving a stale prior observation
when refresh fails. It never turns observation into another worker launch.

[Prepared tasks](/stateset-sandbox/agent-tasks) add private parent journals and exact
command/workspace/process identity. Registry discovery does not reconstruct every private
control or result receipt.

Source: Node execution/process handlers, SDK receipt APIs, and `docs/EXECUTION_READINESS.md`,
checked at `67bc2370` on October 20, 2026. Continue with
[the quickstart](/stateset-sandbox/stateset-sandbox-quickstart-guide) or
[the workbench](/stateset-sandbox/workbench).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.