docs(chat): correct the mailbox docs and describe the stop guarantee

The mailbox section described head-of-line behaviour that no longer happens: it
said a control record arriving before a message keeps `hasPending()` false and
makes `next()` wait, when a message behind a stop or a handover is now reported
and returned normally. Docs that state the opposite of what ships are worse than
none, so those claims are replaced with what the delivery guarantee actually is.

Also documents two things that had no coverage. A stop applies only to the turn
that was live when it arrived, so a recovered message's turn is not aborted by a
stop from before the crash. And `sessionInEventId` is a lower bound rather than
the sequence of the record a turn answered, which is the mistake a client makes
when it tries to match a turn boundary to its own send.

Author: ericallam

docs/ai-chat/custom-agents.mdx

@@ -179,6 +179,12 @@ for await (const turn of session) {
 
 The frontend stops a turn with [`transport.stopGeneration(chatId)`](/ai-chat/frontend#stop-generation), which writes a stop signal to the session's input stream. It aborts the current turn's generation but keeps the run alive, so the next message continues on the same session.
 
+A stop only applies to the turn that was live when it arrived. If the run crashes
+and a later run recovers a message that had not been answered yet, a stop that
+was already applied before the crash is not applied again, so the turn answering
+the recovered message runs to completion. A stop sent after the recovery is live
+and aborts that turn as normal.
+
 `turn.signal` is a combined stop-and-cancel `AbortSignal`, fresh each turn. Pass it to `streamText` so the stop reaches the model, then let `turn.complete()` finish the turn:
 
 ```ts trigger/my-chat.ts
@@ -227,16 +233,16 @@ For full control, skip `createSession` and compose the primitives directly:
 
 | Method | Behavior |
 | --- | --- |
-| `peek()` | Return the buffer head when it is a message, without consuming it; otherwise return `undefined` |
-| `hasPending()` | Resolve `true` when the buffer head is a message; does not consume it |
+| `peek()` | Return the next queued message without consuming it, or `undefined` when none is queued |
+| `hasPending()` | Resolve `true` when a message is queued; does not consume it |
 | `next({ timeoutInSeconds? })` | Consume exactly one message record in channel order, or resolve `undefined` when the optional timeout elapses |
 | `on(handler)` | Consume messages as they arrive and invoke the handler |
 | `waitWithIdleTimeout(options)` | Wait warm, then suspend the run until the next message arrives |
 
-`hasPending()` checks whether the local, already-delivered buffer head is a
-message that `next()` can consume immediately. It does not query the remote
-Session channel or start a subscription. Use `waitWithIdleTimeout()` when the
-loop needs to idle until future input arrives.
+`hasPending()` checks whether a message has already been delivered locally and is
+waiting for `next()` to take it. It does not query the remote Session channel or
+start a subscription. Use `waitWithIdleTimeout()` when the loop needs to idle
+until future input arrives.
 
 `next({ timeoutInSeconds: 0 })` is also a local, non-blocking read. Call
 `next()` without a timeout, or with a positive timeout, to subscribe for future
@@ -262,18 +268,15 @@ owns its own turn sequencing never advances past input it has not taken. By
 contrast, `on()` commits a record as soon as it dispatches the handler; avoid
 mixing `on()` and `next()` when a single loop owns mailbox consumption.
 
-The Session `.in` channel also carries control records such as handovers. If one
-comes before a message, `hasPending()` stays `false` and `next()` leaves the
-control record for its own consumer. After that record is handled, the message
-becomes pending.
-
-A control record that nothing on the run consumes is discarded rather than left
-at the head of the channel. `hasPending()` and `next()` only look at the head, so
-a record parked there would make every message behind it undeliverable.
+The Session `.in` channel also carries control records such as stops and
+handovers. Those are routed to their own consumers and never block messages: a
+message that arrived behind one is still reported by `hasPending()` and still
+returned by `next()`, in channel order. The same holds for a record kind this
+version of the SDK does not recognise, which is discarded rather than left where
+it would make every message behind it undeliverable.
 
-`next()` still returns `undefined` whenever no message became consumable before
-the timeout, including while a control record that does have its own consumer
-sits at the head.
+`next()` returns `undefined` when no message became consumable before the
+timeout.
 
 A complete loop:
 

docs/ai-chat/reference.mdx

@@ -504,7 +504,7 @@ All methods available on the `chat` object from `@trigger.dev/sdk/ai`.
 | `chat.createSession(payload, options)`      | Create an async iterator for chat turns                                                                                      |
 | `chat.pipe(source, options?)`               | Pipe a stream to the frontend (from anywhere inside a task)                                                                  |
 | `chat.pipeAndCapture(source, options?)`     | Pipe and capture the response; returns `{ message, status, error }`                                                         |
-| `chat.writeTurnComplete(options?)`          | Signal turn complete; returns `{ lastEventId, sessionInEventId }` resume cursors                                            |
+| `chat.writeTurnComplete(options?)`          | Signal turn complete; returns `{ lastEventId, sessionInEventId }` resume cursors. `sessionInEventId` is a lower bound, not the sequence of the record the turn answered |
 | `chat.createStopSignal()`                   | Create a managed stop signal wired to the stop input stream                                                                  |
 | `chat.messages`                             | Incoming message mailbox; supports non-consuming `.peek()` / `.hasPending()`, single-record `.next()`, `.on()`, and suspend-aware `.waitWithIdleTimeout()` |
 | `chat.local<T>({ id })`                     | Create a per-run typed local (see [`chat.local`](/ai-chat/chat-local))                             |
@@ -645,7 +645,7 @@ The `onEvent` callback receives a `ChatTransportEvent` (exported from `@trigger.
 | `message-send-failed` | `messageId?`, `source`, `error`, `status?`, `durationMs`, `partId?`, `bodyBytes?` | A send definitively failed after internal retries. Fires in addition to `useChat`'s `onError`. |
 | `stream-connected` | `resumed`, `lastEventId?`, `messageId?` | The SSE subscription to the session's output stream started delivering. `resumed: true` when reconnecting from a stored cursor (page reload) rather than following a fresh send. `lastEventId` is the cursor it connected from. |
 | `first-chunk` | `chunkType?`, `lastEventId?`, `messageId?`, `sinceSendMs?` | The first response chunk of a turn arrived. `sinceSendMs` is the delta from the last turn-producing send — time to first token without any bookkeeping. |
-| `turn-completed` | `lastEventId?`, `sessionInEventId?`, `messageId?`, `sinceSendMs?` | The agent's turn-complete control record arrived — the "finished answering" signal. `sinceSendMs` is the full turn latency; `sessionInEventId` is the agent's committed input-stream cursor. |
+| `turn-completed` | `lastEventId?`, `sessionInEventId?`, `messageId?`, `sinceSendMs?` | The agent's turn-complete control record arrived — the "finished answering" signal. `sinceSendMs` is the full turn latency; `sessionInEventId` is the cursor the agent can safely resume its input stream from. Treat it as a lower bound: it is held back behind any message still waiting to be handled, so it can be below the sequence of the record this turn answered. Do not use it to decide whether a turn boundary belongs to your own send. |
 | `stream-error` | `error`, `status?` | The output stream failed unrecoverably. |
 
 `source` identifies the send path: `"submit-message"`, `"regenerate-message"`, `"steer"` (`sendPendingMessage`), `"action"` (`sendAction`), `"stop"` (`stopGeneration`), or `"head-start"`.