Skip to main content
Choose recovery based on what Kiwi confirmed. A known validation, authority, missing-resource, or stale-command rejection means Kiwi rejected that request. A lost response or server error can occur after a run commit, so do not treat every HTTP error as proof that nothing happened.

​
Unknown outcome or definitive rejection

Every run state mutation requires a positive current expected_run_version. Do not reuse a version from before another action. See the Integration API reference for the supported external request shapes.

​
Attempt IDs

When a ready node has no currentAttemptId, generate a new UUID for the first attempt. Use the currentAttemptId returned by the server for subsequent mutations to that attempt. Do not invent an attempt ID from a null field. For a manually reported resumable blocker, only the same principal, performer, and session may resume the blocked attempt; call start_step with that same attempt ID. A new agent session must not impersonate the old session to resume it. A handoff_step call ends the current performer attempt and queues the step under a new ID reserved for the run’s responsible human. The responsible human starts that queued attempt. An unrelated agent cannot claim it.

​
Checks and candidate changes

Before reporting CI evidence, read GET /v1/runs/{runId}/checks. Use its current runVersion, accepted plan revision, candidate reference, implementation attempt, and verification attempt. If Verify is ready and verificationAttemptId is null, generate one UUID for the first checker report; then use the returned current attempt on later reports. Each check binds to the current accepted Plan, candidate, Implement attempt, and Verify attempt. A pass is the only status that can satisfy the gate. fail fails Verify; blocked and not-applicable do not satisfy it. Failed or blocked check outcomes require authorized rework; they cannot be resumed as a manually reported blocker. Rework preserves attempt history. It can keep the current accepted Plan or explicitly revise it. Revising Plan increments the Plan revision and returns to Plan. Rework at Implement invalidates the current candidate and all dependent verification and review evidence. Reports for the previous candidate remain visible but cannot pass the new gate. Rerun checks and review against the new candidate.

​
Credential outcomes

If MCP or checker credential issuance has an unresolved result, inspect its nonsecret status in the Kiwi app before creating another credential. An issuance replay does not reveal an already-issued secret. If the secret is confirmed lost, use the app to revoke that credential and issue a replacement. If Kiwi shows that revocation is pending, use the available retry action in the app and check its status there.

​
Rework, handoff, and cancellation

An authorized human can request rework through the app. The request needs a reason and may set revise_plan. The designated owner decides rework on a submitted Plan; other rework follows the workflow’s authorized role. A responsible human or project Admin can cancel with a reason. Cancellation prevents future Kiwi run transitions but does not stop external agents, jobs, or systems. Use Manual participation for human roles and structured step outputs, and Runs and history to inspect current attempts and prior events.