zooid 0.12.0 → 0.14.0

package/src/daemon/delivery-cache.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { DeliveryCache } from './delivery-cache.js'
+
+describe('DeliveryCache', () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it('accepts an id once and rejects the replay', () => {
+    const c = new DeliveryCache(60_000)
+    expect(c.seen('abc')).toBe(false)
+    expect(c.seen('abc')).toBe(true)
+  })
+
+  it('treats ids from different triggers as distinct', () => {
+    const c = new DeliveryCache(60_000)
+    expect(c.seen('t1:abc')).toBe(false)
+    expect(c.seen('t2:abc')).toBe(false)
+  })
+
+  it('forgets an id after the TTL, so the cache cannot grow without bound', () => {
+    const c = new DeliveryCache(60_000)
+    c.seen('abc')
+    vi.advanceTimersByTime(61_000)
+    expect(c.seen('abc')).toBe(false)
+  })
+
+  it('evicts expired entries rather than retaining them forever', () => {
+    const c = new DeliveryCache(1_000)
+    for (let i = 0; i < 1000; i++) c.seen(`id-${i}`)
+    vi.advanceTimersByTime(2_000)
+    c.seen('trigger-eviction')
+    expect(c.size).toBeLessThan(10)
+  })
+})

package/src/daemon/delivery-cache.ts

@@ -0,0 +1,36 @@
+/**
+ * TTL-bounded replay defence for webhook delivery ids. GitHub sends no
+ * timestamp, so freshness-window rejection (used for Stripe/Slack in
+ * `webhook-verify.ts`) is not available — dedupe on delivery id instead.
+ * Keys are namespaced by trigger name (e.g. `t1:abc`) so two triggers never
+ * collide on the same upstream id.
+ */
+export class DeliveryCache {
+  private readonly ttlMs: number
+  private readonly expiryById = new Map<string, number>()
+
+  constructor(ttlMs: number) {
+    this.ttlMs = ttlMs
+  }
+
+  get size(): number {
+    return this.expiryById.size
+  }
+
+  /** Returns true if `id` was already seen (and still within its TTL). */
+  seen(id: string): boolean {
+    this.evictExpired()
+    const now = Date.now()
+    const expiry = this.expiryById.get(id)
+    if (expiry !== undefined && expiry > now) return true
+    this.expiryById.set(id, now + this.ttlMs)
+    return false
+  }
+
+  private evictExpired(): void {
+    const now = Date.now()
+    for (const [id, expiry] of this.expiryById) {
+      if (expiry <= now) this.expiryById.delete(id)
+    }
+  }
+}

package/src/daemon/load-custom-verifiers.ts

@@ -0,0 +1,43 @@
+import { pathToFileURL } from 'node:url'
+import type { TriggerConfig } from '@zooid/core'
+import type { CustomVerifier } from './webhook-verify.js'
+
+/**
+ * Import the `verify:` module of every `provider: custom` trigger, keyed by
+ * trigger name.
+ *
+ * Loaded once at daemon start rather than per delivery: a bad path or a
+ * module that exports the wrong thing is a configuration error, and it
+ * should surface when the operator starts the daemon, not silently as a 401
+ * the first time the service fires. Config has already resolved the path to
+ * an absolute one against the zooid.yaml directory.
+ */
+export async function loadCustomVerifiers(
+  triggers: Record<string, TriggerConfig>,
+): Promise<Record<string, CustomVerifier>> {
+  const out: Record<string, CustomVerifier> = {}
+  for (const [name, trigger] of Object.entries(triggers)) {
+    const path = trigger.webhook?.provider === 'custom' ? trigger.webhook.verify : undefined
+    if (!path) continue
+
+    let mod: Record<string, unknown>
+    try {
+      mod = (await import(pathToFileURL(path).href)) as Record<string, unknown>
+    } catch (err) {
+      throw new Error(
+        `triggers.${name}.webhook.verify: cannot load ${path} — ${(err as Error).message}`,
+      )
+    }
+    // `export default` is the documented shape; a named `verify` export is
+    // accepted so a module can hold more than one provider's verifier.
+    const fn = mod.default ?? mod.verify
+    if (typeof fn !== 'function') {
+      throw new Error(
+        `triggers.${name}.webhook.verify: ${path} must export a function as \`default\` ` +
+          `(or as \`verify\`), got ${typeof fn}`,
+      )
+    }
+    out[name] = fn as CustomVerifier
+  }
+  return out
+}

