# Run lifecycle

> Source: https://docs.clonepartner.com/concepts/run-lifecycle/

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

```mermaid Task run lifecycle
sequenceDiagram
  actor User
  participant CP as Control plane
  participant EX as Executor
  participant P as Task subprocess

  User->>CP: Start task
  CP->>CP: Validate arguments and connector mapping
  CP->>CP: Resolve connector secrets and create run
  CP->>EX: Dispatch resolved task
  EX->>P: Spawn isolated process
  P-->>EX: Logs and metrics
  EX-->>CP: Heartbeats and status
  P-->>EX: Exit
  EX-->>CP: Terminal result
  CP-->>User: Updated run detail
```

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:

1. loads the selected task version;
2. validates and coerces declared arguments;
3. resolves the connector mapping;
4. reads connector configuration through the secret provider;
5. writes the run record;
6. 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](/reference/tasks/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](/operations/retention) before enabling run deletion.