Replay and Overrides

Replay creates a new execution from a previous one.

Use replay when you want to keep earlier durable work and rerun only a suffix of your workflow.

SDK replay

import kitaru

client = kitaru.KitaruClient()

replayed = client.executions.replay(
    "kr-a8f3c2",
    from_="write_draft",
    topic="New topic",
    overrides={
        "checkpoint.research": "Edited notes",
    },
)

print(replayed.exec_id)
print(replayed.original_exec_id)  # points to source execution

Flow-object replay

handle = content_pipeline.replay(
    exec_id="kr-a8f3c2",
    from_="write_draft",
    topic="New topic",
    overrides={"checkpoint.research": "Edited notes"},
)

result = handle.wait()

CLI replay

kitaru executions replay kr-a8f3c2 \
  --from write_draft \
  --args '{"topic":"New topic"}' \
  --overrides '{"checkpoint.research":"Edited notes"}'

Selector rules

from_ can target:

checkpoint name (for example write_draft)
checkpoint invocation ID
checkpoint call ID

If a selector is ambiguous, replay raises KitaruStateError.

Override keys

Replay override keys must start with checkpoint..

Examples:

checkpoint.research
checkpoint.fetch_data

Any other prefix raises KitaruUsageError.

Replay does not support overriding or pre-populating wait results. If a replayed execution reaches a wait() during normal execution, that wait behaves like any new wait and must be resolved through the normal wait input flow:

SDK: client.executions.input(exec_id, wait="name", value=...)
CLI: kitaru executions input <exec_id> --value ... (auto-detects single pending wait)
CLI interactive: kitaru executions input <exec_id> --interactive

Divergence

Replay can raise KitaruDivergenceError when the backend detects that durable call sequence compatibility is broken.

Also check replayed execution failure metadata:

latest = client.executions.get(replayed.exec_id)
if latest.failure:
    print(latest.failure.origin, latest.failure.message)

Example in this repository

uv sync --extra local
uv run examples/replay/replay_with_overrides.py
uv run pytest tests/test_phase16_replay_example.py

For the broader catalog, see Examples.