The coordinator records these states in order where applicable:
created → validated → preparing → prepared → starting → running
→ collecting → verifying → exporting → completed
↘ failed
- Validate: load JSON, apply safe defaults, reject unknown fields, unsafe paths/options, symlinks, and unbounded resource values.
- Prepare: inspect Git, reject dirty sources, create a detached worktree or isolated clone, canonicalize the existing host workspace path before bind mounting (including macOS
/privatealiases), and resolve the selected Docker/Podman image by build, reuse, or pull. - Launch: build explicit backend argv and start the labeled container with the configured timeout and bounded output capture. Docker and Podman launch with
--pull=never: image acquisition and verification happen during preparation, and a subsequently missing image fails startup instead of causing an implicit pull. - Collect: capture stdout/stderr, exit status, timing, changed files, and a Git patch.
- Verify: reject post-run workspace symlinks, run the versioned declarative checks in separate labeled containers when the workload succeeds, validate patch/artifact boundaries, and record execution versus verification separately.
- Export: stream bounded stdout/stderr to redacted run logs while the container runs, then copy declared artifacts only into the run directory and apply the same secret policy to persisted evidence. Declared secret values are always redacted from
changes.patchbefore it is written, independently ofartifacts.secret_action; that field only escalates a patch that held a secret to a failed run when it is set toreject. - Record: write the structured receipt, including failure stage, diagnostics, and a versioned integrity manifest that can be verified offline with
workcell verify. - Clean: remove the labeled container and ownership-marked temporary worktree. On failure,
--keep-failedpreserves only the explicitly owned temporary workspace.
Before the integrity manifest is sealed, Workcell writes
preservation.json using kujo.preservation-outcome/v1. Filesystem
preservation means the owned workspace directory remains; it never means the
container or process remains alive. Remote providers that are destroyed after
collection report filesystem preservation as unsupported instead of
inventing a local path. A handoff bundle records clean source, patch/evidence
references, limitations, cleanup ownership, and an optional retention deadline.
The same record phase writes execution-result.json, reexecution.json, and
reexecution-input.json. These separate the observed execution outcome from
the metadata needed to start a new attempt. A re-execution is not a rollback or
deterministic replay; live network dependencies disable automatic retry and
leave external effect state explicitly unknown.
Retention expiry never schedules deletion by itself. The explicit
clean --preservation path accepts only an expired, satisfied local-filesystem
outcome owned by workcell-clean, reuses the workspace ownership checks, and
writes workcell-preservation-deletion/v1 under the run root's deletions/
directory so the sealed run manifest is not mutated.
Timeouts are distinct from ordinary workload failures. The process API returns a timeout result; Workcell retrieves available container logs, attempts the selected backend's graceful stop, then escalates to label-scoped forced removal. The receipt records timeout: true and the CLI returns exit code 6. Cleanup is attempted after validation-stage partial setup, image failures, startup failures, workload failures, export failures, and receipt failures.
| Code | Meaning |
|---|---|
| 0 | Workcell completed and cleanup succeeded. |
| 2 | Usage or definition validation failure. |
| 3 | Missing Git/source dependency or workspace preparation failure. |
| 4 | Backend/image preparation failure. |
| 5 | Container startup failure. |
| 6 | Timeout. |
| 7 | Workload command exited non-zero. |
| 8 | Verification or artifact export failure. |
| 9 | Cleanup failure. |
| 10 | Internal Workcell failure. |
The workload's own exit code remains in receipt.json; the CLI code identifies the category of failure. A Docker/Podman startup error is distinct from a workload command failure.
Remote execution uses resolve → provision → prepare → execute → collect → export → destroy → record. Resolve must accept every required semantic control before provision. Workcell persists an ownership-bound provision intent before calling the provider, then atomically attaches the returned handle before any workspace upload. A lost provision response therefore remains inventory-recoverable instead of being recorded as “not provisioned.” Prepare verifies the observed workspace package digest. Execute and declarative verification produce normalized terminal results; a nonzero workload exit is a result, not an adapter transport failure. Collect may report incomplete deltas or unknown metrics but cannot invent evidence. Export returns only declared paths, which core revalidates and re-hashes. Destroy must return itemized cleanup and zero remaining run-owned resources for a clean success.
Cancel and inventory are mandatory protocol operations used by control and recovery paths. --cancel-file gives local callers and agent hosts a deterministic cancellation hook for both v1 containers and portable execute operations. Portable cancellation terminates the adapter process, records a cancelled result, and destroys the owned remote resource from its durable handle; it does not claim that a provider performed graceful process cancellation. Pause, resume, snapshot, and metrics remain optional capabilities and do not alter the canonical success lifecycle. Workcell does not retry workloads; Dispatch or Relay may start a new correlated Workcell attempt under their own policy.
Portable Docker and Podman use the same stable OCI lifecycle implementation as v1 rather than an external subprocess adapter. This keeps engine launch, streaming, artifact export, verification, and cleanup behavior identical while the coordinator presents the backend-neutral receipt v2 contract.
Use run --preserve-until-evaluated --retain-until <future-UTC-time> when an
external gate runs after the action. The intent is declared before execution.
The default mode is handoff_bundle: export declared artifacts, logs and source
references before destroying provider resources; then write the preservation
outcome and hash manifest. Local --preservation-mode filesystem also retains
the successful owned workspace. Runtime containers are still destroyed.
Remote filesystem/live-pause/snapshot requests remain explicitly unsupported
unless an adapter actually supplies the capability. No remote resource is kept
alive indefinitely. Review the outcome, not the requested mode, before choosing
re-execution. Cleanup remains operator-owned through the recorded deadline and
existing clean --preservation command; the flag does not start a timer daemon.
Without this opt-in, successful workspaces keep their existing cleanup behavior.