Runs and recovery — scrollport

Catalog tools may take time. The run control tool waits for a bounded period so a normal call returns a result, but it can return a resumable run_id when work is still in progress.

The run states

queued means accepted but not claimed. running means a worker has claimed the execution. succeeded carries the result and final cost. failed carries a teaching error and releases the full hold. awaiting_approval means the human has not authorized the quoted estimate yet.

Resume, do not duplicate

When run returns a run_id, call:

code

{
  "name": "run",
  "arguments": {
    "run_id": "<existing run id>"
  }
}

Do not send tool_id or input in a resume call. Resuming waits on the existing run; it starts nothing and costs nothing.

Terminal recovery

succeeded: read result, artifacts and cost_final, then reconcile with wallet.
failed: read error, message and hint; retry once only after correcting the input or understanding the provider state.
awaiting_approval: show the human the estimate and approval URL.
connection_required: send the human to connect_url, then inspect the same tool again.

The run ledger is the source for charge state. Do not infer billing from a provider response or from whether the HTTP request timed out.