package/src/daemon/start-daemon.ts

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs'
-import { mkdir, unlink } from 'node:fs/promises'
+import { mkdir } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
 import type { AddressInfo } from 'node:net'
@@ -26,15 +26,19 @@ import {
   type PublisherHandle,
   type SyncLoop,
 } from '@zooid/transport-matrix'
-import {
-  SpawnRegistry,
-  startDaemonSocketServer,
-  type DaemonSocketHandle,
-} from '@zooid/context-mcp'
-import { buildAcpRegistry } from '../build-registry.js'
+import { SpawnRegistry, startAgentSocketServers, type AgentSocketsHandle } from '@zooid/context-mcp'
+import { buildAcpRegistry, contextEligibleAgents } from '../build-registry.js'
+import { installPiExtension, resolvePiAgentDir } from '../pi-extension-install.js'
+import { resolvePiExtensionBundle } from '@zooid/pi-extension'
 import { prepullImages } from '../prepull-images.js'
+import { mountPushGateway } from '../push-gateway/index.js'
 import { makeSyncCursorStore } from './sync-cursors.js'
+import { makeTaskJournal } from './task-journal.js'
 import { shouldBindHttpListener } from './pull-wiring.js'
+import { startTriggerScheduler, validateCron } from './trigger-scheduler.js'
+import { mountWebhookRoutes, WEBHOOK_ROUTE_PREFIX } from './webhook-routes.js'
+import { loadCustomVerifiers } from './load-custom-verifiers.js'
+import { joinTriggerRooms } from './trigger-rooms.js'
 
 export interface StartDaemonOpts {
   configPath?: string
@@ -79,6 +83,8 @@ export interface StartDaemonOpts {
 export interface DaemonHandle {
   port: number
   agentNames: string[]
+  /** VAPID public key for web push, when the gateway bound (appservice mode with a data dir). */
+  vapidPublicKey?: string
   stop(): Promise<void>
   whenStopped: Promise<void>
 }
@@ -100,44 +106,73 @@ function closeAsync(server: ServerType): Promise<void> {
   })
 }
 
