@zooid/transport-matrix 0.11.2 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zooid/transport-matrix",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "Matrix Application Service transport for zooid. Routes inbound Matrix messages to ACP agents and posts replies plus approval custom events back to threads.",
   "type": "module",
   "license": "MIT",
@@ -28,8 +28,8 @@
     "marked": "^18.0.4",
     "sanitize-html": "^2.17.4",
     "yaml": "^2.5.0",
-    "@zooid/acp-client": "^0.11.2",
-    "@zooid/core": "^0.11.2"
+    "@zooid/acp-client": "^0.13.0",
+    "@zooid/core": "^0.13.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.13.0",

package/src/context-provider.test.ts

@@ -347,4 +347,122 @@ describe('MatrixContextProvider', () => {
     expect(byId.get('$img')?.text).toBe('[image: dog.jpg]')
     expect(byId.get('$file')?.text).toBe('[file: report.pdf]')
   })
+
+  it('renders agent prose sent as m.notice — ZNC025 §10 switches agent output to m.notice', async () => {
+    const client = fakeClient({
+      fetchRoomMessages: vi.fn().mockResolvedValue({
+        chunk: [
+          {
+            event_id: '$e1',
+            sender: '@architect:hs',
+            origin_server_ts: 1000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.notice', body: 'agent output' },
+          },
+        ],
+        end: undefined,
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map([['@architect:hs', 'architect']]),
+    })
+    const page = await provider.getRoomHistory('!room:hs', {})
+    expect(page.messages[0]?.text).toBe('agent output')
+  })
+
+  it('getRecentThreads keeps a thread rooted in an m.notice', async () => {
+    const client = fakeClient({
+      fetchRoomMessages: vi.fn().mockResolvedValue({
+        chunk: [
+          {
+            event_id: '$root',
+            sender: '@architect:hs',
+            origin_server_ts: 1000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.notice', body: 'agent thread root' },
+          },
+        ],
+        end: undefined,
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map([['@architect:hs', 'architect']]),
+    })
+    const page = await provider.getRecentThreads('!room:hs', { limit: 50 })
+    expect(page.threads.map((t) => t.id)).toEqual(['$root'])
+    expect(page.threads[0]?.text).toBe('agent thread root')
+  })
+})
+
+// The authorization boundary for context reads is the homeserver, not this
+// class: every read is impersonated as the *agent's own* Matrix user, so a room
+// or thread the agent isn't in fails at Matrix. Nothing asserted that, and a
+// stale doc comment claimed the opposite (that asUserId was the AS bot, which
+// can read every room) — so a refactor could have quietly swapped in the AS
+// user and turned a homeserver-enforced boundary into an honour system.
+describe('MatrixContextProvider — reads are impersonated as the agent', () => {
+  const AGENT = '@dev.assistant:hs'
+
+  function provider(overrides: Partial<MatrixClient>) {
+    return new MatrixContextProvider({
+      client: fakeClient(overrides),
+      asUserId: AGENT,
+      agentBots: new Map(),
+    })
+  }
+
+  it('threads the agent user through every read, never a different user', async () => {
+    const fetchRoomMessages = vi.fn().mockResolvedValue({ chunk: [], end: undefined })
+    const getJoinedMembers = vi.fn().mockResolvedValue({ joined: {} })
+    const fetchRoomName = vi.fn().mockResolvedValue('room')
+    const fetchEvent = vi.fn().mockResolvedValue(null)
+    const fetchThreadRelations = vi.fn().mockResolvedValue({ chunk: [], next_batch: undefined })
+    const p = provider({
+      fetchRoomMessages,
+      getJoinedMembers,
+      fetchRoomName,
+      fetchEvent,
+      fetchThreadRelations,
+    } as unknown as Partial<MatrixClient>)
+
+    await p.getRoomHistory('!room:hs', { limit: 10 })
+    await p.getRecentThreads('!room:hs', { limit: 10 })
+    await p.getThreadHistory('!room:hs', '$root', { limit: 10 })
+    await p.getChannelMembers('!room:hs')
+    await p.getChannelInfo('!room:hs')
+
+    expect(fetchRoomMessages.mock.calls.every(([a]) => a.asUserId === AGENT)).toBe(true)
+    expect(fetchThreadRelations).toHaveBeenCalledWith(expect.objectContaining({ asUserId: AGENT }))
+    // These two take the user as a positional argument, not a field.
+    expect(getJoinedMembers).toHaveBeenCalledWith('!room:hs', AGENT)
+    expect(fetchRoomName).toHaveBeenCalledWith('!room:hs', AGENT)
+    expect(fetchEvent).toHaveBeenCalledWith('!room:hs', '$root', AGENT)
+  })
+
+  // An agent naming a room it isn't in must fail loudly. Swallowing the error
+  // and returning `{ messages: [] }` would read as "empty room" to the model —
+  // indistinguishable from a real empty room, and it would hide the refusal.
+  it('propagates a homeserver refusal instead of returning an empty page', async () => {
+    const forbidden = new Error('fetchRoomMessages(!private:hs) failed: 403')
+    const p = provider({
+      fetchRoomMessages: vi.fn().mockRejectedValue(forbidden),
+    } as unknown as Partial<MatrixClient>)
+
+    await expect(p.getRoomHistory('!private:hs', { limit: 10 })).rejects.toThrow('403')
+  })
+
+  it('propagates a refusal on the thread path too', async () => {
+    const p = provider({
+      fetchEvent: vi.fn().mockResolvedValue(null),
+      fetchThreadRelations: vi
+        .fn()
+        .mockRejectedValue(new Error('fetchThreadRelations($x) failed: 403')),
+    } as unknown as Partial<MatrixClient>)
+
+    await expect(p.getThreadHistory('!private:hs', '$x', { limit: 10 })).rejects.toThrow('403')
+  })
 })

package/src/context-provider.ts

@@ -32,7 +32,18 @@ interface MatrixMessageEvent {
 
 export interface MatrixContextProviderOpts {
   client: MatrixClient
-  /** AS sender_localpart user (read access). */
+  /**
+   * The **agent's own** Matrix user (`@{workstation}.{name}:server`), which
+   * every read is impersonated as via `?user_id=`. Not the AS bot: that would
+   * read every room on the homeserver and make this class the only thing
+   * standing between an agent and someone else's conversation.
+   *
+   * This is load-bearing. It is what makes the homeserver — not our own
+   * bookkeeping — the authorization boundary for context reads, so a room or
+   * thread the agent is not in fails at Matrix with 403/404. Anything that
+   * widens who can name a room (a CLI, a new tool parameter) is safe only
+   * while this holds.
+   */
   asUserId: string
   /** Map of Matrix user IDs → agent names, for is_agent / agent_name flags. */
   agentBots: Map<string, string>
@@ -84,7 +95,14 @@ export class MatrixContextProvider implements TransportContextProvider {
     const threads: ThreadOverview[] = []
     for (const ev of chunk as unknown as MatrixMessageEvent[]) {
       if (ev.type !== 'm.room.message') continue
-      if (ev.content?.msgtype !== 'm.text' || typeof ev.content.body !== 'string') continue
+      // m.notice: agent prose sends as m.notice so
+      // .m.rule.suppress_notices silences the chunk storm server-side
+      // (ZNC025 §10) — a thread root sent by an agent must still surface here.
+      if (
+        (ev.content?.msgtype !== 'm.text' && ev.content?.msgtype !== 'm.notice') ||
+        typeof ev.content.body !== 'string'
+      )
+        continue
       const relatesTo = ev.content['m.relates_to']
       if (relatesTo?.rel_type === 'm.thread') continue // skip thread replies
       const agent = this.opts.agentBots.get(ev.sender)
@@ -169,7 +187,8 @@ export class MatrixContextProvider implements TransportContextProvider {
       }
     }
 
-    if (msgtype !== 'm.text' || typeof body !== 'string') return null
+    // Agent prose sends as m.notice (ZNC025 §10); m.text is human prose.
+    if ((msgtype !== 'm.text' && msgtype !== 'm.notice') || typeof body !== 'string') return null
     return {
       id: ev.event_id,
       sender: ev.sender,

package/src/event-encoders.test.ts

@@ -10,6 +10,7 @@ import {
   toPlanBody,
   toErrorBody,
   toAvailableCommandsBody,
+  toTurnEndBody,
 } from './event-encoders.js'
 
 describe('toToolCallBody', () => {
@@ -165,7 +166,6 @@ describe('toErrorBody', () => {
       threadRoot,
     )
     expect(body).toMatchObject({
-      msgtype: 'm.notice',
       body: '⚠ [auth_missing] Authentication required',
       session_id: 'sess-1',
       turn_id: 'turn-1',
@@ -179,6 +179,14 @@ describe('toErrorBody', () => {
     expect(body.recovery).toMatch(/^https:\/\/zooid\.dev\/docs\//)
   })
 
+  it('carries no msgtype — dev.zooid.error is not m.room.message, so the field is meaningless', () => {
+    const body = toErrorBody(
+      { kind: 'error', agentId: 'a', sessionId: 's', turnId: 't', code: 'auth_missing', message: 'x', transient: false },
+      threadRoot,
+    )
+    expect(body).not.toHaveProperty('msgtype')
+  })
+
   it('truncates message to 250 chars and detail to 2000 chars', () => {
     const body = toErrorBody(
       {
@@ -230,3 +238,63 @@ describe('toErrorBody', () => {
     expect(body.session_id).toBeUndefined()
   })
 })
+
+describe('toTurnEndBody', () => {
+  it('carries the produced_output flag ZOD076 reads', () => {
+    expect(toTurnEndBody({ agentId: 'claude', sessionId: 's1', producedOutput: true }, '$root')).toEqual({
+      body: 'claude finished',
+      agent_id: 'claude',
+      session_id: 's1',
+      produced_output: true,
+      'm.relates_to': { rel_type: 'm.thread', event_id: '$root' },
+    })
+  })
+
+  it('carries a preview of the final message — the prose itself never pushes', () => {
+    // Agent prose goes out as m.notice and is silenced by
+    // .m.rule.suppress_notices, so without this the only notification the user
+    // gets says an agent finished and nothing about what it said.
+    const out = toTurnEndBody(
+      { agentId: 'claude', sessionId: 's1', producedOutput: true, lastMessage: 'the deploy is green' },
+      '$root',
+    )
+    expect(out.last_message).toBe('the deploy is green')
+    // body stays the turn-boundary summary a generic Matrix client renders.
+    expect(out.body).toBe('claude finished')
+  })
+
+  it('collapses whitespace and truncates a long final message', () => {
+    const out = toTurnEndBody(
+      {
+        agentId: 'claude',
+        sessionId: 's1',
+        producedOutput: true,
+        lastMessage: '  line one\n\nline two   ' + 'x'.repeat(400),
+      },
+      '$root',
+    )
+    const preview = out.last_message as string
+    expect(preview.length).toBe(140)
+    expect(preview.startsWith('line one line two ')).toBe(true)
+    expect(preview).not.toContain('\n')
+  })
+
+  it('omits last_message entirely when the turn produced nothing', () => {
+    const out = toTurnEndBody({ agentId: 'claude', sessionId: 's1', producedOutput: false }, '$root')
+    expect('last_message' in out).toBe(false)
+  })
+
+  it('marks an empty turn', () => {
+    const out = toTurnEndBody(
+      { agentId: 'claude', sessionId: 's1', producedOutput: false },
+      '$root',
+    )
+    expect(out.produced_output).toBe(false)
+    expect(out.body).toBe('claude finished without output')
+  })
+
+  it('carries no msgtype — a vestigial m.notice here would collide with .m.rule.suppress_notices', () => {
+    const out = toTurnEndBody({ agentId: 'a', sessionId: 's', producedOutput: true }, '$r')
+    expect(out).not.toHaveProperty('msgtype')
+  })
+})

package/src/event-encoders.ts

@@ -91,7 +91,11 @@ type ErrorTap = Extract<TapEvent, { kind: 'error' }>
 export function toErrorBody(evt: ErrorTap, threadRoot: string): Record<string, unknown> {
   const msg = evt.message.slice(0, 250)
   const out: Record<string, unknown> = {
-    msgtype: 'm.notice',
+    // No msgtype: dev.zooid.error is not m.room.message, so the field is
+    // meaningless here — it was a vestige of copying the message-body shape.
+    // Its presence used to force careful push-rule `before` positioning
+    // (ZNC025 §10); that positioning is kept regardless, since it also
+    // protects rules for event types that never carried the field.
     body: `⚠ [${evt.code}] ${msg}`,
     code: evt.code,
     message: msg,
@@ -106,3 +110,39 @@ export function toErrorBody(evt: ErrorTap, threadRoot: string): Record<string, u
   if (recovery) out.recovery = recovery
   return out
 }
+
+export interface TurnEnd {
+  agentId: string
+  sessionId: string
+  producedOutput: boolean
+  /** The turn's final assistant message, for the push notification's preview. */
+  lastMessage?: string
+}
+
+/** Push payloads are size-capped, and a notification body is glanceable or useless. */
+const PREVIEW_MAX = 140
+
+/**
+ * Turn-boundary marker for [[ZOD076]] and push notifications. Carries no
+ * `msgtype` — a vestigial one (as `toErrorBody` used to carry) would collide
+ * with `.m.rule.suppress_notices`'s type-agnostic match and silently swallow
+ * the event before the [[ZNC025]] agent push rule ever sees it.
+ */
+export function toTurnEndBody(evt: TurnEnd, threadRoot: string): Record<string, unknown> {
+  const preview = evt.lastMessage?.trim().replace(/\s+/g, ' ')
+  return {
+    // `body` stays the turn-boundary summary: it is what a generic Matrix
+    // client renders for this event, and the prose is already its own message
+    // in the timeline. The preview below exists only for the push, which
+    // cannot see that message — agent prose is `m.notice`, deliberately
+    // silenced by `.m.rule.suppress_notices` so a chatty turn doesn't fire one
+    // push per chunk ([[ZNC025]] §10). Without it the only notification the
+    // user gets says an agent finished and nothing about what it said.
+    body: evt.producedOutput ? `${evt.agentId} finished` : `${evt.agentId} finished without output`,
+    ...(preview ? { last_message: preview.slice(0, PREVIEW_MAX) } : {}),
+    agent_id: evt.agentId,
+    session_id: evt.sessionId,
+    produced_output: evt.producedOutput,
+    'm.relates_to': { rel_type: 'm.thread', event_id: threadRoot },
+  }
+}

package/src/transport.test.ts

@@ -146,7 +146,7 @@ describe('matrix transport /transactions', () => {
         roomId: '!r:example.com',
         asUserId: '@architect:example.com',
         threadRoot: '$root',
-        content: expect.objectContaining({ msgtype: 'm.text', body: 'hello back' }),
+        content: expect.objectContaining({ msgtype: 'm.notice', body: 'hello back' }),
       }),
     )
   })
@@ -273,7 +273,7 @@ describe('matrix transport /transactions', () => {
         formatted_body?: string
       }
     }
-    expect(call.content.msgtype).toBe('m.text')
+    expect(call.content.msgtype).toBe('m.notice')
     expect(call.content.body).toBe('**bold** _italic_\n\n```ts\nconst x = 1\n```')
     expect(call.content.format).toBe('org.matrix.custom.html')
     expect(typeof call.content.formatted_body).toBe('string')
@@ -316,6 +316,37 @@ describe('matrix transport /transactions', () => {
     expect(call.content).not.toHaveProperty('format')
   })
 
+  it('sends agent prose as m.notice so .m.rule.suppress_notices silences the chunk storm server-side', async () => {
+    const { transport, agents, client } = makeTransport()
+    agents.prompt.mockImplementation(async (_name: string, p: { threadId: string }) => {
+      agents.onEvent('architect', {
+        type: 'agent_message_chunk',
+        sessionId: 'sess-' + p.threadId,
+        content: { type: 'text', text: 'hello' },
+      })
+      return { stopReason: 'end_turn' as const }
+    })
+    await postTxn(transport.app, {
+      events: [
+        {
+          type: 'm.room.message',
+          event_id: '$root',
+          room_id: '!r:example.com',
+          sender: '@alice:example.com',
+          content: {
+            msgtype: 'm.text',
+            body: 'hi',
+            'm.mentions': { user_ids: ['@architect:example.com'] },
+          },
+        },
+      ],
+    })
+    await settleTurn()
+    expect(client.sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ content: expect.objectContaining({ msgtype: 'm.notice' }) }),
+    )
+  })
+
   it('emits dev.zooid.approval_request when an approval is registered', async () => {
     const { transport, approvals, client } = makeTransport()
     await postTxn(transport.app, {
@@ -375,6 +406,95 @@ describe('matrix transport /transactions', () => {
   })
 })
 
+describe('dev.zooid.turn.end', () => {
+  function topLevelMention() {
+    return {
+      type: 'm.room.message',
+      event_id: '$root',
+      room_id: '!r:example.com',
+      sender: '@alice:example.com',
+      content: {
+        msgtype: 'm.text',
+        body: 'hi',
+        'm.mentions': { user_ids: ['@architect:example.com'] },
+      },
+    }
+  }
+
+  it('is sent once per turn, after the final flush has settled', async () => {
+    const { transport, agents, client } = makeTransport()
+    agents.prompt.mockImplementation(async (_name: string, p: { threadId: string }) => {
+      agents.onEvent('architect', {
+        type: 'agent_message_chunk',
+        sessionId: 'sess-' + p.threadId,
+        content: { type: 'text', text: 'hello back' },
+      })
+      return { stopReason: 'end_turn' as const }
+    })
+    await postTxn(transport.app, { events: [topLevelMention()] })
+    await settleTurn()
+
+    const sendMessageOrder = client.sendMessage.mock.invocationCallOrder[0]!
+    const turnEndCall = client.sendCustomEvent.mock.calls.find(
+      (c) => (c[0] as { eventType: string }).eventType === 'dev.zooid.turn.end',
+    )
+    expect(turnEndCall).toBeDefined()
+    const turnEndIdx = client.sendCustomEvent.mock.calls.indexOf(turnEndCall!)
+    const turnEndOrder = client.sendCustomEvent.mock.invocationCallOrder[turnEndIdx]!
+    // Ordering matters: a turn.end that lands before the prose would notify
+    // the user to look at a room that has nothing in it yet.
+    expect(turnEndOrder).toBeGreaterThan(sendMessageOrder)
+    expect(turnEndCall![0]).toMatchObject({
+      roomId: '!r:example.com',
+      asUserId: '@architect:example.com',
+      content: expect.objectContaining({ produced_output: true }),
+    })
+  })
+
+  it('reports produced_output: false for a silent turn', async () => {
+    const { transport, agents, client } = makeTransport()
+    // The agent emits no chunks at all — this is exactly ZOD076's case.
+    agents.prompt.mockImplementation(async () => ({ stopReason: 'end_turn' as const }))
+    await postTxn(transport.app, { events: [topLevelMention()] })
+    await settleTurn()
+
+    const turnEndCall = client.sendCustomEvent.mock.calls.find(
+      (c) => (c[0] as { eventType: string }).eventType === 'dev.zooid.turn.end',
+    )
+    expect(turnEndCall![0]).toMatchObject({
+      content: expect.objectContaining({ produced_output: false }),
+    })
+  })
+
+  it('is still sent when the turn throws, so the room never hangs on a spinner', async () => {
+    const { transport, agents, client } = makeTransport()
+    agents.prompt.mockImplementation(async () => {
+      throw new Error('boom')
+    })
+    await postTxn(transport.app, { events: [topLevelMention()] })
+    await settleTurn()
+
+    const turnEndCall = client.sendCustomEvent.mock.calls.find(
+      (c) => (c[0] as { eventType: string }).eventType === 'dev.zooid.turn.end',
+    )
+    expect(turnEndCall).toBeDefined()
+  })
+
+  it('threads to the turn root', async () => {
+    const { transport, agents, client } = makeTransport()
+    agents.prompt.mockImplementation(async () => ({ stopReason: 'end_turn' as const }))
+    await postTxn(transport.app, { events: [topLevelMention()] })
+    await settleTurn()
+
+    const turnEndCall = client.sendCustomEvent.mock.calls.find(
+      (c) => (c[0] as { eventType: string }).eventType === 'dev.zooid.turn.end',
+    )
+    expect(
+      (turnEndCall![0] as { content: { 'm.relates_to': unknown } }).content['m.relates_to'],
+    ).toEqual({ rel_type: 'm.thread', event_id: '$root' })
+  })
+})
+
 describe('thread implicit triggers', () => {
   it('triggers the most-recent-posting agent for a bare reply in a thread', async () => {
     const { transport, agents } = makeTransport()

package/src/transport.ts

@@ -7,7 +7,14 @@ import { BotPool } from './bot-pool.js'
 import { route, isMediaMsgtype, type AgentBinding, type ThreadState } from './router.js'
 import { sessionKeyFor, composeHandoffKey } from './session-keys.js'
 import { stripMention, extractMentions } from './mentions.js'
-import { toToolCallBody, toUpdateBody, toPlanBody, toAvailableCommandsBody, toErrorBody } from './event-encoders.js'
+import {
+  toToolCallBody,
+  toUpdateBody,
+  toPlanBody,
+  toAvailableCommandsBody,
+  toErrorBody,
+  toTurnEndBody,
+} from './event-encoders.js'
 import { classify } from '@zooid/acp-client'
 import { toMatrixHtml } from './markdown-to-matrix-html.js'
 import {
@@ -288,7 +295,11 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     text: string,
   ): { msgtype: string; body: string; [k: string]: unknown } => {
     const content: { msgtype: string; body: string; [k: string]: unknown } = {
-      msgtype: 'm.text',
+      // m.notice, not m.text: .m.rule.suppress_notices silences the
+      // chunk-storm of agent prose server-side (ZNC025 §10) instead of every
+      // client having to filter it. dev.zooid.error carries the same tweak
+      // for the same reason.
+      msgtype: 'm.notice',
       body: text,
     }
     const html = toMatrixHtml(text)
@@ -312,11 +323,17 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
   // same turn. The buffer is cleared synchronously (before the first await),
   // so a chunk for the *next* message that arrives during the send starts
   // fresh. Returns true when a message was enqueued.
+  const lastFlushed = new Map<string, string>()
+
   const flushBuffer = (sessionId: string): boolean => {
     const ctx = sessions.get(sessionId)
     const text = buffers.get(sessionId) ?? ''
     if (!ctx || text.length === 0) return false
     buffers.set(sessionId, '')
+    // Kept for turn.end's push preview: the prose goes out as `m.notice` and
+    // is deliberately silenced server-side, so turn.end is the only event that
+    // can tell the user what the agent actually said.
+    lastFlushed.set(sessionId, text)
     flushedCounts.set(sessionId, (flushedCounts.get(sessionId) ?? 0) + 1)
     const content = buildTextContent(text)
     const tail = (sendQueue.get(sessionId) ?? Promise.resolve()).then(async () => {
@@ -900,21 +917,39 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       // Flush the final assistant message — the one with no following messageId
       // change or out-of-band event to have triggered an earlier flush.
       flushBuffer(sessionId)
+    } finally {
+      clearInterval(refresh)
+      await safeTyping(false)
+      await safePresence('online')
       // Wait for every queued send (mid-turn flushes, tool/plan events, final
-      // flush) to settle before tearing the session down.
+      // flush) to settle before announcing the turn's end — and run this even
+      // when the turn above threw, so the room never hangs on a spinner.
       await (sendQueue.get(sessionId) ?? Promise.resolve())
-      if ((flushedCounts.get(sessionId) ?? 0) === 0) {
+      const producedOutput = (flushedCounts.get(sessionId) ?? 0) > 0
+      if (!producedOutput) {
         console.warn(
           `[matrix:${agent.name}] turn finished with empty buffer (session=${sessionId}); nothing sent to ${evt.room_id}`,
         )
       }
-    } finally {
-      clearInterval(refresh)
-      await safeTyping(false)
-      await safePresence('online')
+      // Turn boundary for [[ZOD076]] and push notifications. Sent after the
+      // send queue drains so it lands *after* the prose it announces — a
+      // turn.end arriving first would notify the user to look at a room that
+      // has nothing in it yet.
+      await client
+        .sendCustomEvent({
+          roomId: evt.room_id,
+          asUserId: agent.userId,
+          eventType: 'dev.zooid.turn.end',
+          content: toTurnEndBody(
+            { agentId: agent.name, sessionId, producedOutput, lastMessage: lastFlushed.get(sessionId) },
+            threadRoot,
+          ),
+        })
+        .catch((e) => console.warn(`[matrix:${agent.name}] turn.end send failed:`, e))
       buffers.delete(sessionId)
       bufferMessageIds.delete(sessionId)
       flushedCounts.delete(sessionId)
+      lastFlushed.delete(sessionId)
       sendQueue.delete(sessionId)
     }
   }