Runs

A run is one attempt at a task. Tasks are long-lived; runs are how that work actually executes, and a task may accumulate several of them.

When a new run is created#

• Initial execution of a task.
• Resumption after suspension — budget increase, approval granted, dependency restored.
• Retry after a non-recoverable failure, starting from the last valid checkpoint.
• Fork: exploring an alternative approach from a checkpoint without discarding the original run.

The event log#

Each run writes an append-only event log. The log is the source of truth for observability, debugging and audit — and it is what Streaming exposes in real time.

Forking a run#

class="tok-com">// Explore an alternative approach from a known-good checkpoint
const fork = await pimsy.runs.fork({
  runId: class="tok-str">"run_7c1a9d",
  fromCheckpoint: class="tok-str">"ckpt_step_4",
  note: class="tok-str">"Try the queue-based design instead of synchronous retries"
});

const [a, b] = await Promise.all([
  pimsy.runs.wait(class="tok-str">"run_7c1a9d"),
  pimsy.runs.wait(fork.id)
]);