Core Concepts
Run lifecycle
Follow task and job runs from snapshot and dispatch through heartbeats, completion, failure, stopping, reruns, and retention.
A run is an auditable execution record, not just a live process. Envoy creates the record before dispatch, updates it while the executor works, and retains its status and metadata after the process exits.
Task run flow
The normal status progression is pending → running → success or failed. A user-initiated stop produces a terminal cancelled state after the process is stopped.
Snapshot and resolution
Before dispatch, the control plane:
- loads the selected task version;
- validates and coerces declared arguments;
- resolves the connector mapping;
- reads connector configuration through the secret provider;
- writes the run record;
- sends the resolved work to an executor.
The executor does not need direct access to the control-plane state database or secret provider.
Logs and metrics
The subprocess writes data output to stdout and human diagnostics to stderr. Server execution captures the streams into the configured run log store. Metrics are associated with the run and summarized for the UI.
The run detail page follows active updates and exposes arguments, step metrics, logs, stop, rerun, and log cleanup actions according to the run state and user role.
Heartbeats and leases
Running work has a lease. HTTP executors renew leases in heartbeat traffic; the local executor path renews them in the server process.
If a running lease expires, or a pending dispatch remains stale, the run reaper marks the record failed with an executor-unavailable error. This prevents abandoned rows from occupying capacity forever.
Manual failed runs remain failed until an operator deliberately reruns them. Scheduled jobs can run again on a later trigger. Supervised loop tasks have their own restart behavior described in Task structure.
Job runs
A job run creates child task runs by DAG level:
- nodes with no unmet dependency can run in parallel;
- a dependent node waits for its prerequisites;
- selected-task runs include dependencies unless explicitly skipped;
- the job failure policy determines whether the DAG pauses, aborts, or continues after a child failure.
A paused or failed job run can be resumed where the product exposes a resume action. Completed nodes are not blindly repeated.
Stop and rerun
Stopping requests cancellation; it is not equivalent to deleting the run. A connector performing long I/O must honor the abort signal for prompt cancellation, while the executor also controls the subprocess.
A rerun creates a new run record. It preserves the earlier run as history and uses the current task/job entry point shown by the UI. Review connector mappings and editable job configuration before rerunning if the environment has changed.
Retention
Retention applies only to terminal statuses. By default, old log content is pruned while run rows remain. An operator can configure retention to delete complete run records and associated metrics instead.
See Run and log retention before enabling run deletion.