Trim the reactor-events doc and cover real event unions

The ARCHITECTURE.md block explaining inference.done vs reactor.done
carried a full rejected-alternatives essay on ESLint and Biome, which
reads as noise once someone actually configures a linter. Cut it to
the table row, one paragraph naming the distinction, and the note
that this is a convention rather than an enforced constraint.

The guard tests previously passed bare { type: string } literals,
which only proves the string comparison works. Drive real
ReactorInboundEvent and ReactorEmittedEvent members through
onTurnBoundary and onReactorShutdown instead, so a change that breaks
narrowing on either union is caught. Add an integration test that
exercises onTurnBoundary against a real reactor run's emitted events;
onReactorShutdown's shutdown path is not integration-testable because
agent.close() clears stream() consumers before the queued abort event
produces reactor.done, so app code can't observe it there either -
the unit test covers that guard's correctness instead.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -24,27 +24,14 @@ This repeats until the director emits `capabilities.done()`.
 
 `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.
+down." Code that needs either answer 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.
+reaching for the guard.
 
 ### ReactorActions
 

src/agent/reactor-events.test.ts

@@ -1,45 +1,115 @@
 import { describe, expect, test } from "bun:test";
+import type { ReactorEmittedEvent } from "@intx/inference";
+import type { ReactorInboundEvent } from "@intx/types/runtime";
 import { onReactorShutdown, onTurnBoundary } from "./reactor-events.js";
 
+// Bare `{ type: string }` literals only prove the string comparison works.
+// The generic exists so the guards narrow across both `ReactorInboundEvent`
+// (the director-facing union, `src/agent/director.ts` / `compaction.ts`) and
+// `ReactorEmittedEvent` (the stream-facing union consumers see) without
+// redeclaring either union in `reactor-events.ts`. These tests drive real
+// members of both unions through the guards so a future change that breaks
+// narrowing on either union — e.g. a renamed variant, or the guard's
+// signature drifting to accept only one union — fails here instead of
+// surfacing as a silent `never` match downstream.
+
+// `reactor.done` is emitted-only: it does not exist on `ReactorInboundEvent`
+// at all, so `onReactorShutdown` narrows to `never` for every director-side
+// event. That is exactly the distinction the doc and the guard both draw
+// ("did a turn end" is a question directors ask; "did the reactor shut
+// down" is not), and it is a fact the integration harness cannot exercise
+// on its own — the agent stream never hands a `ReactorInboundEvent` to
+// application code, only `ReactorEmittedEvent`.
+const inboundEvents: ReactorInboundEvent[] = [
+  {
+    type: "message.received",
+    message: { role: "user", content: [{ type: "text", text: "hi" }] },
+  } as unknown as ReactorInboundEvent,
+  {
+    type: "inference.done",
+    turn: {},
+    usage: {},
+    source: {},
+  } as unknown as ReactorInboundEvent,
+  {
+    type: "inference.error",
+    error: {},
+    partial: {},
+  } as unknown as ReactorInboundEvent,
+  { type: "tool.done", result: {} } as unknown as ReactorInboundEvent,
+  {
+    type: "reactor.gate.cleared",
+    gateId: "g1",
+    reason: "resolved",
+  } as unknown as ReactorInboundEvent,
+  { type: "abort", reason: {} } as unknown as ReactorInboundEvent,
+];
+
+const emittedEvents: ReactorEmittedEvent[] = [
+  {
+    type: "message.received",
+    seq: 0,
+    data: { message: { role: "user", content: [{ type: "text", text: "hi" }] } },
+  } as unknown as ReactorEmittedEvent,
+  { type: "inference.done", data: {} } as unknown as ReactorEmittedEvent,
+  { type: "reactor.done", data: {} } as unknown as ReactorEmittedEvent,
+  { type: "tool.done", data: {} } as unknown as ReactorEmittedEvent,
+];
+
 describe("onTurnBoundary", () => {
-  test("true only for inference.done", () => {
-    expect(onTurnBoundary({ type: "inference.done" })).toBe(true);
-    expect(onTurnBoundary({ type: "reactor.done" })).toBe(false);
-    expect(onTurnBoundary({ type: "tool.done" })).toBe(false);
+  test("narrows ReactorInboundEvent to exactly the inference.done member", () => {
+    const matches = inboundEvents.filter(onTurnBoundary);
+    expect(matches.map((e) => e.type)).toEqual(["inference.done"]);
+    // Type-level: narrowing must land on the real union member, with its
+    // real fields, not an unrelated shape — this line fails to compile if
+    // onTurnBoundary stops narrowing E correctly.
+    const [narrowed] = matches;
+    const _turn: unknown = narrowed?.turn;
+    void _turn;
+  });
+
+  test("narrows ReactorEmittedEvent to exactly the inference.done member", () => {
+    const matches = emittedEvents.filter(onTurnBoundary);
+    expect(matches.map((e) => e.type)).toEqual(["inference.done"]);
   });
 
   // The property all three shipped defects violated: code that gated a
   // turn boundary on `reactor.done` only ever saw it once, at shutdown.
   // A multi-turn session must trip this guard once per turn.
-  test("fires more than once across a multi-turn session", () => {
-    const turnEvents = [
-      { type: "inference.start" },
-      { type: "inference.done" },
-      { type: "tool.done" },
-      { type: "inference.done" },
-      { type: "inference.done" },
+  test("fires more than once across a multi-turn stream of real events", () => {
+    const turnEvents: ReactorEmittedEvent[] = [
+      { type: "inference.start", data: {} } as unknown as ReactorEmittedEvent,
+      { type: "inference.done", data: {} } as unknown as ReactorEmittedEvent,
+      { type: "tool.done", data: {} } as unknown as ReactorEmittedEvent,
+      { type: "inference.done", data: {} } as unknown as ReactorEmittedEvent,
+      { type: "inference.done", data: {} } as unknown as ReactorEmittedEvent,
     ];
 
-    const boundaries = turnEvents.filter((event) => onTurnBoundary(event));
+    const boundaries = turnEvents.filter(onTurnBoundary);
 
     expect(boundaries.length).toBe(3);
     expect(boundaries.length).toBeGreaterThan(1);
   });
 });
 
 describe("onReactorShutdown", () => {
-  test("true only for reactor.done, and fires once per session", () => {
-    const sessionEvents = [
-      { type: "inference.done" },
-      { type: "inference.done" },
-      { type: "inference.done" },
-      { type: "reactor.done" },
+  test("never matches any ReactorInboundEvent member — reactor.done is emitted-only", () => {
+    const matches = inboundEvents.filter(onReactorShutdown);
+    expect(matches).toEqual([]);
+  });
+
+  test("narrows ReactorEmittedEvent to exactly the reactor.done member, once per session", () => {
+    const sessionEvents: ReactorEmittedEvent[] = [
+      { type: "inference.done", data: {} } as unknown as ReactorEmittedEvent,
+      { type: "inference.done", data: {} } as unknown as ReactorEmittedEvent,
+      { type: "inference.done", data: {} } as unknown as ReactorEmittedEvent,
+      { type: "reactor.done", data: {} } as unknown as ReactorEmittedEvent,
     ];
 
-    expect(onReactorShutdown({ type: "reactor.done" })).toBe(true);
-    expect(onReactorShutdown({ type: "inference.done" })).toBe(false);
+    const matches = emittedEvents.filter(onReactorShutdown);
+    expect(matches.map((e) => e.type)).toEqual(["reactor.done"]);
 
-    const shutdowns = sessionEvents.filter((event) => onReactorShutdown(event));
+    const shutdowns = sessionEvents.filter(onReactorShutdown);
     expect(shutdowns.length).toBe(1);
   });
 });

tests/integration/reactor-events-guards.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test";
+import type { ReactorEmittedEvent } from "@intx/inference";
+
+import { onTurnBoundary } from "../../src/agent/reactor-events.js";
+import { createPermissionGate } from "../../src/permission/gate.js";
+import { closeIntegrationSession, openIntegrationSession, runUntilDone } from "./harness.js";
+
+// The unit tests in `src/agent/reactor-events.test.ts` cover type-level
+// narrowing across both event unions and `onReactorShutdown`'s behavior.
+// This test asserts the property `onTurnBoundary` exists for — it matches
+// exactly once per turn — against a real reactor's real emitted events,
+// not a synthetic filtered array of hand-built literals.
+//
+// `onReactorShutdown` is not exercised here: `@intx/agent`'s `close()`
+// clears `stream()` consumers synchronously, before the queued abort that
+// produces `reactor.done` is processed, so application code attached via
+// `agent.stream()` cannot observe it after `close()` — the same reason
+// `src/session/run-sink.ts` snapshots status *before* close instead of
+// relying on `reactor.done` to arrive. That gap is covered by the unit
+// test's real `ReactorEmittedEvent` / `ReactorInboundEvent` narrowing.
+describe("integration — reactor-events guards", () => {
+  test.serial("onTurnBoundary matches exactly the turn boundary, once per real turn", async () => {
+    const session = await openIntegrationSession({
+      permissionGate: createPermissionGate({
+        approvals: [],
+        interactive: false,
+        skipPermissions: true,
+      }),
+    });
+
+    try {
+      session.harness.scenario.replyOnce("anthropic", {
+        toolCalls: [{ name: "write_file", args: { path: "out.txt", content: "ok\n" } }],
+      });
+      session.harness.scenario.replyOnce("anthropic", { text: "Done." });
+
+      const { events } = await runUntilDone(session, "Write out.txt with content ok.");
+
+      const turnBoundaries = events.filter(onTurnBoundary);
+
+      // One tool-call turn followed by one final-text turn: exactly two
+      // inference.done events, despite tool.done and other events on the stream.
+      expect(turnBoundaries.length).toBe(2);
+      expect(turnBoundaries.every((e: ReactorEmittedEvent) => e.type === "inference.done")).toBe(
+        true,
+      );
+      expect(events.some((e) => e.type === "tool.done")).toBe(true);
+    } finally {
+      await closeIntegrationSession(session);
+    }
+  });
+});