Operator decision for an unknown outcome or a context no checkpoint covers
Records an operator's decision where the platform will not guess: a turn whose outcome is unknown, or context no checkpoint covers. Nothing the execution did outside is reverted.
abandon: theoutcome_unknownturntarget_turn_idbecomescancelledand its input receipt fails; the session isstopped.confirm_completed: withevidence_ref, the turn becomescompletedand its input receipt succeeds; it needs a committed checkpoint that reaches the turn. The session isstopped.close: ends the session for good.start_fresh: continues on a new engine session that does not remember the turns before; the checkpoints so far are retired and queued input runs.retry_restore: restores the same checkpoint again after what made the restores fail is fixed; queued input runs.
The decision takes effect in the request: the receipt is succeeded in the response, with result {resulting_admission_state, checkpoint_revision, resumable}. After abandon or confirm_completed, resume the session; resumable: false means a resume would answer CHECKPOINT_UNAVAILABLE. The decision is also recorded as a system event on the stream.
Scope: sessions:recover (API key or cookie session). Idempotency-Key: required.
AuthorizationBearer <token>For servers and scripts: an API key sent as an HTTP bearer token, Bearer <key>. It holds exactly the scopes it was issued with; a key issued before scopes existed holds none. It never needs the CSRF header, and it cannot manage agents, members, teams or API keys. Issue one in the web console under Settings → API keys; each operation names the scope it needs.
Scope: sessions:recover
id*stringThe session's id.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidIdempotency-Key*stringRequired, 1–255 characters; a UUID per user intent works. A retry with the same key and the same body returns the original response and runs the command once; the same key with a different body answers 409 IDEMPOTENCY_CONFLICT. A missing or invalid key answers 400 BAD_REQUEST, after the body is read.
1 <= length <= 255X-Requested-With?"werft-web"Required with a cookie session: the literal werft-web.
"werft-web"application/json- body
expected_revision*integer0 <= value <= 2147483647reason*string1 <= lengthdecision*stringtarget_turn_id*string1 <= lengthThe decision is applied; the receipt is succeeded.
application/json- response
receipt_id*string^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidreceipt_status*string"accepted""succeeded""failed""unknown"curl -X POST 'https://example.com/v1/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/recovery-decisions' \ -H 'Idempotency-Key: string' \ -H 'Content-Type: application/json' \ -d '{ "decision": "abandon", "expected_revision": 9, "target_turn_id": "3", "reason": "The call had no external effect."}'{ "receipt_id": "c4a1e9d2-7b3f-4e8a-a6c5-1d2e3f4a5b6c", "receipt_status": "succeeded"}