# Deployment progress and interrupted agents

Source: https://docs.imprezahost.com/deployment-progress.html

Read the last reported deployment step and distinguish a saved result awaiting delivery from an interrupted execution.

## Read progress in the portal or MCP

Open the app card and read **Last operation** and **Stage**. Refresh to receive the latest report. REST deployment list/detail and `impreza_list_deployments` expose the same `last_operation.progress` fields. This is a last reported step with a timestamp, not a completion percentage or proof that work is still running.

| Step | Meaning |
| --- | --- |
| Preparing / fetching source | Reviewing configuration or obtaining the Git/upload source. |
| Validating / pulling / building | Preparing Compose and images before replacing app containers. |
| Replacing / checking health | Starting the new containers and evaluating startup checks. |
| Installing / routing / checking readiness | Running applicable installation hooks, routes or advisory readiness checks. |
| Recovering / restoring configuration | Attempting the existing recovery policy or restoring preparation files. |
| Preparation completed / reconciling interrupted preparation | Preparation commands finished, or the agent is waiting for supervised preparation (0.6.8+) or checking and restoring a saved checkpoint after restart. |
| Waiting for supervised replacement | After restart, waiting for the original runtime worker and its verified final outcome (agent 0.6.9+). |
| Sending result / finished | Delivering the saved outcome, or a terminal operation already recorded by the API. |

Some steps are skipped when they do not apply. `reported_at` and `age_seconds` describe the last step report. A long build or a reporting outage can leave an older step displayed. Use [runtime health](/runtime-health.html) separately for current container observations; a failed or interrupted operation does not establish that the app is down.

```
{"command_id":"cmd_example","status":"in_progress",
 "progress":{"supported":true,"step":"building","label":"Building images",
 "reported_at":"2026-09-14T19:00:00Z","age_seconds":12,
 "recovery":"none","reason":null}}
```

## What happens after an agent restart

| Local record | Behavior |
| --- | --- |
| Final result saved | The agent resends the same success, failure or cancellation result until the API acknowledges it. It does not execute the deploy again. If the API already recorded it but its response was lost, the repeat is idempotent. |
| Durable unstarted or completed preparation checkpoint (agent 0.6.7+) | The agent verifies the exact operation is still in preparation, checks unchanged container identities, restores previous configuration and records failure or confirms an existing cancellation request. It does not execute the deployment again. Wait for the final result, then retry explicitly if desired. |
| Supervised pull/build still running (agent 0.6.8+) | `recovery=reconciling`. Wait for the original worker and its verified successful completion receipt. The agent then checks whether preparation can be reconciled; it never repeats the pull/build or the deployment. |
| Supervised replacement with a saved identity (agent 0.6.9+) | The original worker continues startup checks, hooks, routes and normal recovery. The agent waits for its final receipt and sends it without reexecuting the deployment. |
| Missing checkpoint, unconfirmed external work or unsupervised replacement boundary | `recovery=required`. Execution is not repeated and subsequent commands remain blocked. Contact support to reconcile the operation and local state. A completed build without either a durable completion checkpoint or a verified worker receipt is still uncertain. |
| Poll response lost before a local record was written | The API returns only recovery metadata for the claimed operation. The agent records the interruption and requests reconciliation; it does not receive another executable deployment payload. |

`recovery=resending_result` means the agent is retrying delivery of a saved result. Wait for `last_operation.status` to become terminal. `recovery=none` means no restart recovery has been reported; it does not prove the agent is online.

## Safe preparation reconciliation

