Workflows, runs, executions, and attempts

A workflow is a file in the repository that describes work to do. A run is the record Shipfox creates when one event or manual start uses that workflow. The workflow file can change over time. The run must stay an accurate record of what it used.

That need for a stable record is why Shipfox keeps more than one level of history.

A run keeps a fixed copy of the workflow

Shipfox syncs workflow files from the repository into stored definitions. A successful sync changes what future runs use. It doesn't start work, and it doesn't change an active or finished run.

When a trigger starts a run, Shipfox copies the workflow into a run attempt. The attempt keeps the parsed job graph and the agent tool selection for that work. The run also keeps its starting event, its inputs, and the source snapshot.

This has two useful results.

• A workflow edit can't change the meaning of work that is already running.
• A later investigation can compare the saved source with the jobs, tools, and outputs that actually ran.

Start a new run when the work must use a newly synced definition. A rerun keeps the original copy.

The six levels of history

run
`-- run attempt
    `-- job
        `-- job execution
            `-- step
                `-- step attempt

A simple run has one item at each level. The extra levels appear when work repeats.

• Run attempt: a rerun adds another attempt under the same run.
• Job execution: a listening job adds an execution for each matching event batch.
• Step attempt: a feedback loop adds an attempt when a gate restarts an earlier step.

These three are different kinds of repetition. A rerun repeats the run plan. A listening execution handles new outside input. A step attempt revises work after a check failed.

Each level has its own status

The run shows the overall state. Each attempt, job, execution, and step keeps its own state and history. A mixed result stays readable: one job succeeded, a listener still waits, and another step is on its second attempt.

A finished run shows whether its current attempt succeeded, failed, or stopped after a cancellation. Earlier attempts and their logs stay available. The dashboard can therefore show both the current result and the path that led to it.

What a rerun keeps

A rerun keeps the same run, starting event, inputs, source snapshot, and workflow copy. It creates a new run attempt with new jobs and executions.

The rerun choice decides what moves into the new attempt.

• Re-run failed jobs carries successful jobs, their published outputs, and named agent sessions into the new attempt. Failed, cancelled, and blocked work runs again. Rerun steps can continue the conversations from the source attempt.
• Re-run all jobs starts every job and named agent session from scratch.

Carried outputs let later jobs use a successful result without rebuilding it. The old job's files and process environment don't move to the new attempt.

Start a new run instead when the event, the inputs, or the workflow definition must change.

What cancellation keeps

Cancellation stops the active attempt. Shipfox stops unfinished work and marks the affected levels as cancelled. Completed logs, outputs, and earlier attempts stay available.

Cancellation therefore differs from deleting a record. It changes the outcome of active work and keeps the evidence needed to understand it.

Use Cancel or re-run work for the procedure. Inspect a run shows how to move through these levels in the dashboard.