Gates, run control, ending and retry

This page lists the board's routes that act on a work item once it is filed: they decide its gates, control its run, end it and retry it. The routes that file, read and change an item are on Filing, reading and changing work items, which also says that every board route can change in any release. A route here that answers with the item itself answers the stored row, never the detail object.

Deciding a gate

POST /api/work-items/{id}/gates/{gate}/approve

Approves the pending gate {gate} and starts the chain again at the node after it. kraft item approve calls it. {gate} is the id of a gate node of the item's chain. A review agent still running on the gate is stopped first: a person's decision outranks it. The decision is recorded with who made it: see Events.

The body is optional.

The answer is the stored row: the item's columns as saved, without display_status, stop or the other fields the detail adds.

The final review gate always needs its document, and any other gate does when it sets artifact_required: true. The 403 check reads the header, so a caller that leaves it off passes: see Agents and gates.

POST /api/work-items/{id}/gates/{gate}/reject

Rejects the pending gate {gate} and sends the chain back to work, with your note as the steer. kraft item reject calls it. A review agent still running on the gate is stopped first. Each rejection counts against the gate's reject loop. Once that cap is spent, the item stays at the gate, stopped as cap, and nothing reruns: a person decides.

The answer is the stored row.

Pausing and resuming

POST /api/work-items/{id}/pause

Stops a running item: its running sessions are ended and the item becomes paused. kraft item pause calls it. It takes an item that is active, waiting on CI or a review, or rate_limited, and clears the timer that would wake a waiting or rate-limited item. The body is empty.

{"id": "...", "paused_sessions": ["..."]}

paused_sessions holds the ids of the sessions it ended, and is empty for an item with none running.

POST /api/work-items/{id}/steer

Stores a note for the next agent launch of a paused item. A POST /api/work-items/{id}/resume that carries steer stores it and resumes in one call. The note is stored once and leads the prompt of the launch that takes it.

The answer is {"id": "...", "steer": "..."}. It takes a paused item, and a needs_human item stopped on a worker's question (stop.kind question).

POST /api/work-items/{id}/resume

Starts a paused item, including one just filed, at the node it stood on. kraft item resume calls it. The worktree is first brought up to date with its base branch. A conflict goes to the node's on_conflict handler or stops the item as conflict. Another git failure stops it as infra, and the answer is then the stored row.

{"id": "...", "node_id": "implementation", "steer": "...", "steered": ["implementation.main.implement"]}

Skipping and escalating

POST /api/work-items/{id}/skip

Advances past the current node, or the gate the item waits at, without running or approving it, and starts the chain at the next node. kraft item skip calls it.

With a path that names a step or a task, only that scope is skipped: an active item keeps its walk, which counts the scope as done, and any other item resumes from where it stood. Skipping a gate does not approve it: the event is node_skipped, with the gate's id, and no gate_approved.

A running node's sessions are ended first. It takes an item that is active, waiting, paused or needs_human.

The answer is the stored row.

POST /api/work-items/{id}/escalate

Sends a message to an agent that helps with a stopped item: it starts an escalation turn, or continues the item's thread. kraft item escalate calls it. The turn runs after the answer. When the turn asks to retry its own item, Kraft performs that once the turn ends.

The answer is {"id": "...", "status": "escalating"}.

POST /api/work-items/{id}/escalate/stop

Ends the running escalation turn. The item keeps the status and stop it had: only the turn ends. The body is empty.

{"id": "...", "session_id": "...", "status": "paused"}

session_id is the turn's session, and status is always paused.

Ending a work item

GET /api/work-items/{id}/cancel-preview

Shows what POST /api/work-items/{id}/cancel would do, without doing it.

{
  "running": {"node": "mr_checks", "task": "mr_checks", "attempt": 1, "started_at": "2026-10-03T10:00:00+00:00"} | null,
  "kept": {"branch": "kraft/...", "worktree": "/path", "findings": 0, "threads": 1},
  "mr": {"ref": 54, "url": "https://...", "state": "open"} | null,
  "spend": {"spent_usd": 1.2, "cap_usd": 5.0},
  "beads": ["kraft-ab1"]
}

beads holds the item's own bead, the ones it implements, and those a Fixes or Closes trailer on its commits names (an id starting Kraft-, any case). An item filed while bd was down has none yet, and close_beads files one for it and closes that.

POST /api/work-items/{id}/cancel

Ends the item, with a reason, and stops whatever is running. The worktree and the branch stay, and so does the merge request unless close_mr is set. The item's stored status becomes abandoned, which the board shows as cancelled: see Displayed status.

The answer is the stored row. With close_mr: true it also carries close_mr: {"ok": true}, or {"ok": false, "error": "..."} when there was no open merge request or the forge call failed. A failed close never undoes the cancel. The key is absent when close_mr was not asked for.

