Executor claims

These routes are not called with PUPPI_API_TOKEN. A worker presents a claim token, sent as Authorization: Bearer <claim-token>. The engine mints that token for one attempt. It can be claimed once.

A missing or unknown token is 401 {"error": "unknown_claim"}. already_claimed, already_completed, stale_fence, and settled are 409.

Lease

POST /api/v1/executor/claims/lease takes {"worker_id": "<id>"}. The response is the lease itself, not wrapped in data:

{
  "message": "lease",
  "execution": {},
  "input": {},
  "claim_token": "<token>"
}

execution includes attempt_id and fence. input is the executor input, with bundle_ref set to the bundle URL.

Bundle, events, heartbeat, complete

GET /api/v1/executor/claims/bundle downloads the bundle file for the claimed attempt.

POST /api/v1/executor/claims/events delivers one executor event. 202 has an empty body.

POST /api/v1/executor/claims/heartbeat takes attempt_id and fence. 204 has an empty body.

POST /api/v1/executor/claims/complete posts the final result. The response is {"recorded": true} or {"recorded": false}.