zooid 0.13.0 → 0.14.0

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,16 +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
@@ -103,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',
@@ -151,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) => {
@@ -209,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.
@@ -224,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)
@@ -234,6 +268,26 @@ 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
@@ -246,10 +300,42 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
           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.
@@ -257,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,
@@ -268,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)
     }
@@ -281,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
@@ -321,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 {
@@ -344,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
     }

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()
+  })
+})

package/src/daemon/trigger-runner.ts

@@ -0,0 +1,41 @@
+import type { TriggerMessage } from '@zooid/core'
+
+export interface FireTriggerDeps {
+  name: string
+  as: string
+  message: TriggerMessage
+  agentUserId: string
+  resolveRoom: (room: string) => Promise<string | null>
+  ensureBot: (asUserId: string, roomId: string) => Promise<void>
+  sendMessage: (input: {
+    roomId: string
+    asUserId: string
+    content: { msgtype: string; body: string; [k: string]: unknown }
+  }) => Promise<{ event_id: string }>
+}
+
+export async function fireTrigger(deps: FireTriggerDeps): Promise<void> {
+  const { name, as, message, agentUserId, resolveRoom, ensureBot, sendMessage } = deps
+  try {
+    const roomId = await resolveRoom(message.room)
+    if (!roomId) {
+      console.warn(`[trigger:${name}] cannot resolve room ${message.room} — skipping`)
+      return
+    }
+    await ensureBot(as, roomId)
+    await sendMessage({
+      roomId,
+      asUserId: as,
+      content: {
+        msgtype: 'm.text',
+        body: message.text,
+        // Structural mention: routes deterministically AND disarms the raw-body
+        // fallback in extractMentions, which only fires when nothing matched.
+        'm.mentions': { user_ids: [agentUserId] },
+      },
+    })
+  } catch (err) {
+    // Never throw: one bad firing must not take down the scheduler.
+    console.warn(`[trigger:${name}] failed:`, (err as Error).message)
+  }
+}

package/src/daemon/trigger-scheduler.ts

@@ -0,0 +1,55 @@
+import { Cron } from 'croner'
+import type { TriggerConfig } from '@zooid/core'
+import { fireTrigger, type FireTriggerDeps } from './trigger-runner.js'
+
+export interface StartTriggerSchedulerDeps {
+  triggers: Record<string, TriggerConfig>
+  agentUserIds: Record<string, string>
+  resolveRoom: FireTriggerDeps['resolveRoom']
+  ensureBot: FireTriggerDeps['ensureBot']
+  sendMessage: FireTriggerDeps['sendMessage']
+}
+
+export interface TriggerSchedulerHandle {
+  stop(): Promise<void>
+}
+
+/**
+ * Cron-expression validator backed by croner's own parser, injected into
+ * `loadZooidConfig({ validateCron })` so a malformed `schedule:` fails at
+ * config-load time with croner's real error, not a generic field-count check.
+ * `core` stays cron-dependency-free; only the daemon entrypoint needs this.
+ */
+export function validateCron(name: string, expr: string): void {
+  try {
+    new Cron(expr, { paused: true }).stop()
+  } catch (err) {
+    throw new Error(`triggers.${name}.schedule: ${(err as Error).message}`)
+  }
+}
+
+export function startTriggerScheduler(deps: StartTriggerSchedulerDeps): TriggerSchedulerHandle {
+  const { triggers, agentUserIds, resolveRoom, ensureBot, sendMessage } = deps
+  const jobs: Cron[] = []
+
+  for (const [name, trigger] of Object.entries(triggers)) {
+    if (!trigger.schedule) continue
+    const job = new Cron(trigger.schedule, () => {
+      for (const message of trigger.messages) {
+        const agentUserId = agentUserIds[message.mention]
+        if (!agentUserId) {
+          console.warn(`[trigger:${name}] unknown agent "${message.mention}" — skipping`)
+          continue
+        }
+        void fireTrigger({ name, as: trigger.as, message, agentUserId, resolveRoom, ensureBot, sendMessage })
+      }
+    })
+    jobs.push(job)
+  }
+
+  return {
+    async stop(): Promise<void> {
+      for (const job of jobs) job.stop()
+    },
+  }
+}

package/src/daemon/webhook-routes.test.ts

@@ -0,0 +1,74 @@
+import { createHmac } from 'node:crypto'
+import { describe, expect, it, vi } from 'vitest'
+import { Hono } from 'hono'
+import { loadZooidConfig } from '@zooid/core'
+import { mountWebhookRoutes } from './webhook-routes.js'
+
+const secret = 'route-secret'
+const body = JSON.stringify({ action: 'opened' })
+const signature = `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`
+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:
+  triage:
+    webhook:
+      provider: github
+      secret: ${secret}
+    as: '@hook:example.org'
+    room: '!product:example.org'
+    mention: product
+    text: Triage.
+`
+
+function makeApp() {
+  const sent: Array<Record<string, unknown>> = []
+  const app = new Hono()
+  mountWebhookRoutes(app, {
+    triggers: loadZooidConfig(yaml).triggers,
+    agentUserIds: { product: '@product:example.org' },
+    resolveRoom: async (room) => room,
+    ensureBot: async () => {},
+    sendMessage: async (message: Record<string, unknown>) => {
+      sent.push(message)
+      return { event_id: '$event' }
+    },
+  })
+  return { app, sent }
+}
+
+function post(app: Hono, path: string) {
+  return app.request(path, {
+    method: 'POST',
+    body,
+    headers: {
+      'x-hub-signature-256': signature,
+      'x-github-event': 'issues',
+      'x-github-delivery': crypto.randomUUID(),
+    },
+  })
+}
+
+describe('webhook route contract', () => {
+  it('accepts a signed delivery at /_zooid/webhooks/:name', async () => {
+    const { app, sent } = makeApp()
+    expect((await post(app, '/_zooid/webhooks/triage')).status).toBe(202)
+    await vi.waitFor(() => expect(sent).toHaveLength(1))
+  })
+
+  it('does not expose the retired /webhook/:name route', async () => {
+    const { app, sent } = makeApp()
+    expect((await post(app, '/webhook/triage')).status).toBe(404)
+    expect(sent).toHaveLength(0)
+  })
+})