Workflow states, errors, and Receipts
Use this reference to interpret records returned by the CLI and API. For a first workflow, see managed Build or Guard with your own agent.
Managed Build states
Read the summary from GET /v1/runs and the current record from GET /v1/runs/{id}. Track the lifecycle, workflow disposition, and verification verdict separately.
| Field | Values and meaning |
|---|---|
lifecycle |
define, approve, build, verify, deliver, closed. This is the stage. A closed run can have several outcomes, including cancellation. |
disposition |
ready, needs_specification, working, repairable, blocked, needs_human_judgment, rejected, rollback_recommended, canceled, or superseded. This describes the workflow's next step or outcome. |
verdict |
not_evaluated before verification, verified when all required checks pass independently on the exact candidate, failed when a required check fails, or inconclusive when required evidence is incomplete. |
For a run that needs a decision, read the approval queue or open the run in the panel. A verified verdict describes the candidate's evidence. A signed Receipt is the record of a completed landing.
Guard proposal states
Read the proposal detail and use status together with its separate verdict and disposition.
| Status | What to do |
|---|---|
proposed |
Review the change and the verification quote. An authorized person can start checks in the panel. |
verifying |
Follow the assigned verification and wait for results. |
needs_evidence, inconclusive, failed |
Review the check results and remediation. Resolve missing evidence or fix the candidate before asking for approval. |
candidate_changed, stale_base |
Read the latest refs. Propose the intended head again. If the base moved, update the change against the new base first. |
verified, ready_for_approval |
Checks passed for the recorded candidate. Wait for ready_for_approval and have the eligible human review and confirm in the panel. |
landed, rejected, superseded |
The proposal landed, was refused or stopped, or was replaced. Read the Receipt for a landed proposal. |
When checking a proposal, use the full head commit and proposal digest. Review the quote digest separately from the proposal digest. A new candidate, base, or quote may require new checks or approval.
Errors and retries
Gateway errors that use the v1 error format include kind: "error", api_version: "v1", code, and message. Some endpoints and the Git listener use other response shapes. Use the HTTP status and inspect the body. A successful JSON response can also carry incomplete sources; see the API reference.
| HTTP status or code | What to check |
|---|---|
400 invalid_request or 422 plan_invalid |
Check the payload, field names, required identifiers, or plan validation message. |
401 unauthenticated |
Check the credential for that host. For the Gateway, obtain a fresh token in the intended workspace. |
402 funding_required |
Ask the authorized human to check the quote and available funding in the panel. |
403 forbidden, interactive_required, or listener scope_required |
Check the role or token scope. For interactive authorization, hand off to the signed-in human. |
404 not_found |
Check the exact ID, active workspace, and feature availability. |
409 conflict, stale_base, candidate_changed, quote_changed, or needs_evidence |
Read the current resource, then resolve the conflict. The Gateway or listener may return different codes for a moved candidate. |
409 checks_not_approved |
Ask a workspace owner or maintainer to approve the repository checks in the panel, then retry the proposal. |
429 rate_limited |
Respect Retry-After when present and back off before retrying. |
502 or 503 |
An upstream or required check may be unavailable. Retry reads with backoff. If a write's outcome is unknown, read back its state before retrying. |
When an operation accepts an idempotency key, reuse it with the same request after an ambiguous failure. Refresh identities before authorizing a changed request. Agents should report the refusal, resource ID, and observed state to the human without sharing credentials.
Read a signed Receipt
Fetch the full signed record by its Receipt ID. The Gateway endpoint GET /v1/receipts/{id} returns it at data.receipt. The standalone CLI wraps the Gateway response in its own data field, so dengel --json receipt RECEIPT_ID returns the record at data.data.receipt.
Use jq to extract the record from the CLI response.
dengel --json receipt RECEIPT_ID | jq -e '.data.data.receipt'
The Guard proposal detail shows a Receipt summary when one exists. For Receipt searches, q matches the Receipt ID, bundle, canonical commit, or canonical tree.
| Fields | What they record |
|---|---|
id, bundle, bundle_digest |
Stable Receipt ID and identity of the exact bundle landed. |
target_branch, canonical_commit, canonical_tree |
The branch moved and the commit and tree recorded after landing. |
landed_at, landed_by, approved_by |
When Dengel landed it and the human approval that authorized the action. |
signature, timestamp, canonical_signature |
Dengel's Receipt signature and, where recorded, the timestamp and separate standing of the commit signature. |
verification |
When present, the tested commit and tree and the per-criterion evidence. Treat a missing historical verification record as unrecorded. |
author, approval_context |
When recorded, the human sponsor and agent attribution, the approval rule, and feedback or accepted risks present at landing. |
artifact, deployment_ref |
Optional artifact or pipeline references. Check deployment status in the deployment system. |
Keep the full signed record for audit and compare its canonical commit to a fresh read of the intended repository and branch. If the branch has advanced, check that the Receipt commit is in its history. Use the canonical commit for Git comparison. The recorded tree digest has its own format. For cryptographic verification, use the trusted Dengel signing key and the Receipt's signing format for your deployment. Fetching a Receipt and checking the remote branch establishes record and branch agreement.
