MCP Task Orchestrator · Field guidePlate 2 of 10

One call moves an item. The gate decides.

Every work item with a lifecycle sits in one of five roles. (A schema with lifecycle: none gives its items no role and no transitions.) Agents never edit status directly. They call advance with a trigger, and that call is where the server checks claims, dependencies and required notes.

The line an item travels

start skips review when the schema has no review-phase notes start start start queue notes work notes review notes queue work review terminal block · hold blocked resume returns the item to the role it was blocked from reopen: terminal back to queue, no note or dependency check
Amber bars are gates: the notes named under each bar must be filled before start passes it. Every move into work, review or terminal except cancel also waits for the item's blockers, and entry into work takes its resource leases. Two triggers are not drawn: complete jumps from queue, work or review straight to terminal and checks the required notes of every phase, and cancel jumps to terminal from any role that is not terminal, blocked included, with no note or dependency check. Ownership and seat checks still apply to every trigger an agent sends, cancel included.

Try the gate

A simplified model of the server's rules for one item, using the 4.0 error codes and messages. The gates run in order: transition table, dependencies, notes. Fire triggers in any order, tick the blocker, and read what comes back. The highlighted station above follows along.

Login API

queue

type feature-task · no status label

Notes · tick to upsert

Server says

Every trigger

TriggerFromToGate
startqueue, work or reviewthe next role on the lineDependencies satisfied, then required notes of the current phase. Entry into work also takes the item's resource leases.
completequeue, work or reviewterminalDependencies satisfied, then required notes of every phase. A blocked item must resume first.
block / holdqueue, work or reviewblockedNo dependency or note check. Invalid from blocked. Saves the previous role and a reason.
resumeblockedthe saved roleDependencies satisfied when the saved role is work or review, plus the lease when it is work. Back to queue is not gated.
cancelqueue, work, review or blockedterminalNo dependency or note check, but ownership and seat still apply. Sets the status label to cancelled.
reopenterminalqueueNo dependency or note check. A terminal parent goes back to work.

The gates run in a fixed order and the first to fail answers: claim ownership, seat, the table above, dependencies, notes, leases. Entering terminal also clears the item's claim. To see which gate would answer without sending anything, read items_read select="context": gateStatus.canAdvance and, when false, gateStatus.blockedBy (table, dependency, note or lease).

A block carries a reason

block and hold take a reason: awaiting_decision (with the decisionId of an open decision), dependency, resource or manual (the default). Reads report it, and an awaiting_decision block reports resumable once its decision is no longer pending. Answering a decision never resumes the item: someone still sends resume.

Roles are fixed, labels are yours

The role is what the server reasons about. Alongside it, each transition sets or clears a status label: display text for people and dashboards. The five roles never change. The labels can be renamed per project.

TriggerDefault label
startin-progress. A start that lands in terminal uses the complete label.
completedone
blockblocked
holdnone, so the item keeps its label while it enters blocked
cancelcancelled, unless you configure another
resumenone, so the label is cleared
reopennone, so the label is cleared unless you configure one
a terminal cascadedone (the cascade key)
a start or reopen cascadethe start or reopen label
status_labels:
  start: "working"
  complete: "finished"
  block: "on-hold"
  cancel: "dropped"
  cascade: "auto-completed"

An explicit label wins. With none configured, entering blocked keeps the label the item has and any other transition clears it. The label comes back on every transition result and on item queries. Filter and gate on the role. Show the label.

When a call fails

Every failure carries a kind that says whether retrying can help, and a code to branch on. An agent never has to parse the message text.

A call fails read error.kind transient Back off, then retry the same request claim_held, resource_unavailable, run_at_capacity, internal permanent Do not retry. Fix the request. gate_blocked, dependency_unmet, invalid_transition, not_found shedding Wait retryAfterMs, then retry unavailable: the store or a config read is busy. Poll less often.
The error also carries detail, such as a gate's missing notes or the blockers of a dependency, and a fix sentence for codes that define one. A claim_held error names the item and when the claim expires, never the holder. A gate error does not heal on its own: fill the named note, finish the blocker or resume the item, then send the call again.
{
  "ok": false,
  "error": {
    "code": "claim_held",
    "kind": "transient",
    "message": "...",
    "detail": { "itemId": "550e8400-...", "expiresAt": "2026-10-16T13:15:00Z", "retryAfterMs": 420000 },
    "fix": "...",
    "retryAfterMs": 420000
  },
  "meta": { "reqId": "..." }
}

A one-element write without atomic that fails answers partial_failure, with this error object at data.results[0].error.

An idempotencyKey makes a write safe to resend

Each element of a write call may carry an idempotencyKey. The server records a committed element for 24 hours per principal and tool and returns its stored result again (replayed: true) instead of running it twice. The same key with a different element is idempotency_mismatch.

Same key on every retry

No response arrived, such as a timeout: resend with the same key. A committed element is recorded, so the retry returns its stored result. An element that failed with a gate, dependency or other runtime error is not recorded and runs again; only an invalid_request or unknown_parameter rejection is recorded and replayed.

Schemas and notes never touch until the gate

Schema rules in versioned config pinned to each item requires Gate check advance provides Notes content written by agents stored with no schema reference
A schema is chosen by the item's type, then a default. A config change does not regrade an item already in flight: each item is pinned to the config versions that were current when it was created, retyped, moved to another root, given other traits, taken out of terminal or repinned, and the gate reads that pin. Changing a schema never rewrites existing notes. An item that resolves to no schema advances freely.