+function localpart(userId: string): string {
+  const m = /^@([^:]+):/.exec(userId)
+  if (!m) throw new Error(`bad user id: ${userId}`)
+  return m[1]!
+}
+
 export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHandle> {
   const cwd = opts.cwd ?? process.cwd()
   const found = opts.configPath ? { path: opts.configPath } : findConfigFile(cwd)
   if (!found) throw new Error('zooid.yaml is required')
   const configDir = dirname(found.path)
-  const base = loadZooidConfig(readFileSync(found.path, 'utf8'), { configDir })
+  const base = loadZooidConfig(readFileSync(found.path, 'utf8'), { configDir, validateCron })
   const config = mergeCliFlags(base, opts.cliFlags ?? {})
 
   const approvals = new ApprovalCorrelator()
 
-  const daemonSockPath = opts.agentsDir
-    ? join(opts.agentsDir, '..', 'run', 'context.sock')
-    : join(tmpdir(), `zooid-context-${process.pid}.sock`)
-  await mkdir(dirname(daemonSockPath), { recursive: true }).catch(() => {})
+  const runDir = opts.agentsDir
+    ? join(opts.agentsDir, '..', 'run')
+    : join(tmpdir(), `zooid-context-${process.pid}`)
+  await mkdir(runDir, { recursive: true }).catch(() => {})
   const contextSpawnRegistry = new SpawnRegistry()
-  let contextSocket: DaemonSocketHandle | null = null
-  try {
-    contextSocket = await startDaemonSocketServer({
-      sockPath: daemonSockPath,
-      registry: contextSpawnRegistry,
-    })
-  } catch (err) {
-    console.warn('[context] daemon socket startup failed; zooid-context MCP disabled:', err)
-  }
+  const contextSockets: AgentSocketsHandle = await startAgentSocketServers({
+    runDir,
+    registry: contextSpawnRegistry,
+    agentNames: contextEligibleAgents(config),
+  })
 
   const dataDir = opts.agentsDir ? dirname(opts.agentsDir) : undefined
   const registry = buildAcpRegistry(config, {
     approvals,
     onTap: opts.onTap,
     agentsDir: opts.agentsDir,
-    contextSpawnRegistry: contextSocket ? contextSpawnRegistry : undefined,
-    daemonSockPath: contextSocket ? daemonSockPath : undefined,
+    contextSpawnRegistry,
+    daemonSockPaths: contextSockets.paths,
     configDir,
     dataDir,
     daemonHome: process.env.HOME,
   })
   const agentNames = Object.keys(config.agents)
 
+  const piAgents = agentNames.filter(
+    (name) => (config.agents[name].acp as { preset?: string } | undefined)?.preset === 'pi',
+  )
+  if (piAgents.length > 0) {
+    const bundlePath = resolvePiExtensionBundle()
+    // PI_CODING_AGENT_DIR is normally relative, so each agent gets its own
+    // extensions dir; an absolute value (or none) collapses them into one.
+    const installed = new Set<string>()
+    for (const name of piAgents) {
+      const { dir, scope } = resolvePiAgentDir({
+        agentWorkdir: resolve(configDir, config.agents[name].workdir),
+        daemonHome: process.env.HOME ?? '',
+        env: process.env,
+      })
+      if (installed.has(dir)) continue
+      installed.add(dir)
+      const result = installPiExtension({
+        agentDir: dir,
+        bundlePath,
+        createMissing: scope === 'project',
+      })
+      const where = result.target ? ` extension=${result.target}` : ''
+      const why = result.reason ? ` reason=${result.reason}` : ''
+      console.log(`[pi] agent=${name}${where} status=${result.status}${why}`)
+    }
+  }
+
   if (config.runtime !== 'local') {
     await prepullImages(registry, {
       engine: config.runtime === 'podman' ? 'podman' : 'docker',
@@ -148,16 +183,14 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
     })
   }
 
-  console.log(
-    `[context] socket=${daemonSockPath} ` +
-      `status=${contextSocket ? 'listening' : 'disabled'} ` +
-      `agents={${agentNames
-        .map((n) => `${n}:${registry.hasContextSpawn(n) ? 'yes' : 'no'}`)
-        .join(', ')}}`,
-  )
+  console.log(`[context] runDir=${runDir}`)
+  for (const name of agentNames) {
+    console.log(`[context] agent=${name} socket=${contextSockets.paths[name] ?? '(disabled)'}`)
+  }
 
   let server: ServerType | null = null
   let syncLoops: SyncLoop[] | undefined
+  let triggers: { stop(): Promise<void> } | undefined
   let stopped = false
   let resolveStopped!: () => void
   const whenStopped = new Promise<void>((r) => {
@@ -166,6 +199,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
 
   const matrix = findMatrixTransport(config)
   let port: number
+  let vapidPublicKey: string | undefined
 
   if (matrix) {
     const mode = matrix.transport.mode ?? 'appservice'
@@ -205,8 +239,11 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
     // `:` is the homeserver's server_name. Fall back to the homeserver URL's
     // host if the namespace shape is unexpected.
     const serverName =
-      matrix.transport.user_namespace.split(':').slice(1).join(':').replace(/\\?\)?$/, '') ||
-      new URL(matrix.transport.homeserver).hostname
+      matrix.transport.user_namespace
+        .split(':')
+        .slice(1)
+        .join(':')
+        .replace(/\\?\)?$/, '') || new URL(matrix.transport.homeserver).hostname
     const asUserId = `@${matrix.transport.sender_localpart}:${serverName}`
     // Pull mode's loadSince/saveSince are keyed by MXID; the cursor store is
     // keyed by agent name. Translate via the bindings we just built.
@@ -220,6 +257,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
       adminUserId: opts.adminUserId,
       botUserId: asUserId,
       media: mediaClient,
+      taskJournal: dataDir ? makeTaskJournal(dataDir) : undefined,
       mode,
       loadSince: (uid) => {
         const name = nameByUserId.get(uid)
@@ -230,12 +268,74 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
         if (name && cursors) cursors.saveSince(name, since)
       },
     })
