- **Park ideas:** tell any agent "park it" and your words become a pipeline item, parked for later.
+## The states, and what ends each one {#lifecycle}
+
+Every agent on the **Agents** page shows one **state**. It posts most of them itself; d2 sets two (*dispatching* and *quiet*) and can set *gone*. Each state ends in its own way, which is the part worth knowing: an agent is only ever marked **gone** by something that has run out.
+
+```
+ up ──► working ──► done (it signed off: done stays done)
+ │ │ ▲
+ │ │ └── merging (folding its branch in: leased like working)
+ │ ▼
+ │ stuck ──► (its next status: back to work)
+ │ warning ─► (finishes what it holds, takes nothing new)
+ │ │
+ ├──► idle (nothing to do)
+ ├──► waiting ──► quiet ──► gone (on its person: 12 h of quiet)
+ ├──► handing-over ──► gone (its handover item closed)
+ └──► stopped ──► gone (its token expired or was revoked)
+
+ any of them ──► gone (nothing posted for twice its `every`)
+```
+
+- **up** — it started and read its skills. Ends on its first piece of work.
+- **working** — on one item (the row names it). Leased: nothing posted for twice its `every` and it is gone, and its items go back to its role.
+- **merging** — a coder folding its own branch in. Coloured and leased exactly like *working*.
+- **idle** — alive with nothing to do. Ends when it takes work.
+- **waiting** — on something. *waiting ›* on the map means it has stopped until **you** type; *waiting · for an item* means it is still running and polling for work, and there is nothing for you to do. One waiting on you goes **quiet** rather than gone, because a chat can't post while you're away — then **gone** after 12 hours of it, with its question and its items kept the whole time.
+- **handing-over** — writing its handover for the next agent in its role. Not measured by its `every`: it ends when that handover item is done or dropped, or, for a row that names no handover at all, once it has gone silent and holds none.
+- **warning** (orange) — low on room to work (context nearly full, a quota nearly used, repeated errors): it finishes the item in hand and takes nothing new. It posts **up** when it can go on. d2 sets this itself for quotas and errors.
+- **stopped** (red) — it can't go on, with the reason; whatever it had taken stays for you to decide. Its row clears, to **gone**, once the token it posted with has expired or been revoked — so a stopped agent stops holding a place among your live agents, without you having to tidy up.
+- **stuck** (red) — one problem it can't get past; you get a notice. No exit of its own: its **next status replaces it**, so an agent that gets going again simply says so.
+- **quiet** (grey) — it has stopped posting, but d2 can still see it alive another way: the monitor on its own channel, an agent by its token's last request, or a chat that is waiting on you. It keeps its last text, its context ring and its items, and reads *quiet · Nm*, the minutes it has said nothing. d2 sets it; no agent can post it.
+- **done** — it signed off. Done stays done (dimmed on the page) until it posts again: it isn't missing.
+- **dispatching** — a dispatcher alive through the agents it runs, with their names. d2 sets it; it is never posted.
+- **gone** — d2's, when something ran out (above). Its items are released to its role and you get a notice, except where the agent had already told you it had stopped.
+
## Watching them {#watching}
- The **Agents** page (in the Toolbox) shows each agent's state (up, idle, working, waiting, handing over, done, stuck, quiet, gone), what it's on, its messages and who it's waiting on; **Agent history** shows what they did. Its map, at the top, is the pipeline's map over every role that reports (roles outside the pipeline, like a dispatcher, after a dotted line), the agents of a role rolled up in one circle: tap a role for its log, or, when several agents share it, for *All <role>* (their merged log) and a chip per agent (that agent's log).
- **Dispatchers:** a dispatcher is an agent that starts and runs other agents unattended, for one role or several (*for coder*). One dispatcher per role. The agents it starts show under their own role, each row naming the dispatcher that started it; the dispatcher itself shows after the dotted line on the map. While its agents work it reads **Dispatching**, with the agents it runs; it's marked gone only once they've all gone quiet too.
-- **Warning** (orange) means an agent is running low on room to work (its context nearly full, a quota nearly used, repeated errors): it finishes the item in hand and takes nothing new. **Stopped** (red) means it can't go on; it's never marked gone, and whatever it had taken stays for you to decide. Both show only here, with the reason, no notice. d2 sets *warning* itself for quotas and errors; the agent sets it for its context, then hands over.
+- **Warning** (orange) means an agent is running low on room to work (its context nearly full, a quota nearly used, repeated errors): it finishes the item in hand and takes nothing new. **Stopped** (red) means it can't go on, and whatever it had taken stays for you to decide; its row clears once the token it posted with has ended ([the states](#lifecycle)). Both show only here, with the reason, no notice. d2 sets *warning* itself for quotas and errors; the agent sets it for its context, then hands over.
- **Waiting for you or for work:** on the map a waiting agent reads **waiting ›** when it has stopped until you type (a chat that asked you something): tap it for its last message, when it posted and **Open the chat ↗**. **waiting · for an item** means it is still running and waiting for work: nothing for you to do.
+- You get a notice when one is stuck or stops posting. An agent **waiting on you** isn't marked gone for its silence — it can't post while you're away — it goes **quiet** and keeps its question and its items, for 12 hours. One **handing over** (writing its handover for the next chat or agent in its role) stays until that handover item closes; the next one in that role replaces it on the board. One that posted **done** stays done (dimmed on the Agents page) until it posts again: it signed off, so it isn't missing. [Every state and what ends it](#lifecycle).
+- **Quiet** (grey) is for an agent that has stopped posting but which d2 can still see alive another way: the monitor, which d2 watches on its own channel (a post or a read there within its `every` means it is working, so a run of quick polls that crowds out its status post no longer reads as gone); an agent whose own token was used within that window; and a chat **waiting on you**, which can't post at all until you answer. A quiet agent keeps its last status text, stays on the map (*quiet · Nm*, the minutes it has said nothing) and keeps its items; it goes **gone** only when that other sign of life stops too — for one waiting on you, after 12 hours — and its own next status clears it. Every other agent still goes straight to gone. d2 sets *quiet* itself — no agent can post it.
-- You get a notice when one is stuck or stops posting. An agent waiting on you, or one **handing over** (writing its handover for the next chat or agent in its role), is never marked gone; the next one in that role replaces it on the board. Nor is one that posted **done**: it signed off, so it stays done (dimmed on the Agents page) until it posts again.
-- **Quiet** (grey) is for an agent that has stopped posting but which d2 can still see alive another way — so far only the monitor, which d2 watches on its own channel: a post or a read there within its `every` means it is working, and a run of quick polls that crowds out its status post no longer reads as gone. A quiet agent keeps its last status text, stays on the map (*quiet · Nm*, the minutes it has said nothing) and keeps its items; it goes **gone** only when that other sign of life stops too, and its own next status clears it. Every other agent still goes straight to gone. d2 sets *quiet* itself — no agent can post it.
- **Approvals:** for a risky step, an agent puts an approval item in the pipeline for you; answer it with **Approve** or **Refuse** on the item's page.
- **Telling one to stop, so it can't be missed:** a stop you (or your designer, or whoever started the agent) send on the board is not only a message — it becomes a **flag on that agent**, and it stays there until the agent acknowledges it. Its row and its chip read **stop pending**, and the row tells you whether the agent has **read** it yet: *not read yet* is a stop that may still be missed, *read, not acknowledged* is one being ignored — two different problems that until now looked the same. Only the agent's **own** reading of the board marks it read; your looking at its messages never does. While a stop is pending the agent **can't start another agent or take new work**, so a round can't begin over a stop nobody answered — but it can still post its status, read the board and reply, because an agent that couldn't speak couldn't acknowledge the stop that is blocking it. It clears the flag by replying to the stop, or by acknowledging it on its next status.