Designing recoverable desktop-agent runs
A runbook for saving artifacts, creating durable checkpoints, reconciling failures, and collecting results.
Begin with the artifact contract
Define the native project files, required sidecars, expected export formats, and save behavior before the agent starts. A screenshot is evidence of appearance, not a recoverable artifact. The environment must know which saved files represent useful progress.
For a KiCad workflow that may include a project, schematic, PCB, and local assets. For FreeCAD, the native document should be saved before any derived STEP or STL export is treated as final.
Checkpoint before consequence
Create a checkpoint immediately before an operation that could make the project hard to repair: a large refactor, destructive delete, format conversion, or automated batch edit. First save in the application, then request the checkpoint, and inspect whether durable persistence actually succeeded.
Isle’s public documentation distinguishes an accepted checkpoint call from confirmed persistence and lists failure reasons such as a changing artifact or storage failure (source).
Recover, observe, verify
After recovery, assume that process handles, Python state, and application connection details may have changed. Refresh capabilities, capture the desktop, reopen or verify the intended document, and only then resume.
At the end of a run, download reviewed artifacts before stopping. Retain the environment only when the operational need justifies it, and destroy it when the retained state is no longer required.