+    contextSpawnRegistry.setTaskActions(transport.taskActions)
+
+    // Declared here, assigned after the listener is up. The closures below
+    // read it at call time, so they can be built before the space exists.
+    let spaceRoomId: string | undefined
+    const agentUserIds = Object.fromEntries(bindings.map((b) => [b.name, b.userId]))
+    const resolveRoom = async (r: string): Promise<string | null> =>
+      r.startsWith('!') ? r : await client.resolveAlias(r)
+    const ensureBot = async (mxid: string, roomId: string): Promise<void> => {
+      await client.registerBot(localpart(mxid)).catch(() => {})
+      // Agent rooms are created restricted to workforce-space members
+      // (BotPool.bootstrap): a trigger bot needs space membership too,
+      // or its join to the target room 403s.
+      if (spaceRoomId) {
+        await client.invite({ roomId: spaceRoomId, asUserId, targetUserId: mxid }).catch(() => {})
+        await client.joinRoom(spaceRoomId, mxid).catch(() => {})
+      }
+      await client.joinRoom(roomId, mxid)
+    }
+
     if (shouldBindHttpListener(mode)) {
       const requestedPort = matrix.transport.port ?? 9000
+      // The gateway rides the appservice listener, not webStatic: webStatic
+      // exists only under `zooid dev`, and on a deployed box Caddy serves the
+      // dist directly with the daemon out of the serving path. This is the
+      // one HTTP surface bound in both modes.
+      if (dataDir) {
+        vapidPublicKey = mountPushGateway(transport.app, {
+          dataDir,
+          subject: `https://${serverName}`,
+        }).publicKey
+      }
+      // Webhook ingress rides this same listener, alongside the push gateway.
+      // A separate port would buy no isolation — same process — and the AS
+      // transaction endpoint is already internet-reachable under [ZOD063].
+      // What matters is that each route authenticates its own callers:
+      // hs_token for transactions, HMAC over the raw body for webhooks.
+      //
+      // MUST be mounted before serve(): Hono builds its route matcher on the
+      // first request and then refuses new routes ("matcher is already
+      // built"), and the AS transaction endpoint starts taking pushes during
+      // bootstrap below.
+      const webhookTriggers = Object.entries(config.triggers).filter(([, t]) => t.webhook)
+      if (webhookTriggers.length > 0) {
+        // Imported before serving so a bad `verify:` path fails the daemon
+        // start, not the first delivery.
+        const customVerifiers = await loadCustomVerifiers(config.triggers)
+        mountWebhookRoutes(transport.app, {
+          triggers: config.triggers,
+          customVerifiers,
+          agentUserIds,
+          resolveRoom,
+          ensureBot,
+          sendMessage: (m) => client.sendMessage(m),
+        })
+        for (const [name] of webhookTriggers) {
+          console.log(`[webhook] POST ${WEBHOOK_ROUTE_PREFIX}/${name}`)
+        }
+      }
+
       // Bind 0.0.0.0 explicitly — @hono/node-server defaults to IPv6-only on
       // macOS, which Docker's NAT bridge can't reach when Tuwunel pushes AS
       // events back to host.docker.internal:<port>.
-      server = serve({ fetch: transport.app.fetch, port: requestedPort, hostname: '0.0.0.0' })
+      server = serve({
+        fetch: transport.app.fetch,
+        port: requestedPort,
+        hostname: '0.0.0.0',
+      })
       port = await listenAsync(server)
     } else {
       // Pull (client) mode runs outbound /sync loops; no inbound listener.
@@ -243,7 +343,6 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
     }
     const spaceLocalpart = matrix.transport.space ?? 'dev'
     const adminUserIds = opts.adminUserId ? [opts.adminUserId] : []
