Document the reactor.done vs inference.done distinction

Names the failure mode in the events table, cites the three
defects it caused, and points at the onTurnBoundary /
onReactorShutdown guards. States plainly that this is a naming
convention rather than an enforced constraint: no lint tooling
is configured in this repo to add a restricted-syntax rule, and
a type-level fix would require modifying the vendored
@intx/types / @intx/inference packages, which is off-limits.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -18,8 +18,33 @@ 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 — naming the
+question makes the right thing easier to write than the wrong one.
+
+This is a convention, not an enforced constraint: nothing stops a future
+call site from writing `event.type === "reactor.done"` directly instead of
+reaching for the guard. Two enforcement routes were considered and both are
+out of scope here — a lint rule (`no-restricted-syntax` or similar) would
+mean standing up ESLint or Biome from scratch, since neither is configured
+anywhere in this repo, disproportionate for a Low-priority cleanup; and a
+type-level fix branding `event.type` would require modifying `@intx/types`
+or `@intx/inference`, which are vendored and off-limits. Reviewers should
+treat a bare `event.type === "reactor.done"` / `"inference.done"` comparison
+outside `reactor-events.ts` as a signal to ask why the guard wasn't used.
 
 ### ReactorActions