Document the reactor.done vs inference.done distinction

Names the failure mode in the events table and cites the three
defects it caused, alongside the new onTurnBoundary /
onReactorShutdown guards.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -18,8 +18,22 @@ This repeats until the director emits `capabilities.done()`.
 
 | Event | When it fires |
 |---|---|
-| `inference.done` | The LLM finished one assistant turn. Carries the full turn content. |
+| `inference.done` | The LLM finished one assistant turn. Carries the full turn content. Fires once per turn, every turn — this is the **turn boundary**. |
 | `tool.done` | One tool call completed. Carries the result and the original `callId`. |
+| `reactor.done` | The reactor loop shut down. Fires once, at the end of the run — not between turns. |
+
+`inference.done` and `reactor.done` read as near-synonyms at a call site but
+answer different questions: "did a turn end" versus "did the reactor shut
+down." Three shipped defects came from code that needed a turn boundary but
+keyed off `reactor.done` instead: queued messages never dispatched because
+the send-queue drain waited for shutdown; `run.json`'s `turnsUsed` froze for
+an entire session because the mid-run snapshot only re-fired on shutdown;
+and the shell run state didn't return to idle between turns. Documentation
+didn't prevent the second and third instances, so code that needs to ask
+"did a turn end" or "did the reactor shut down" should go through the
+`onTurnBoundary` / `onReactorShutdown` guards in `src/agent/reactor-events.ts`
+rather than comparing `event.type` to a string directly — the guards can't be
+handed the wrong event by mistake the way a bare string comparison can.
 
 ### ReactorActions