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

# Replay a supervisor

> Try a supervisor or a draft rules document on a past run in dry run to see what it would have sent, before it touches a live run.

<dl />

**Use this when** you are about to change rules or a supervisor's settings and want evidence first, or you want to know why a supervisor did (or did not) react in an incident.

**Prerequisites:** a saved supervisor, for example `ci-guard` from [Write a rules supervisor](https://yukta.infenia.com/guides/supervise/write-a-rules-supervisor.md), and the id of a finished run (`GET /api/workflow/{sessionId}/history`). Add `-H "X-API-Key: $YUKTA_API_KEY"` if your server has keys.

A replay rebuilds the **status events** of the past run from its execution log and feeds them to the supervisor in **dry run**: nothing is sent to any run. You get what it would have sent, and whether the supervisor's shell (`allowedCommands`, ownership) would have let it through.

![A replay feeds the stored status events of a finished run to the supervisor in dry run and lists the commands it would have sent, each marked allowed or not. Nothing is sent to any run.](https://yukta.infenia.com/images/diagrams/guide-replay-a-supervisor.light.svg)

The replay produces a list of decisions only: the live run is not touched.

## Steps

**1. Pick a run that has the situation**

Find a finished run in which a node failed, for example a run of the `sort` workflow from [Handle failures](https://yukta.infenia.com/guides/build/handle-failures.md) with `onError` set to `FAIL`:

```bash theme={"system"}
curl -s localhost:9858/api/workflow/failures/history
# EXEC=<the executionId of a run with a FAILURE node>
```

**2. Replay the stored supervisor**

```bash theme={"system"}
curl -s -X POST localhost:9858/api/supervisors/ci-guard/replay \
  -H 'Content-Type: application/json' -d "{\"executionId\":\"$EXEC\"}"
```

CLI: `yukta-cli supervisors replay ci-guard --execution $EXEC`. MCP: `replay_supervisor`.

The answer lists decisions:

```json theme={"system"}
{
  "status": 200,
  "message": "Replayed",
  "data": [
    { "command": "PauseWorkflowCommand", "executionId": "…", "nodeId": null,
      "cause": "event:…", "reason": "3 nodes failed within 60 seconds", "allowed": true }
  ]
}
```

`allowed` says whether the supervisor's capabilities would let the command through: a command outside `allowedCommands` shows `false`. An empty list means the supervisor would have done nothing.

**3. Replay a draft instead**

To try new settings without saving them, pass a draft in `settings` (for a `rules` supervisor, the rules document). The stored shared settings (`allowedCommands`, `initiative`) still apply.

```bash theme={"system"}
curl -s -X POST localhost:9858/api/supervisors/ci-guard/engine/rules/replay \
  -H 'Content-Type: application/json' \
  -d "{\"executionId\":\"$EXEC\",\"settings\":{\"schemaVersion\":1,\"rules\":[{\"id\":\"pause-on-failure\",\"when\":{\"event\":\"NodeStatusChanged\",\"status\":\"FAILURE\"},\"then\":{\"command\":\"PauseWorkflow\",\"reason\":\"a node failed\"}}]}}"
```

CLI: `yukta-cli supervisors rules replay ci-guard --execution $EXEC -f draft.json` (without `-f` it replays the stored rules). MCP: `replay_rules` with `rules`. `POST /api/supervisors/{id}/replay` takes the same `settings` for any engine that supports it.

**4. Change the draft until it does what you mean, then save it**

Adjust the rules and replay again, then save with `PUT /api/supervisors/ci-guard/engine/rules` (a new version) or roll back later with `yukta-cli supervisors rollback ci-guard --version N`.

## Verify it worked

The decisions list matches what you expect: the failing node produced a `PauseWorkflowCommand` with your reason, a run with no failures produced none, and the live run you replayed is unchanged (`GET /api/executions/$EXEC` shows the same status as before). Nothing appears in `GET /api/supervisors/decisions` for a replay, because nothing was sent.

## Variations

* **What a replay cannot see.** Only statuses are rebuilt: node outputs and log lines were not kept, and a replayed node event has an empty `module` and no `metadata`. A rule that depends on `module`, `metadata['code']` or a `LogLine` will not fire in a replay even if it would live.
* **Timers.** A timed rule (`every`) is given about two seconds of replay time. At most 100 decisions come back.
* **Input requests and commands.** Input events are not in the replay; test those rules with a live request in a test session ([Route input requests](https://yukta.infenia.com/guides/supervise/route-input-requests.md)).
* **Dry run on a live supervisor.** `"dryRun": true` on a supervisor records its commands as `dry-run` in the decision list without applying them; `yukta.supervisor.dry-run=true` does it for every supervisor. Use it to watch a new supervisor on real traffic.

## Related

* [Rule files reference](https://yukta.infenia.com/reference/supervisors/rule-files.md) for the rule fields to try.
* [Supervisor shell reference](https://yukta.infenia.com/reference/supervisors/shell.md).
* [Write a rules supervisor](https://yukta.infenia.com/guides/supervise/write-a-rules-supervisor.md).


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