Agent 0.6.7+ can reconcile an interrupted deploy without a final result only from a durable unstarted or completed preparation checkpoint, after verifying the exact operation and the server preparation phase. It verifies unchanged container IDs, restores and verifies previous compose.yaml, .env and startup.json, and records failed or a previously requested cancellation without repeating deployment. recovery=reconciling means verification/restoration is underway, or agent 0.6.8+ is waiting for its supervised pull/build worker; wait for the terminal result before an explicit retry. An external operation without a verified successful completion receipt, replacement without a verified supervised final receipt, container drift, missing/legacy state, recursive data ownership changes and onion provisioning require support reconciliation (recovery=required). No process absence or timeout proves a build finished; from agent 0.6.23 a stopped pull or ordinary build worker without a successful receipt reconciles as failed with the verified restore (see [stopped preparation workers](#stopped-worker-recovery)), and is still never counted as finished. Agent 0.6.12 adds an explicit opt-in exception for [controlled builds](/deployment-cancellation.html#controlled-builds): verified owned executors can be stopped and cleaned after worker loss or host reboot without replay. Missing or inconsistent identity evidence still requires support. Preparation reconciliation does not resume builds, replace containers, restore data or promise runtime health. The private journal must be preserved; older operations do not gain checkpoints retroactively.

The snapshot covers three configuration files, including their prior absence and permissions. Uploaded/Git source directories, downloaded images, retained release snapshots, proxy setup and application data are not rolled back by this operation. It is not a release promotion or a database rollback. A crash during restoration can repeat the same restoration safely while the recorded container identities still match.

## Supervised preparation

Agent 0.6.8+: supported Linux/systemd deploys run image pull and build in a separate supervised process. If the agent restarts, it waits for the exact worker receipt without repeating that work. Only a durable successful receipt allows the existing preparation reconciliation: revalidate operation/phase and unchanged containers, restore previous configuration, and close as failed or confirm a previously requested cancellation. recovery=reconciling can include waiting for the original worker. Missing/invalid receipts, worker failure or timeout, host reboot before a receipt, legacy unsupervised work, replacement uncertainty, data ownership and onion preparation still require review; agent 0.6.23 reconciles a stopped pull or ordinary build worker as a failure instead (see [stopped preparation workers](#stopped-worker-recovery)). A process or service disappearing is never proof of completion. The customer must wait for the final result before retrying; no automatic deploy retry, immediate build termination, data rollback or runtime-health guarantee is added.

## Supervised replacement

Agent 0.6.9+: new supported Linux/systemd deploys keep the authorized container replacement, startup checks, lifecycle hooks, routes and normal startup recovery in one supervised worker. If the agent restarts, recovery=reconciling with step=reconciling\_replacement waits for that original worker. Its verified durable final receipt is delivered without repeating containers or hooks, including a failed deployment whose previous release was restored. Missing or invalid receipts, worker loss or timeout, host reboot before completion, legacy unsupervised operations, data ownership changes and onion provisioning still require support; keep the private journal and do not retry to unblock the queue. This does not add automatic deployment retries, database rollback or zero-downtime traffic switching. Update the agent explicitly before the next deploy.

## Compatibility and local state

Deployment progress and persistent result delivery require agent **0.6.6+** and the `deploy-progress-v1` protocol negotiated when a deploy/redeploy is claimed. MCP **0.28.0+** includes guidance for supervised replacement; 0.27.0 introduced supervised preparation guidance; 0.26.0 introduced preparation reconciliation guidance; 0.25.0 introduced progress guidance. Preparation checkpoints require agent **0.6.7+** when execution starts; supervised pull/build requires **0.6.8+** on Linux with systemd. Supervised replacement requires **0.6.9+** and the same Linux/systemd scope. Older claims and other command kinds show unavailable progress; terminal jobs can still show finished. Update the agent explicitly before starting the next deploy using [the customer update command](/agent-updates.html). Existing operations do not gain recovery support retroactively.

The agent keeps one private operation record under its state directory and deletes the final receipt only after acknowledgement. The record can contain operation credentials, generated application credentials and the previous environment configuration; do not share or delete it to unblock the queue. Corrupt records or an agent/control-plane identity mismatch stop replay for review. One running agent owns that state directory. Persistent delivery depends on preserving the state disk.

See [deployment cancellation](/deployment-cancellation.html) and [deployment safety and recovery](/deployment-safety.html) for the existing rules around preparation, container replacement and data.

## Recorded stage history

The API records a bounded sequence of fixed deployment stages for newly reported operations using `deploy-progress-v1`. In the portal, open the application’s recent deployment history to read the recorded stages. Through REST, read `GET /v1/platform/deployments/{id}` and inspect `release_history[].timeline`. Through hosted or local MCP, use `impreza_api_call` with `{"path":"/platform/deployments/dpl_example"}`, replacing the example with an owned deployment ID.

Each event contains `sequence`, `step`, a fixed `label`, `recovery` and the server’s `reported_at` timestamp. Consecutive identical reports are recorded once. At most 64 transitions per operation are retained; `truncated=true` identifies an expired beginning. Older operations without stored transitions return `available=false`. The existing recent-history window remains ten deploy/rollback attempts. The final attempt status is separate from the sequence: a last build step does not imply the build is still running. This is an agent-reported history, not a duration measurement, live health check or complete audit of every action.

No logs, environment values or control tokens are included in stage events. Recording and the latest-progress update share one transaction; a storage error does not silently discard a transition while acknowledging its latest step. History is available for newly reported operations; older records are not backfilled.

## Preparation after host reboot

Agent 0.6.11+ records the Linux boot identity for new supervised preparation. If a host reboot removes an unfinished build/pull worker and its completion receipt, the agent may restore the prior configuration after verifying the old operation, a local Docker daemon/builder, inactive worker, unchanged preparation inputs and unchanged container identities. It reports a failed operation with `preparation_restored=true`; it never reports the interrupted build as successful and never replays the deployment. Review the failure and retry explicitly. If the server has already closed the command, agents before 0.6.23 retain their local recovery journal for manual reconciliation; agent 0.6.23+ first restores and verifies the previous configuration, and keeps the journal when it cannot. A terminal status alone never authorizes restoration.

This is limited to preparation before container replacement, on Linux/systemd with a local Docker daemon and the built-in default builder. Remote/custom builders, old journals without a boot identity, corrupt receipts, changed configuration/containers and replacement phases remain blocked for review. A second agent restart resends the saved failure until acknowledgement. Keep the state disk and update explicitly to agent 0.6.11 or newer; existing operations do not gain the new evidence retroactively.

## Stopped preparation workers

Agent 0.6.23+: a supervised pull or build whose worker is confirmed stopped without a successful receipt no longer waits for review. This covers a failed pull or build, a pull that stalls or reaches its 45-minute limit, a build past its ten-minute budget and a worker lost to a crash. The agent verifies unchanged container IDs, restores and verifies the previous `compose.yaml`, `.env` and `startup.json`, and reports a failed operation with `preparation_restored=true`. It never reports the interrupted work as successful and never replays the deployment; review the failure and retry explicitly.

If the server has already closed the command, the agent performs the same verified restore and then releases its recovery journal without sending a result, so later commands on the server run. A worker that may still be running, a [controlled build](/deployment-cancellation.html#controlled-builds) (its builder container can outlive the worker), changed containers and a restore that cannot be verified keep the journal for support.