Hosted Runs

Hosted runs let agents do longer work while todos.md keeps status, logs, and artifacts.

Lifecycle

1. Create a run.
2. Queue it with an organization scope.
3. Let a worker claim it with a lease.
4. Keep the lease alive with heartbeats.
5. Recover expired leases or timed out work.
6. Review logs and artifacts.

platform-todos runs list

platform-todos runs create example-capability --body '{"goal":"ship"}' --max-attempts 2 --timeout-ms 900000

Worker lifecycle

Workers use the hosted API or MCP tools to claim one queued run, report heartbeats, and let todos.md requeue or fail work when the lease or timeout expires.

platform-todos api post /api/v1/runs/claim --body '{"workerId":"worker-a","leaseMs":30000}'

platform-todos api post /api/v1/runs/<run-id>/heartbeat --body '{"workerId":"worker-a","leaseMs":30000}'

Artifact layout

Each run can export files:

.todos/
  exports/
    run_01hy...
      manifest.json
      receipt.json
      result.json

Async status

Long jobs should be resumable by run id.

platform-todos runs show <run-id>

platform-todos runs logs <run-id>

platform-todos runs artifacts <run-id>