POST /api/work-items/{id}/complete

Ends the item as completed, by hand, with a reason, and stops whatever is running. kraft item complete calls it. Nothing runs and no gate is approved: the worktree, the branch and the merge request stay as they are. The reason goes on the timeline, as work_item_manually_completed and then work_item_completed. The item's beads stay open unless close_beads is set.

The answer is the stored row.

POST /api/work-items/{id}/archive

Archives a completed or cancelled item and reclaims its worktree. The item still reads as completed or cancelled. It answers {"id", "archived_by", "worktree_removed"}. An item already archived answers the same shape with worktree_removed: false.

Archive never deletes a commit, and keeps the attachment copies. It does discard uncommitted changes in the worktree, which it removes with git worktree remove --force. These keys appear only in the cases below.

POST /api/work-items/{id}/restore

Puts an archived item back under Done. The item's status never moved when it was archived, so it reads as completed or cancelled again. Restore clears archived_at and archived_by and records work_item_restored. It does not bring back the worktree that archive removed. The body is empty.

{"id": "...", "status": "completed"}

status is the item's stored status, completed or abandoned.

POST /api/work-items/{id}/abandon

Ends the item and deletes its worktree, branch and attachment copies. Uncommitted work and unpushed commits are lost. It answers {"id", "status": "abandoned", "worktree_removed"}.

When the item's repository has been moved or deleted, abandon removes the worktree directory directly and adds repo_missing, the repository path it could not find. It does nothing to the branch.

An item that is already abandoned, a cancelled one included, is reclaimed again without a second event. A second call finds nothing left and answers worktree_removed: false.

Retrying a work item

POST /api/work-items/{id}/retry

Reruns the node an item stopped on, with steer text if you give it. It is the only way back onto an item stopped by a task failure, and kraft item retry calls it.

Only a retry from a person resets the cap counters of what it reruns. A retry that carries X-Kraft-Session-Id or X-Kraft-Client: mcp leaves them where they stand, so an item stopped on a cap stops again.

With no path and no restart, a pending rewind replaces path, and its note goes before your steer. A rewind is a request-changes review submitted while no gate was pending.

{"id": "...", "node_id": "implement", "path": "implement", "loop": null, "steer": null, "attempt": 2}

A path naming a task counts only that task's sessions, and one naming a step takes the highest next attempt over the step's tasks. A path naming a node, which is the default, takes the highest over the node's own tasks: all of its tasks except its escalation task, which is never counted. A restart does the same for the first node. A walk may enter at any one of those tasks.

A retry that stops at once answers the stored row.

An escalation turn that retries its own item is not refused. Kraft records the request and performs it once the turn ends, and the answer is {id, node_id, loop, steer}, with no path or attempt.

POST /api/work-items/{id}/reopen-mr

Reopens the item's merge request on the forge and retries the stopped node, the same as POST /api/work-items/{id}/retry with no path. Use it on an item that stopped because its merge request was closed there without merging.

A poller checks every waiting or needs_human item parked at a merge-request node against the forge every policy.forge_poll_s seconds (default 300). When the merge request was closed without merging, it stops the item with stop.kind: "mr_closed" and facts: {ref, url}. See Events: work_item_needs_human.

There are three ways out: this route, POST /api/work-items/{id}/retry with the merge request node's path to open a new merge request, and POST /api/work-items/{id}/cancel. Cancelling leaves the closed merge request and the worktree as they are. MR closed externally lists the board's button for each.

The answer is that of /retry with no path, and so are its 409s. The ones that matter here: the item has no current node, every slot is busy, or a walk is already running.

The route reopens the merge request on the forge and records mr_reopened before it retries. If the retry then answers 409, the merge request stays reopened and the item stays stopped. Repeating this call asks the forge to reopen it again, which may fail: retry the item with POST /api/work-items/{id}/retry instead.

Routes a worker calls

A worker session calls these on its own item. Neither route refuses a worker session. A sandboxed worker under a network: policy reaches progress through its channel but not mr-labels: the channel allows only a short list of routes (see Agents and gates).

POST /api/work-items/{id}/progress

Records that the implementing worker started plan task task, as a plan_progress event. kraft item progress calls it.

The answer is {"id": "...", "progress": {...}}, where progress is the progress field with its tasks, or null when the item has no plan to follow.

POST /api/work-items/{id}/mr-labels

Labels the item's merge request on the forge and re-creates its pipeline, then records mr_labels_set. kraft item mr-label calls it. A repair agent calls it once it has read a failed CI trace and decided which labels the trace asks for.

The answer is {"work_item_id": "...", "labels": [...]}, the labels as set.