Why replay needs the checkpoint

Replay is not a retry button on the whole graph. It is a request to run one step again against the payload that step originally received.

That payload is not in your prompt file. It is the output of the steps before it, plus whatever memory and tool results were in scope. If the host did not execute the run, that record does not exist. A framework can model the loop. It cannot replay what it never stored.

This is why replay sits on the host. An observability tool can show the failure. It never ran the graph, so it has no checkpoint to replay from. The rest of Linea — workers, memory, a boxed code node — exists so that this record is there when you need it.

What the checkpoint holds

A checkpoint is the exact input a node saw, written when the host ran it. Replay loads that record and calls the node again. Nothing upstream has to move.

const checkpoint = {
  runId: "run_4f2a",
  step: "draft_reply",
  input: {
    thread: "cust_8891",
    facts: ["plan is annual", "last invoice failed"],
    draft: null,
  },
};

Without that object, "replay step four" is a polite way to say "run the graph again and hope." You get a new run, a new input, and a new bill for the nodes that already worked.

Full re-run vs step replay

The difference is not taste. It is whether the host kept the input. If you want that loop, start building or read the docs.