@zooid/transport-matrix 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zooid/transport-matrix",
-  "version": "0.13.0",
+  "version": "0.14.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.13.0",
-    "@zooid/core": "^0.13.0"
+    "@zooid/acp-client": "^0.14.0",
+    "@zooid/core": "^0.14.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.13.0",

package/src/context-provider.test.ts

@@ -155,7 +155,7 @@ describe('MatrixContextProvider', () => {
     ])
   })
 
-  it('getChannelInfo returns the room name and transport: matrix', async () => {
+  it('getRoomInfo returns the room name and transport: matrix', async () => {
     const client = fakeClient({
       fetchRoomName: vi.fn().mockResolvedValue('engineering'),
     } as unknown as Partial<MatrixClient>)
@@ -164,10 +164,67 @@ describe('MatrixContextProvider', () => {
       asUserId: '@_zooid:hs',
       agentBots: new Map(),
     })
-    const info = await provider.getChannelInfo('!room:hs')
+    const info = await provider.getRoomInfo('!room:hs')
     expect(info).toEqual({ id: '!room:hs', name: 'engineering', transport: 'matrix' })
   })
 
+  it('getRooms maps this agent\'s own room bindings to RoomInfo, fetching each name', async () => {
+    const fetchRoomName = vi.fn().mockResolvedValueOnce('general').mockResolvedValueOnce('dev')
+    const client = fakeClient({ fetchRoomName } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@architect:hs',
+      agentBots: new Map(),
+      rooms: [{ alias: '!a:hs' }, { alias: '!b:hs' }],
+    })
+    const rooms = await provider.getRooms()
+    expect(rooms).toEqual([
+      { id: '!a:hs', name: 'general', transport: 'matrix' },
+      { id: '!b:hs', name: 'dev', transport: 'matrix' },
+    ])
+    expect(fetchRoomName).toHaveBeenCalledWith('!a:hs', '@architect:hs')
+  })
+
+  it('getRooms returns an empty list when the provider has no room bindings', async () => {
+    const provider = new MatrixContextProvider({
+      client: fakeClient(),
+      asUserId: '@architect:hs',
+      agentBots: new Map(),
+    })
+    expect(await provider.getRooms()).toEqual([])
+  })
+
+  it('sendMessage posts as this agent into a bound room, echoing thread_id when replying in-thread', async () => {
+    const sendMessage = vi.fn().mockResolvedValue({ event_id: '$sent' })
+    const client = fakeClient({ sendMessage } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@architect:hs',
+      agentBots: new Map(),
+      rooms: [{ alias: '!a:hs' }],
+    })
+    const result = await provider.sendMessage({ room: '!a:hs', thread_id: '$root', text: 'noted' })
+    expect(result).toEqual({ event_id: '$sent', thread_id: '$root' })
+    expect(sendMessage).toHaveBeenCalledWith({
+      roomId: '!a:hs',
+      asUserId: '@architect:hs',
+      content: { msgtype: 'm.notice', body: 'noted' },
+      threadRoot: '$root',
+    })
+  })
+
+  it('sendMessage refuses a room this agent is not bound to', async () => {
+    const provider = new MatrixContextProvider({
+      client: fakeClient(),
+      asUserId: '@architect:hs',
+      agentBots: new Map(),
+      rooms: [{ alias: '!a:hs' }],
+    })
+    await expect(provider.sendMessage({ room: '!elsewhere:hs', text: 'hi' })).rejects.toThrow(
+      /not_in_room/,
+    )
+  })
+
   it('getRecentThreads returns top-level entries newest-first with bundled thread metadata, skipping thread replies', async () => {
     const client = fakeClient({
       fetchRoomMessages: vi.fn().mockResolvedValue({
@@ -311,7 +368,7 @@ describe('MatrixContextProvider', () => {
       asUserId: '@_zooid:hs',
       agentBots: new Map(),
     })
-    const info = await provider.getChannelInfo('!room:hs')
+    const info = await provider.getRoomInfo('!room:hs')
     expect(info.name).toBe('!room:hs')
   })
 
@@ -433,7 +490,7 @@ describe('MatrixContextProvider — reads are impersonated as the agent', () =>
     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')
+    await p.getRoomInfo('!room:hs')
 
     expect(fetchRoomMessages.mock.calls.every(([a]) => a.asUserId === AGENT)).toBe(true)
     expect(fetchThreadRelations).toHaveBeenCalledWith(expect.objectContaining({ asUserId: AGENT }))

package/src/context-provider.ts

@@ -3,12 +3,15 @@ import type {
   HistoryOptions,
   HistoryPage,
   Member,
-  ChannelInfo,
+  RoomInfo,
+  SendMessageInput,
+  SendMessageResult,
   Message,
   ThreadOverview,
   ThreadOverviewPage,
 } from '@zooid/core'
 import type { MatrixClient } from './matrix-client.js'
+import type { RoomBinding } from '@zooid/core'
 
 interface MatrixMessageEvent {
   event_id: string
@@ -47,6 +50,15 @@ export interface MatrixContextProviderOpts {
   asUserId: string
   /** Map of Matrix user IDs → agent names, for is_agent / agent_name flags. */
   agentBots: Map<string, string>
+  /**
+   * This agent's own room bindings — the live array `BotPool.bootstrap`
+   * rewrites `.alias` on in place, so reads through this field after
+   * bootstrap see canonical room IDs. Backs `getRooms()` and the
+   * `sendMessage()` authorization check. Absent/empty = no rooms known
+   * (context providers built before this field existed, or in tests that
+   * don't exercise either method).
+   */
+  rooms?: RoomBinding[]
 }
 
 export class MatrixContextProvider implements TransportContextProvider {
@@ -213,7 +225,7 @@ export class MatrixContextProvider implements TransportContextProvider {
     })
   }
 
-  async getChannelInfo(channelId: string): Promise<ChannelInfo> {
+  async getRoomInfo(channelId: string): Promise<RoomInfo> {
     const name = await this.opts.client.fetchRoomName(channelId, this.opts.asUserId)
     return {
       id: channelId,
@@ -221,4 +233,30 @@ export class MatrixContextProvider implements TransportContextProvider {
       transport: 'matrix',
     }
   }
+
+  async getRooms(): Promise<RoomInfo[]> {
+    const rooms = this.opts.rooms ?? []
+    return Promise.all(
+      rooms.map(async (r) => {
+        const name = await this.opts.client.fetchRoomName(r.alias, this.opts.asUserId)
+        return { id: r.alias, name: name ?? r.alias, transport: 'matrix' as const }
+      }),
+    )
+  }
+
+  async sendMessage(input: SendMessageInput): Promise<SendMessageResult> {
+    const rooms = this.opts.rooms ?? []
+    if (!rooms.some((r) => r.alias === input.room)) {
+      throw new Error(`not_in_room: this agent is not a member of ${input.room}`)
+    }
+    const { event_id } = await this.opts.client.sendMessage({
+      roomId: input.room,
+      asUserId: this.opts.asUserId,
+      // m.notice, not m.text: agent prose sends as m.notice so
+      // .m.rule.suppress_notices silences it server-side (ZNC025 §10).
+      content: { msgtype: 'm.notice', body: input.text },
+      ...(input.thread_id ? { threadRoot: input.thread_id } : {}),
+    })
+    return { event_id, ...(input.thread_id ? { thread_id: input.thread_id } : {}) }
+  }
 }

package/src/index.ts

@@ -1,5 +1,9 @@
 export { MatrixClient } from './matrix-client.js'
-export type { MatrixClientOptions, SendMessageInput, SendCustomEventInput } from './matrix-client.js'
+export type {
+  MatrixClientOptions,
+  SendMessageInput,
+  SendCustomEventInput,
+} from './matrix-client.js'
 export { MatrixContextProvider } from './context-provider.js'
 export type { MatrixContextProviderOpts } from './context-provider.js'
 export { renderRegistration } from './registration.js'
@@ -22,7 +26,11 @@ export { createMatrixTransport } from './transport.js'
 export type { CreateMatrixTransportOptions, MediaClientLike } from './transport.js'
 export { SyncLoop } from './sync-loop.js'
 export type { SyncLoopOptions, SyncResponse, SyncClient } from './sync-loop.js'
-export { ensureDefaultChannel, ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
+export {
+  ensureDefaultChannel,
+  ensureWorkforceSpace,
+  serverNameFromMxid,
+} from './space-provisioner.js'
 export type { EnsureDefaultChannelOpts, EnsureSpaceOpts } from './space-provisioner.js'
 export {
   buildWorkforceRoster,
@@ -35,9 +43,21 @@ export type {
   PublisherHandle,
   StartOpts as StartWorkforcePublisherOpts,
 } from './workforce-publisher.js'
-export { MediaClient, parseMxcUri, MAX_INLINE_IMAGE_BYTES, INLINE_IMAGE_MIMES, MAX_DOWNLOAD_BYTES } from './media-client.js'
+export {
+  MediaClient,
+  parseMxcUri,
+  MAX_INLINE_IMAGE_BYTES,
+  INLINE_IMAGE_MIMES,
+  MAX_DOWNLOAD_BYTES,
+} from './media-client.js'
 export type { MediaClientOptions } from './media-client.js'
 export { PendingMediaStore, MAX_MEDIA_PER_TURN } from './pending-media.js'
 export type { PendingMediaItem } from './pending-media.js'
 export { writeAttachment } from './attachments.js'
 export type { WriteAttachmentInput } from './attachments.js'
+export { TaskRegistry, MAX_OPEN_TASKS_PER_ROOM } from './task-registry.js'
+export type { TaskRecord, TaskPhase, PersistedTask, TaskJournal } from './task-registry.js'
+export { InvocationRegistry } from './invocation-registry.js'
+export { evaluateCompletion } from './task-completion.js'
+export type { CompletionInputs, CompletionDecision, StopReason } from './task-completion.js'
+export { checkDelegable, buildAssignmentContent, renderCompletionPrompt, renderInvocationReturn } from './task-dispatch.js'

package/src/invocation-registry.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { InvocationRegistry } from './invocation-registry.js'
+
+describe('InvocationRegistry', () => {
+  it('tracks a handoff before its Matrix event exists and resolves exactly once', () => {
+    const registry = new InvocationRegistry({ newId: () => 'i1' })
+    const invocation = registry.open({ taskId: 't1', callerAgent: 'a', callerSessionKey: '$root', calleeAgent: 'b' })
+    expect(registry.outstandingFor('$root')).toHaveLength(1)
+    registry.attachCallEvent(invocation.invocationId, '$call', '$root|$call')
+    expect(registry.forCalleeSession('$root|$call')).toBe(invocation)
+    expect(registry.resolve(invocation.invocationId)).toBe(invocation)
+    expect(registry.resolve(invocation.invocationId)).toBeUndefined()
+  })
+  it('detects an outstanding ancestor and cancels late returns', () => {
+    const registry = new InvocationRegistry({ newId: () => 'i1' })
+    const invocation = registry.open({ taskId: 't1', callerAgent: 'a', callerSessionKey: '$root', calleeAgent: 'b' })
+    registry.attachCallEvent('i1', '$call', '$root|$call')
+    expect(registry.isOutstandingAncestor('$root|$call', 'a')).toBe(true)
+    registry.cancelForTask('t1')
+    expect(registry.resolve('i1')).toBeUndefined()
+  })
+})

package/src/invocation-registry.ts

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto'
+import type { InvocationRecord } from '@zooid/core'
+
+export class InvocationRegistry {
+  private readonly records = new Map<string, InvocationRecord>()
+  private readonly byCallee = new Map<string, string>()
+  private readonly byEvent = new Map<string, string>()
+  constructor(private readonly opts: { newId?: () => string } = {}) {}
+  open(input: Omit<InvocationRecord, 'invocationId' | 'state'>): InvocationRecord {
+    const record = { invocationId: this.opts.newId?.() ?? randomUUID(), state: 'outstanding' as const, ...input }
+    this.records.set(record.invocationId, record)
+    return record
+  }
+  attachCallEvent(id: string, eventId: string, sessionKey: string) {
+    const r = this.records.get(id); if (!r) return
+    r.callEventId = eventId; r.calleeSessionKey = sessionKey
+    this.byEvent.set(eventId, id); this.byCallee.set(sessionKey, id)
+  }
+  get(id: string) { return this.records.get(id) }
+  byCallEvent(eventId: string) { const id = this.byEvent.get(eventId); return id ? this.records.get(id) : undefined }
+  forCalleeSession(session: string) { const id = this.byCallee.get(session); return id ? this.records.get(id) : undefined }
+  outstandingFor(session: string) { return [...this.records.values()].filter(x => x.state === 'outstanding' && x.callerSessionKey === session) }
+  outstandingForTask(taskId: string) { return [...this.records.values()].filter(x => x.state === 'outstanding' && x.taskId === taskId) }
+  resolve(id: string) { const r = this.records.get(id); if (!r || r.state !== 'outstanding') return; r.state = 'returned'; return r }
+  cancelForTask(taskId: string) { const records = this.outstandingForTask(taskId); for (const r of records) r.state = 'cancelled'; return records }
+  ancestorAgents(session: string) {
+    const agents: string[] = [], seen = new Set([session]); let cursor = session
+    for (;;) { const r = this.forCalleeSession(cursor); if (!r || r.state !== 'outstanding') break; agents.push(r.callerAgent); if (seen.has(r.callerSessionKey)) break; seen.add(r.callerSessionKey); cursor = r.callerSessionKey }
+    return agents
+  }
+  isOutstandingAncestor(session: string, agent: string) { return this.ancestorAgents(session).includes(agent) }
+}

package/src/matrix-client.ts

@@ -11,6 +11,7 @@ export interface SendMessageInput {
   asUserId: string
   content: { msgtype: string; body: string; [k: string]: unknown }
   threadRoot?: string
+  txnId?: string
 }
 
 export interface SendCustomEventInput {
@@ -18,6 +19,7 @@ export interface SendCustomEventInput {
   asUserId: string
   eventType: string
   content: Record<string, unknown>
+  txnId?: string
 }
 
 export interface SetTypingInput {
@@ -51,7 +53,10 @@ export class MatrixClient {
     const r = await this.fetch(`${this.homeserver}/_matrix/client/v3/register`, {
       method: 'POST',
       headers: { Authorization: `Bearer ${this.asToken}` },
-      body: JSON.stringify({ type: 'm.login.application_service', username: localpart }),
+      body: JSON.stringify({
+        type: 'm.login.application_service',
+        username: localpart,
+      }),
     })
     if (r.status === 200) return (await r.json()) as { user_id: string; device_id: string }
     if (r.status === 400) {
@@ -143,10 +148,7 @@ export class MatrixClient {
     return j.room_id
   }
 
-  async createRoomRaw(opts: {
-    asUserId: string
-    body: Record<string, unknown>
-  }): Promise<string> {
+  async createRoomRaw(opts: { asUserId: string; body: Record<string, unknown> }): Promise<string> {
     const url = `${this.homeserver}/_matrix/client/v3/createRoom?user_id=${encodeURIComponent(opts.asUserId)}`
     const r = await this.fetch(url, {
       method: 'POST',
@@ -190,11 +192,7 @@ export class MatrixClient {
    * already invited" responses idempotently so bootstrap can run on a
    * fresh AND a populated homeserver without branching.
    */
-  async invite(opts: {
-    roomId: string
-    asUserId: string
-    targetUserId: string
-  }): Promise<void> {
+  async invite(opts: { roomId: string; asUserId: string; targetUserId: string }): Promise<void> {
     const url =
       `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(opts.roomId)}/invite` +
       `?user_id=${encodeURIComponent(opts.asUserId)}`
@@ -229,11 +227,7 @@ export class MatrixClient {
     throw new Error(`invite(${opts.targetUserId}) failed: ${r.status}`)
   }
 
-  async leaveRoom(
-    roomId: string,
-    asUserId: string,
-    opts?: { reason?: string },
-  ): Promise<void> {
+  async leaveRoom(roomId: string, asUserId: string, opts?: { reason?: string }): Promise<void> {
     const url =
       `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/leave` +
       `?user_id=${encodeURIComponent(asUserId)}`
@@ -263,13 +257,16 @@ export class MatrixClient {
   async sendMessage(input: SendMessageInput): Promise<{ event_id: string }> {
     const content: Record<string, unknown> = { ...input.content }
     if (input.threadRoot) {
-      content['m.relates_to'] = { rel_type: 'm.thread', event_id: input.threadRoot }
+      content['m.relates_to'] = {
+        rel_type: 'm.thread',
+        event_id: input.threadRoot,
+      }
     }
-    return this.sendEvent(input.roomId, input.asUserId, 'm.room.message', content)
+    return this.sendEvent(input.roomId, input.asUserId, 'm.room.message', content, input.txnId)
   }
 
   async sendCustomEvent(input: SendCustomEventInput): Promise<{ event_id: string }> {
-    return this.sendEvent(input.roomId, input.asUserId, input.eventType, input.content)
+    return this.sendEvent(input.roomId, input.asUserId, input.eventType, input.content, input.txnId)
   }
 
   async setTyping(input: SetTypingInput): Promise<void> {
@@ -356,9 +353,14 @@ export class MatrixClient {
       user_id: opts.asUserId,
     })
     if (opts.from) params.set('from', opts.from)
+    // The 3-segment relations endpoint (rel_type + event_type) scopes both the
+    // returned chunk AND the next_batch cursor to m.room.message server-side —
+    // without it we'd paginate over every m.thread relation (edits, reactions,
+    // redactions) and toMessage()'s client-side filtering would desync from
+    // has_more/next_before (zooid-ai/zooid#21).
     const url =
       `${this.homeserver}/_matrix/client/v1/rooms/${encodeURIComponent(opts.roomId)}` +
-      `/relations/${encodeURIComponent(opts.rootEventId)}/m.thread?${params.toString()}`
+      `/relations/${encodeURIComponent(opts.rootEventId)}/m.thread/m.room.message?${params.toString()}`
     const r = await this.fetch(url, {
       method: 'GET',
       headers: { Authorization: `Bearer ${this.asToken}` },
@@ -409,7 +411,10 @@ export class MatrixClient {
       headers: { Authorization: `Bearer ${this.asToken}` },
     })
     if (!r.ok) throw new Error(`fetchRoomMessages(${opts.roomId}) failed: ${r.status}`)
-    return (await r.json()) as { chunk: Array<Record<string, unknown>>; end?: string }
+    return (await r.json()) as {
+      chunk: Array<Record<string, unknown>>
+      end?: string
+    }
   }
 
   async getJoinedMembers(
@@ -424,19 +429,24 @@ export class MatrixClient {
       headers: { Authorization: `Bearer ${this.asToken}` },
     })
     if (!r.ok) throw new Error(`getJoinedMembers(${roomId}) failed: ${r.status}`)
-    return (await r.json()) as { joined: Record<string, { display_name?: string }> }
+    return (await r.json()) as {
+      joined: Record<string, { display_name?: string }>
+    }
   }
 
-  async sync(opts: {
-    asUserId: string
-    since?: string | null
-    timeoutMs?: number
-  }): Promise<{
+  async sync(opts: { asUserId: string; since?: string | null; timeoutMs?: number }): Promise<{
     next_batch: string
     rooms: {
-      join: Record<string, {
-        timeline: { events: Record<string, unknown>[]; prev_batch?: string; limited?: boolean }
-      }>
+      join: Record<
+        string,
+        {
+          timeline: {
+            events: Record<string, unknown>[]
+            prev_batch?: string
+            limited?: boolean
+          }
+        }
+      >
     }
   }> {
     const params = new URLSearchParams({
@@ -452,9 +462,16 @@ export class MatrixClient {
     return r.json() as Promise<{
       next_batch: string
       rooms: {
-        join: Record<string, {
-          timeline: { events: Record<string, unknown>[]; prev_batch?: string; limited?: boolean }
-        }>
+        join: Record<
+          string,
+          {
+            timeline: {
+              events: Record<string, unknown>[]
+              prev_batch?: string
+              limited?: boolean
+            }
+          }
+        >
       }
     }>
   }
@@ -478,8 +495,9 @@ export class MatrixClient {
     asUserId: string,
     eventType: string,
     content: Record<string, unknown>,
+    txnId?: string,
   ): Promise<{ event_id: string }> {
-    const txn = randomUUID()
+    const txn = txnId ?? randomUUID()
     const url =
       `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}` +
       `/send/${eventType}/${txn}?user_id=${encodeURIComponent(asUserId)}`
@@ -488,7 +506,13 @@ export class MatrixClient {
       headers: { Authorization: `Bearer ${this.asToken}` },
       body: JSON.stringify(content),
     })
-    if (!r.ok) throw new Error(`sendEvent(${eventType}) failed: ${r.status}`)
+    if (!r.ok) {
+      const err = new Error(`sendEvent(${eventType}) failed: ${r.status}`) as Error & {
+        status?: number
+      }
+      err.status = r.status
+      throw err
+    }
     return (await r.json()) as { event_id: string }
   }
 }

package/src/router.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from 'vitest'
-import { route, isMediaMsgtype, type AgentBinding, type ThreadState } from './router.js'
+import {
+  route,
+  isMediaMsgtype,
+  wouldCycleCallers,
+  type AgentBinding,
+  type ThreadState,
+} from './router.js'
 
 const agents: AgentBinding[] = [
   {
@@ -17,7 +23,12 @@ const agents: AgentBinding[] = [
 ]
 
 function msg(
-  overrides: Partial<{ room: string; sender: string; body: string; mentions: string[] }> = {},
+  overrides: Partial<{
+    room: string
+    sender: string
+    body: string
+    mentions: string[]
+  }> = {},
 ) {
   return {
     type: 'm.room.message',
@@ -55,7 +66,10 @@ describe('route', () => {
 
   it('skips events whose sender is the matched agent itself', () => {
     const matches = route(
-      msg({ sender: '@architect:example.com', mentions: ['@architect:example.com'] }),
+      msg({
+        sender: '@architect:example.com',
+        mentions: ['@architect:example.com'],
+      }),
       agents,
     )
     expect(matches).toEqual([])
@@ -71,10 +85,7 @@ describe('route', () => {
         trigger: 'mention',
       },
     ]
-    const matches = route(
-      msg({ mentions: ['@architect:example.com', '@qa:example.com'] }),
-      both,
-    )
+    const matches = route(msg({ mentions: ['@architect:example.com', '@qa:example.com'] }), both)
     expect(matches.map((m) => m.name).sort()).toEqual(['architect', 'qa'])
   })
 
@@ -89,6 +100,86 @@ describe('route', () => {
   })
 })
 
+describe('directed task routing', () => {
+  const agents: AgentBinding[] = [
+    {
+      name: 'supervisor',
+      userId: '@supervisor:hs',
+      rooms: [{ alias: '!r:hs' }],
+      trigger: 'mention',
+    },
+    {
+      name: 'worker',
+      userId: '@worker:hs',
+      rooms: [{ alias: '!r:hs' }],
+      trigger: 'mention',
+    },
+    {
+      name: 'eager',
+      userId: '@eager:hs',
+      rooms: [{ alias: '!r:hs' }],
+      trigger: 'any',
+    },
+  ]
+  const root = {
+    type: 'm.room.message',
+    room_id: '!r:hs',
+    sender: '@supervisor:hs',
+    content: {
+      msgtype: 'm.notice',
+      body: '@worker:hs task',
+      'm.mentions': { user_ids: ['@worker:hs'] },
+    },
+  }
+  it('routes a task root solely to its assignee, including self assignment', () => {
+    expect(
+      route(root, agents, new Map(), { assignee: 'worker', isRoot: true }).map((x) => x.name),
+    ).toEqual(['worker'])
+    expect(
+      route(root, agents, new Map(), {
+        assignee: 'supervisor',
+        isRoot: true,
+      }).map((x) => x.name),
+    ).toEqual(['supervisor'])
+  })
+  it('keeps trigger:any out of a task thread while allowing human steering and explicit mentions', () => {
+    const state = new Map([
+      [
+        '$task',
+        {
+          participants: ['worker'],
+          rootMentions: ['worker'],
+          callers: {},
+          handoffs: {},
+        },
+      ],
+    ])
+    const human = {
+      ...root,
+      sender: '@alice:hs',
+      content: {
+        msgtype: 'm.text',
+        body: 'continue',
+        'm.relates_to': { rel_type: 'm.thread', event_id: '$task' },
+      },
+    }
+    expect(
+      route(human, agents, state, { assignee: 'worker', isRoot: false }).map((x) => x.name),
+    ).toEqual(['worker'])
+    const mention = {
+      ...human,
+      sender: '@worker:hs',
+      content: {
+        ...human.content,
+        'm.mentions': { user_ids: ['@supervisor:hs'] },
+      },
+    }
+    expect(
+      route(mention, agents, state, { assignee: 'worker', isRoot: false }).map((x) => x.name),
+    ).toEqual(['supervisor'])
+  })
+})
+
 describe('media events', () => {
   it('classifies media msgtypes', () => {
     for (const t of ['m.image', 'm.file', 'm.video', 'm.audio']) {
@@ -103,7 +194,11 @@ describe('media events', () => {
     const monitorRoom = msg({ room: '!alerts:example.com', body: 'dog.jpg' })
     const mediaEvent = {
       ...monitorRoom,
-      content: { msgtype: 'm.image', body: 'dog.jpg', url: 'mxc://localhost/abc' },
+      content: {
+        msgtype: 'm.image',
+        body: 'dog.jpg',
+        url: 'mxc://localhost/abc',
+      },
     }
     const matches = route(mediaEvent, agents)
     expect(matches).toEqual([])
@@ -169,7 +264,10 @@ describe('directional thread continuation (agent-to-agent handoffs)', () => {
 
   it('an explicit @mention still re-engages the sub (rule 1 wins)', () => {
     const matches = route(
-      threadMsg({ sender: '@parent:example.com', mentions: ['@sub:example.com'] }),
+      threadMsg({
+        sender: '@parent:example.com',
+        mentions: ['@sub:example.com'],
+      }),
       pair,
       states({ participants: ['parent', 'sub'], callers: { sub: 'parent' } }),
     )
@@ -178,7 +276,10 @@ describe('directional thread continuation (agent-to-agent handoffs)', () => {
 
   it('dedupes: a sub reply that also @mentions its caller triggers the caller once', () => {
     const matches = route(
-      threadMsg({ sender: '@sub:example.com', mentions: ['@parent:example.com'] }),
+      threadMsg({
+        sender: '@sub:example.com',
+        mentions: ['@parent:example.com'],
+      }),
       pair,
       states({ participants: ['parent'], callers: { sub: 'parent' } }),
     )
@@ -228,6 +329,24 @@ describe('directional thread continuation (agent-to-agent handoffs)', () => {
   })
 })
 
+describe('caller graph cycle guard', () => {
+  it('rejects a reverse edge back to an existing caller', () => {
+    expect(wouldCycleCallers({ sub: 'parent' }, 'parent', 'sub')).toBe(true)
+  })
+
+  it('rejects a cycle through a deeper ancestor', () => {
+    expect(
+      wouldCycleCallers({ child: 'parent', grandchild: 'child' }, 'parent', 'grandchild'),
+    ).toBe(true)
+  })
+
+  it('allows a new downward or sibling edge', () => {
+    const callers = { child: 'parent' }
+    expect(wouldCycleCallers(callers, 'grandchild', 'child')).toBe(false)
+    expect(wouldCycleCallers(callers, 'sibling', 'parent')).toBe(false)
+  })
+})
+
 describe('fan-out: two subs called in one message ([[ZOD071]] acceptance)', () => {
   const mk = (name: string): AgentBinding => ({
     name,