Preview a rerun/retry of a step: the resolved scope, and whether expired Workspace Snapshots widened it (ADR-0061 s5).

GET

/v1/runs/{id}/steps/{step}/rerun-plan

curl --request GET \
  --url https://example.com/v1/runs/example/steps/example/rerun-plan

Parameters

Path Parameters

id

required

string

Run id

step

required

string

Step id

Responses

200

Media typeapplication/json

GET …/steps/{step}/rerun-plan body: what a rerun/retry of this step would actually execute — before the user confirms it (ADR-0061 s5, and ADR-0027’s rule that smart never means mysterious).

A read-only dry run. The interesting case is a widened one: a Run reopened after its Workspace Snapshots expired cannot rerun just the step you pointed at, because the inputs that step consumes no longer exist — so the scope expands upstream to regenerate them, in the limit back to clone. That is a bigger action than the button implies, so it has to be visible first.

object

expired_inputs

required

Each expired input that caused the widening: the consuming step, the step that produced the missing snapshot, and its CAS root.

Array<object>

One expired Workspace Snapshot behind a widened rerun (ADR-0061 s5).

object

consumer

required

The step whose input workspace is incomplete.

string

produced_by

required

The upstream step that produced the missing snapshot.

string

root

required

The CAS merkle root the store no longer holds.

string

invalidated

required

Every step that would re-execute, sorted — the invalidation set after any widening.

Array<string>

starts_from

required

The steps the rerun effectively starts from (no dependency inside the set). [target] on an ordinary rerun; on a widened one this is the phrase the affordance says out loud — “this re-runs from clone”.

Array<string>

steps

required

The same set as invalidated, execution-ordered and carrying each member’s WHY (git-bug 4afaa3e) — computed by the engine, identically for this preview and for the plan a POST rerun/retry executes and returns.

Array<object>

One member of a rerun plan, with its WHY (git-bug 4afaa3e).

object

because_of

The in-set step this one is here because of: the cascade parent (minimum in-set need by id, deterministic) or, for regenerate, the consumer whose expired input dragged it in. Absent only on the target.

string | null

is_gate

required

A gate (ADR-0008): the rerun pauses for approval here — the plan never claims a gate will run.

boolean

reason

required

Why it is in the set.

string

Allowed values: target cascade regenerate regenerate_cascade

step

required

The step that re-runs (a gate re-arms and pauses instead of running).

string

target

required

The step the plan is for.

string

widened

required

The subset of invalidated present only because a Workspace Snapshot expired: upstream steps dragged in to regenerate data. Empty on an ordinary rerun.

Array<string>

Example

{
  "steps": [
    {
      "reason": "target"
    }
  ]
}

404

No such run or step