-    let spaceRoomId: string | undefined
     try {
       spaceRoomId = await ensureWorkforceSpace({
         client,
@@ -254,7 +353,9 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
         admins: adminUserIds,
         joinRule: opts.publicWorkforceSpace ? 'public' : 'invite',
       })
-      console.log(`[matrix] ensured workforce space #${spaceLocalpart}:${serverName} → ${spaceRoomId}`)
+      console.log(
+        `[matrix] ensured workforce space #${spaceLocalpart}:${serverName} → ${spaceRoomId}`,
+      )
     } catch (err) {
       console.warn('[matrix] workforce space provisioning failed:', err)
     }
@@ -267,6 +368,35 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
     // m.space.child while joining it.
     await transport.bootstrap({ spaceRoomId, asUserId, adminUserIds })
 
+    if (Object.keys(config.triggers).length > 0) {
+      // Join every trigger's rooms up front: a lazy join inside a webhook's
+      // 10s delivery window can 403 after the 202 already went out, silently
+      // losing the message.
+      await joinTriggerRooms({ triggers: config.triggers, resolveRoom, ensureBot })
+      console.log(
+        `[trigger] joined rooms for ${Object.keys(config.triggers).length} trigger(s)`,
+      )
+
+      triggers = startTriggerScheduler({
+        triggers: config.triggers,
+        agentUserIds,
+        resolveRoom,
+        ensureBot,
+        sendMessage: (m) => client.sendMessage(m),
+      })
+      const scheduled = Object.values(config.triggers).filter((t) => t.schedule).length
+      if (scheduled > 0) console.log(`[trigger] scheduled ${scheduled} trigger(s)`)
+      if (!shouldBindHttpListener(mode)) {
+        const webhooks = Object.values(config.triggers).filter((t) => t.webhook).length
+        if (webhooks > 0) {
+          console.warn(
+            `[webhook] ${webhooks} webhook trigger(s) configured, but pull mode binds no ` +
+              `inbound listener — these will never fire.`,
+          )
+        }
+      }
+    }
+
     // Pull mode: start the outbound /sync loops after bootstrap so the rooms
     // each agent syncs already exist. Loops long-poll until stop().
     syncLoops = transport.syncLoops
@@ -307,13 +437,22 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
     const token = process.env.ZOOID_TOKEN
     if (!token) throw new Error('ZOOID_TOKEN is required for http transport')
     const app = createApp({ agents: registry, approvals, token })
-    server = serve({ fetch: app.fetch, port: http.transport.port, hostname: '0.0.0.0' })
+    server = serve({
+      fetch: app.fetch,
+      port: http.transport.port,
+      hostname: '0.0.0.0',
+    })
     port = await listenAsync(server)
   }
 
   const stop = async (): Promise<void> => {
     if (stopped) return whenStopped
     stopped = true
+    try {
+      await triggers?.stop()
+    } catch {
+      // swallow
+    }
     try {
       if (syncLoops) for (const loop of syncLoops) loop.stop()
     } catch {
@@ -330,8 +469,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
       console.error('stopAll:', err)
     }
     try {
-      if (contextSocket) await contextSocket.close()
-      await unlink(daemonSockPath).catch(() => {})
+      await contextSockets.close()
     } catch {
       // swallow
     }
@@ -347,5 +485,5 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
     process.on('SIGTERM', () => handler('SIGTERM'))
   }
 
