Skip to main content
Harmony
Download

Delivery lifecycle

PreviewAvailable on: WindowsShips in the preview channel only. Not a stable release.

The real delivery states Harmony reports, and why queued work is never shown as completed.

Most multi-agent tooling collapses everything between "sent" and "done" into a single cheerful "delivered". Harmony does not, because the gap between those two states is where all the confusion lives.

The problem this solves

When you send a message to another agent, several different things can be true, and they look identical from the outside:

  • The text reached the agent's harness, but no model turn started.
  • The text is sitting in a queue behind other work.
  • The text is staged in the composer and needs one more keypress.
  • The agent is genuinely working on it.

A tool that reports all four as "delivered" is not reporting; it is guessing.

The shape of it

A2A delivery statesA message you send reaches one of six reported states. Only received_and_started means a turn began. Queued_behind means it is in the harness queue with a measured depth. Received_not_started means the text arrived with no work signal. Needs_enter means it is staged in the composer and will never run until submitted. Idle means the agent is at an empty prompt, which may mean your message never arrived. Unknown means the evidence was insufficient and Harmony declined to guess.You senda2a messageClassifierevidence onlyreceived_and_started — STARTEDqueued_behind — not started, depth Nreceived_not_started — no work signalneeds_enter — staged, never submittedidle — empty promptunknown — insufficient evidenceONLYTHIS
Five of the six states mean work has not begun. Only received_and_started sets started to true.

The states Harmony actually reports

These are the delivery states in the shipping source, not a generic lifecycle:

StateMeansStarted?Queued?
received_and_startedThe agent is working on a turnYesNo
queued_behindAccepted into the harness queue, with N aheadNoYes
received_not_startedText delivered, no work signal yetNoNo
idleAt the prompt, queue emptyNoNo
needs_enterStaged in the composer, needs another EnterNoNo
unknownCould not be determinedNoNo

Alongside the state, a delivery status carries a queue depth (how many prompts are pending — 0 means empty, absent means unmeasured) and a human-readable summary line.

IMPORTANT

started is true only when the state is received_and_started. Nothing else in this table means work began. In particular, queued_behind and received_not_started are both "not started" — they simply fail differently.

Never claim a start without evidence

The classifier is deliberately conservative. It derives state from observable evidence — screen content, detector status, and measured queue depth — and it reports unknown rather than guessing when the evidence is absent.

This is why you will sometimes see unknown. That is the system declining to invent a status, and it is more useful than a confident wrong answer.

needs_enter deserves special attention

needs_enter means the message reached the agent's composer but was never submitted. Everything looks fine — the text is there, the agent is alive — and nothing will ever happen.

This is the single most common "why is my agent ignoring me" cause, and it is precisely the state that a generic "delivered" would hide.

Queue depth changes what a state means

queued_behind with a depth of 1 and a depth of 40 are very different situations. Read the depth before deciding whether to wait or to intervene.

NOTE

A queue draining slowly is not a failure. Sending the same message again because nothing appeared to happen usually makes it worse — you end up with the request queued twice.

Task state is a separate question

Delivery state describes whether a message reached an agent and whether work began. It does not describe whether the work is any good, or whether the task finished. A durable task carries its own state, and completion of a task is not implied by successful delivery of the message that requested it.

Check both:

nala tasks list

Reading it correctly

You seeConcludeDo
received_and_startedWork is in progressWait
queued_behind, depth 2Not started, will start soonWait
queued_behind, depth 40Not started, may not start soonInvestigate the queue
received_not_startedArrived, no work signalGive it a moment, then check the agent
needs_enterStuck in the composerSubmit it
idleAgent is freeYour message may not have arrived at all
unknownNo evidence either wayLook at the agent directly