The work item object

A work item reaches a client in three shapes, and the route entries name the one each answers with. This page lists the fields of each shape, then explains the ones that need it.

The three shapes

The stored row

The stored row has one key per column of the item's row. A column that holds JSON comes as text, except the three override columns, which are decoded. It has none of the computed fields, such as display_status, stop or budget_cap.

The list row

The list row is built for the board, from one grouped query, so it leaves out the fields that need a lookup per item, apart from a short progress. It has these keys:

• From the stored row: id, title, description, repo, status, chain_template, current_node_id, bead_id, created_at, updated_at, retry_at, archived_at and archived_by.
• chain_definition, as the chain's nodes, which the board draws as a stage bar. attachments, as a decoded list, [] when none.
• pending_gate, the gate waiting on a person, or null.
• fallback, the fallback launch the item's latest session started on, or null.
• display_status, stop, step, mr_ref and progress, as explained below.

It has no agent_overrides, node_overrides or policy_override, and none of the keys only the detail has.

The detail object

The detail object is the stored row, with chain_definition replaced by the chain's nodes and attachments by a decoded list, plus the keys below. Fields that need an explanation covers display_status, stop, test_result, budget_cap, running_time, summary, mr_ref, progress, worktree_exists, worker_sessions, scope_runs and fix_target.

Fields that need an explanation

Why the item stopped

The stop field

stop is {kind, node, resume_at, reason} on the list. The detail adds task, attempt and facts. On a cap or budget stop it adds limit, and on a budget stop scope.

facts.cause names why an infra stop happened, when Kraft knows. The facts field lists the values. The failed card chooses its action from it, and an infra stop without one reads as a generic infrastructure stop.

A rate_limit stop's facts also carries fallback and fallback_allowed: the stopped task's declared fallback harnesses, and which of those its resolved policy still allows.

stop.kind

stop.kind is one of twelve values: gate, question, cap, budget, failed, conflict, mr_closed, config, infra, stuck, wait and rate_limit. Stop kinds says what each means, and Why did my item stop? gives each stop's reason with its fix.

A needs_human row saved before database migration 45 has no recorded kind. It reads the kind of its stop event, else question for a reason that starts needs_context:, budget where the event carries budget, cap where it carries capped, else failed. A waiting row with none reads wait and a rate_limited one rate_limit.

stop.limit

A cap or budget stop on the detail also carries limit: {path, key, value, maximum} when a PATCH of the item's policy can raise what stopped it, and omits it when none can.

value is the limit that stopped it, in attempts, minutes or dollars. maximum is the maxima ceiling or null.

Raise it with PATCH /api/work-items/{id} {policy: {<key>: N}} (item-wide) or {policy: {paths: {<path>: {<key>: N}}}}, then POST /api/work-items/{id}/retry.

There is no limit for:

• a budget stop on the item's own cap (POST /api/work-items/{id}/budget/raise raises that one), on a node, step or task's budget_usd, a token_budget, the daily cap or spend a harness never reported;
• a node, step or task's time cap;
• a gate's or wait's timeout;
• a loops: cap in policy.yaml;
• exhausted rate-limit retries;
• a fix loop whose bound the older node_overrides set.

stop.scope

A budget stop on the detail also carries scope, the cap that stopped it:

Tests and spend

The test_result field

test_result is {scopes: [{command, scope, passed, exit_code, session_id}], passed}, or null when no scope has finished.

• One entry per scope, passed or failed. scope is null when the repo's table no longer declares the command, and exit_code when none was recorded. passed is true when every scope passed.
• An area's setup appears only when it failed.
• A scope still running is left out.
• No test counts.
• session_id is the scope's session. Read its log with GET /api/worker-sessions/{id}/log.

The budget_cap field

budget_cap is {cap_usd, source, key, spent_usd, daily}.

• cap_usd is whichever cap stops the item first: the lower of its own cap and the item-wide budget_usd of its policy. It is null when neither is set. This holds in the API and in kraft view show --json.
• key says which cap it is, and the PATCH field that changes it: budget_usd for the item's own cap, policy.budget_usd for the policy one.
• source is item when the item itself set the reported cap, by its own budget_usd or by its own policy override, and policy when it comes from policy.yaml or the chain. So source: item with key: policy.budget_usd means the item's policy override.
• spent_usd is the item's own, all-time spend.
• daily is {spent_usd, cap_usd}: the instance's spend since local midnight against policy.budget.daily_usd, the same two numbers as GET /api/budget/today.

POST /api/work-items/{id}/budget/raise (kraft item raise-budget) raises whichever of the two caps stopped the item.

Progress and the worktree

The summary field

summary is a run's progress at a glance:

{"nodes_done": 3, "nodes_total": 8, "gates_passed": 1, "step": {"index": 2, "count": 2} | null}

nodes_done and nodes_total count against the frozen chain. gates_passed is how many of the completed nodes carry a gate after them (gate_after). step is the current node's step (1-based) out of its own steps, read from its latest non-escalation session's task, when the node declares more than one, and null otherwise.

The progress field

progress is {current, total, title, tasks}, or null when the item has no plan to follow. Each task is {n, title, state, sha}. state is done, current or pending, and sha is the short hash of the newest commit on the item's branch that names the task, or null. Rows on the list carry only current, total and title.

The worktree_exists field

worktree_exists is whether worktree_path is a directory on disk. It is false before the item first runs and after its worktree was reclaimed or deleted.

open-worktree, mr-labels and the viewed routes answer 404 when the directory is missing. The message is "this work item has not started, so it has no worktree yet" for an item that never ran, and "this work item's worktree was removed from disk" for one that did. A retry or resume recreates the directory.

diff and compare check the item's base_ref first. Before the first run it is unset: diff answers 200 with an empty diff and base_ref: null, and compare answers 409. With a base_ref set and the directory gone, both answer 404.

The scope_runs field

scope_runs lists every command a changed-test-scope task ran in its node's current pass, in the order each started, across rounds and repositories. Each entry is {session_id, repository, round, command, passed, exit_code?, scope?, area?, setup?, order?, selected?, pending?, node_id, hook_point}. The node's view draws its scopes from it.

• passed is null until the command finishes.
• A command its round picked that has not started yet comes last, pending: true with no session_id, while the node is still running.
• round is the session's fix-loop round, 0 for the first pass. -1 is the repair an on_failure recovery runs inside a fix-loop node, and the re-measure after it.
• A retry starts a new pass, so the list keeps only the newest one.
• It is empty for a chain with no such task.

The fix_target field

fix_target is {gate, node, then, round} while a gate is pending, and null with none pending.

GET /api/work-items/{id}/fix-target answers the same shape for a target the reviewer picked: see Fix target.

Related

• Filing, reading and changing work items and Gates, run control, ending and retry: the routes that answer these shapes.
• Events: the stop.kind values, the facts of a stop, and the events behind each field.
• Work item statuses: what each stored and displayed status means.