-  return { port, agentNames, stop, whenStopped }
+  return { port, agentNames, vapidPublicKey, stop, whenStopped }
 }

package/src/daemon/task-journal.test.ts

@@ -0,0 +1,19 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { makeTaskJournal } from './task-journal.js'
+
+const dirs: string[] = []
+afterEach(() => dirs.splice(0).forEach((dir) => rmSync(dir, { recursive: true, force: true })))
+const makeDir = () => { const dir = mkdtempSync(join(tmpdir(), 'zooid-task-')); dirs.push(dir); return dir }
+const row = { taskId: 't', attemptId: 't', roomId: '!r', assignee: 'a', notify: 'caller' as const, parent: { agent: 'p', threadRoot: '$p', sessionKey: '$p', generation: 0 }, phase: 'open' as const, threadRoot: '$r', runId: 'run' }
+describe('makeTaskJournal', () => {
+  it('round-trips data and tolerates corruption', () => {
+    const dir = makeDir(); const journal = makeTaskJournal(dir)
+    expect(journal.load()).toEqual([])
+    journal.save([row]); expect(journal.load()).toEqual([row])
+    writeFileSync(join(dir, 'tasks.json'), '{broken')
+    expect(journal.load()).toEqual([])
+  })
+})

package/src/daemon/task-journal.ts

@@ -0,0 +1,32 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { PersistedTask, TaskJournal } from '@zooid/transport-matrix'
+
+interface JournalFile { version: 1; tasks: PersistedTask[] }
+
+/** Durable, small task-state journal stored alongside daemon state. */
+export function makeTaskJournal(dataDir: string): TaskJournal {
+  const path = join(dataDir, 'tasks.json')
+  return {
+    load() {
+      try {
+        const value = JSON.parse(readFileSync(path, 'utf8')) as JournalFile
+        return value.version === 1 && Array.isArray(value.tasks) ? value.tasks : []
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') console.warn('[tasks] journal unavailable; starting empty:', error)
+        return []
+      }
+    },
+    save(tasks) {
+      mkdirSync(dataDir, { recursive: true })
+      const temp = `${path}.tmp-${process.pid}`
+      try {
+        writeFileSync(temp, JSON.stringify({ version: 1, tasks } satisfies JournalFile, null, 2), 'utf8')
+        renameSync(temp, path)
+      } catch (error) {
+        console.warn('[tasks] journal write failed:', error)
+        try { unlinkSync(temp) } catch {}
+      }
+    },
+  }
+}

package/src/daemon/trigger-rooms.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi } from 'vitest'
+import { joinTriggerRooms } from './trigger-rooms.js'
+import { loadZooidConfig } from '@zooid/core'
+
+const yaml = `
+runtime: local
+transports:
+  matrix:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: t
+    hs_token: h
+    user_namespace: '@.*:example.org'
+agents:
+  product:
+    acp: { preset: opencode }
+    matrix: { rooms: ["#product:example.org"] }
+triggers:
+  github:
+    webhook: { provider: github, secret: "s" }
+    as: "@hook:example.org"
+    messages:
+      - { room: "#product:example.org", mention: product, text: 'a' }
+      - { room: "#ops:example.org", mention: product, text: 'b' }
+  weekly:
+    schedule: "0 6 * * 1"
+    as: "@cron:example.org"
+    room: "#product:example.org"
+    mention: product
+    text: 'c'
+`
+
+describe('joinTriggerRooms', () => {
+  it('joins every declared room of every trigger, once per (bot, room)', async () => {
+    const ensureBot = vi.fn(async () => {})
+    await joinTriggerRooms({
+      triggers: loadZooidConfig(yaml).triggers,
+      resolveRoom: async (r: string) => r,
+      ensureBot,
+    })
+    expect(ensureBot.mock.calls.sort()).toEqual(
+      [
+        ['@cron:example.org', '#product:example.org'],
+        ['@hook:example.org', '#ops:example.org'],
+        ['@hook:example.org', '#product:example.org'],
+      ].sort(),
+    )
+  })
+
+  it('reports a room it cannot join instead of throwing, so one bad room does not stop the daemon', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    await joinTriggerRooms({
+      triggers: loadZooidConfig(yaml).triggers,
+      resolveRoom: async (r: string) => (r === '#ops:example.org' ? null : r),
+      ensureBot: async () => {},
+    })
+    expect(warn.mock.calls.flat().join(' ')).toMatch(/#ops:example\.org/)
+    warn.mockRestore()
+  })
+})

