Skip to main content
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, 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.

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 with onError set to FAIL:
2

Replay the stored supervisor

CLI: yukta-cli supervisors replay ci-guard --execution $EXEC. MCP: replay_supervisor.The answer lists decisions:
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.
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).
  • 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.