# Runs

A run is one task given to a mech. Each run gets a fresh sandbox that starts from the mech's latest
checkpoint.

## Submitting

`POST /v1/mechs/{id}/runs` with `{ "input": "..." }` and an `Idempotency-Key` header. The response is `202`
with the run. Optional `settings` override the mech's `instructions` and `reasoningEffort` for this run
only.

A mech runs one task at a time. Submitting while a run is active returns `409`. Reusing an idempotency key
with different input or settings also returns `409`; reusing it with the same request returns the original
run.

## Statuses

| Status       | Meaning                                                 |
| ------------ | ------------------------------------------------------- |
| `queued`     | Accepted; checking credits and preparing the sandbox.   |
| `running`    | The mech is working.                                    |
| `cancelling` | Cancellation was requested; the sandbox is stopping.    |
| `completed`  | Finished, and the new checkpoint is saved.              |
| `failed`     | Stopped with an error; the previous checkpoint is kept. |
| `cancelled`  | Stopped on request; the previous checkpoint is kept.    |

If the mech does not have enough credits, the run fails with an error that says so. Add credits and submit
again.

## Events

`GET /v1/mechs/{id}/runs/{runId}/events` streams server-sent events:

- `run.status` carries `{ "status": ... }`.
- `run.output` carries `{ "text": ... }`, the full output observed so far.

Each event has an `id`. To resume after a disconnect, send `Last-Event-ID`, or pass `?after=<id>`. Events
are replayed from that point. Disconnecting never cancels a run.

## Reading and cancelling

`GET /v1/mechs/{id}/runs/{runId}` returns the run's status, output, profile, resolved settings, and the
checkpoint it started from. `POST /v1/mechs/{id}/runs/{runId}/cancel` requests cancellation; repeating it is
safe.