package/src/daemon/trigger-runner.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireTrigger } from './trigger-runner.js'
+import type { TriggerMessage } from '@zooid/core'
+
+const message: TriggerMessage = {
+  room: '#ops:example.org',
+  mention: 'architect',
+  text: 'Check the pinned agent CLI versions.',
+}
+
+const deps = (over: Record<string, unknown> = {}) => ({
+  name: 'image-currency',
+  as: '@cron:example.org',
+  message,
+  agentUserId: '@architect:example.org',
+  resolveRoom: vi.fn(async () => '!room:example.org'),
+  ensureBot: vi.fn(async () => {}),
+  sendMessage: vi.fn(async () => ({ event_id: '$1' })),
+  ...over,
+})
+
+describe('fireTrigger', () => {
+  it('posts text verbatim as the trigger bot user', async () => {
+    const d = deps()
+    await fireTrigger(d as never)
+    expect(d.sendMessage).toHaveBeenCalledTimes(1)
+    const call = (d.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]
+    expect(call.roomId).toBe('!room:example.org')
+    expect(call.asUserId).toBe('@cron:example.org')
+    expect(call.content.body).toBe('Check the pinned agent CLI versions.')
+    expect(call.content.msgtype).toBe('m.text')
+  })
+
+  it('sets m.mentions.user_ids structurally — never a templated @name (§Design 3)', async () => {
+    const d = deps()
+    await fireTrigger(d as never)
+    const content = (d.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0].content
+    expect(content['m.mentions']).toEqual({ user_ids: ['@architect:example.org'] })
+    expect(content.body).not.toContain('@architect')
+  })
+
+  it('posts at the top level, never into a thread — runTurn makes each firing a new root', async () => {
+    const d = deps()
+    await fireTrigger(d as never)
+    expect((d.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0].threadRoot).toBeUndefined()
+  })
+
+  it('registers and joins the bot user before posting', async () => {
+    const d = deps()
+    await fireTrigger(d as never)
+    expect(d.ensureBot).toHaveBeenCalledWith('@cron:example.org', '!room:example.org')
+    const ensure = (d.ensureBot as ReturnType<typeof vi.fn>).mock.invocationCallOrder[0]
+    const send = (d.sendMessage as ReturnType<typeof vi.fn>).mock.invocationCallOrder[0]
+    expect(ensure).toBeLessThan(send)
+  })
+
+  it('surfaces a send failure without throwing — one bad firing must not kill the scheduler', async () => {
+    const d = deps({
+      sendMessage: vi.fn(async () => {
+        throw new Error('matrix down')
+      }),
+    })
+    await expect(fireTrigger(d as never)).resolves.toBeUndefined()
+  })
+
+  it('does not post when the room cannot be resolved', async () => {
+    const d = deps({ resolveRoom: vi.fn(async () => null) })
+    await fireTrigger(d as never)
+    expect(d.sendMessage).not.toHaveBeenCalled()
+  })
+})