cornfield 0.10.0 → 0.12.0

package/server/forge-github.js

@@ -233,6 +233,11 @@ export function createGitHubForge(forge, { token = null, fetch, apiUrl, timeoutM
       return (await client.list(`repos/${repo}/pulls/${n}/files?per_page=${PER_PAGE}`, { what: `the files of ${pullWhat(n)}` })).map(toFile);
     },
 
+    async compare(base, head) {
+      const { body } = await client.request('GET', `repos/${repo}/compare/${segments(base)}...${segments(head)}`, { what: `the files of ${head} against ${base} in ${forge.repo}` });
+      return (Array.isArray(body?.files) ? body.files : []).map(toFile);
+    },
+
     async pullCommits(n) {
       return (await client.list(`repos/${repo}/pulls/${n}/commits?per_page=${PER_PAGE}`, { what: `the commits of ${pullWhat(n)}` })).map(toCommit);
     },

package/server/forge.js

@@ -86,6 +86,7 @@
  *   createIssue(issue: { title: string, body: string, labels?: string[] }): Promise<Issue>,
  *   pullFiles(n: number): Promise<PullFile[]>,
  *   pullCommits(n: number): Promise<PullCommit[]>,
+ *   compare(base: string, head: string): Promise<PullFile[]>,   // the files a branch changes against another (optional: a forge that cannot list them throws `invalid`)
  *   comments(n: number, opts?: { since?: string }): Promise<Comment[]>,
  *   comment(n: number, body: string): Promise<Comment>,
  *   checks(ref: string): Promise<Check[]>,
@@ -280,6 +281,10 @@ export function wrap(a, forge) {
     },
     pullFiles: async (n) => a.pullFiles(number(n)),
     pullCommits: async (n) => a.pullCommits(number(n)),
+    compare: async (base, head) => {
+      if (typeof a.compare !== 'function') throw invalid('This forge does not list the files of a comparison.');
+      return a.compare(text(base, 'The base branch'), text(head, 'The branch'));
+    },
     comments: async (n, opts) => {
       if (opts !== undefined && (opts === null || typeof opts !== 'object' || Array.isArray(opts))) throw invalid('The options are an object.');
       const since = opts && opts.since;

package/server/hooks.js

@@ -25,10 +25,18 @@
  *                   `{ event, at, actor, expiresAt, mapUrl }`
  *   agent.requested  a maintainer asked for an agent run (server/agent-runs.js). Its body is its own: `{ event, at, request, actor, mapUrl }`,
  *                   `request` being the whole request JSON of the contract (docs/agent-contract.md), which holds no credential by construction
+ *   trigger.skipped  an opt-in trigger (`agents.on`, server/triggers.js) was going to request a run and did not: the maintainer whose act caused it has no
+ *                   live sign-in (`reason: 'no-session'`), or the request was refused (the cap, the one-run-per-subject rule, the rate limit: the refusal's code).
+ *                   Its body is its own: `{ event, at, trigger: { event, by, ref }, by, reason, mapUrl }`
  *   run.claimed  run.state  run.stopRequested  run.finished   a run was claimed by its runner, changed state, was asked to stop, ended. They are
  *                   seen when cornfield looks (the spec poll, server/spec-poll.js), each once. Their body is their own:
  *                   `{ event, at, runId, state, pull?, issue?, actor, mapUrl }`
  *
+ * **Triggers listen in-process.** `subscribe(fn)` hands a function the same moments the hooks fire at, with the payload resolved, whether or not
+ * any hook asks for them (server/triggers.js: `spec.approved`, `build.opened`, `thread.message`). A thread's payload then also holds the
+ * comment's text and times for that function alone; `bodyOf` picks fixed fields, so none of it can leave through a hook. A subscriber never
+ * slows or breaks a delivery, and a failing one is only logged.
+ *
  * **A hook never gets in the way.** `emit` returns at once and never throws; the delivery runs in the background, from a
  * queue in memory. A failed delivery (a network error, a timeout, anything but a 2xx) is tried again after 1s, 5s and 30s
  * (four attempts in all) and every attempt is a row in the `actions` audit table (`action: 'hook'`). A hook that is
@@ -135,6 +143,9 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
   if (typeof secret !== 'string' || secret.length < MIN_HOOK_SECRET) throw new Error(`${HOOK_SECRET_ENV} must be at least ${MIN_HOOK_SECRET} characters.`);
   const targets = hooks.map((h, i) => ({ index: i, url: h.url, origin: originOf(h.url), events: h.events === '*' ? HOOK_EVENTS : h.events }));
   const timers = new Set();
+  /** @type {{ fn: (event: string, payload: any) => unknown, events: string[] | null }[]} */
+  const subscribers = [];
+  const listeners = (event) => subscribers.filter((s) => s.events === null || s.events.includes(event));
   let pending = 0;
   let closed = false;
 
@@ -200,6 +211,11 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
   function bodyOf(event, p) {
     // A session's end has no spec, pull request or proposal: its body is only who, until when, and where cornfield is
     if (event === 'session.expiring') return JSON.stringify({ event, at: new Date(now()).toISOString(), actor: p.actor ?? null, expiresAt: p.expiresAt ?? null, mapUrl: publicUrl || null });
+    // A skipped trigger says which trigger, who caused it and why it did nothing: never a brief or any text
+    if (event === 'trigger.skipped') {
+      const t = p.trigger && typeof p.trigger === 'object' ? { event: p.trigger.event ?? null, by: p.trigger.by ?? null, ref: p.trigger.ref ?? null } : null;
+      return JSON.stringify({ event, at: new Date(now()).toISOString(), trigger: t, by: p.by ?? null, reason: p.reason ?? null, mapUrl: publicUrl || null });
+    }
     // A request goes out as it was posted, and is checked once more on the way: nothing like a credential can leave through a hook
     if (event === 'agent.requested') {
       const checked = validateRequest(p.request);
@@ -244,10 +260,17 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
     try {
       if (closed || !HOOK_EVENTS.includes(event)) return;
       const to = targets.filter((t) => t.events.includes(event));
-      if (!to.length) return;
+      // Nobody wants it: the payload is not even worked out (it may read the forge)
+      const local = listeners(event);
+      if (!to.length && !local.length) return;
       Promise.resolve()
         .then(() => (typeof payload === 'function' ? payload() : payload))
         .then((p) => {
+          // In-process listeners first, each on its own: they cannot hold up or break a delivery
+          for (const { fn } of local) {
+            Promise.resolve().then(() => fn(event, p || {})).catch((err) => console.error(`[cornfield] a listener of ${event} failed: ${err instanceof Error ? err.message : err}`));
+          }
+          if (!to.length) return;
           const body = bodyOf(event, p || {});
           for (const t of to) {
             if (pending >= MAX_PENDING) {
@@ -267,6 +290,17 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
     }
   }
 
+  /**
+   * Listens in-process to every event `emit` is given (a trigger does: server/triggers.js). `fn(event, payload)` gets the payload
+   * resolved; it may be async, is never awaited and its failure is only logged. With `events`, only those: an event nobody listens to and no
+   * hook asks for has its payload left unworked out.
+   * @param {(event: string, payload: any) => unknown} fn
+   * @param {string[]} [events]
+   */
+  function subscribe(fn, events) {
+    if (typeof fn === 'function') subscribers.push({ fn, events: Array.isArray(events) ? [...events] : null });
+  }
+
   /**
    * `spec.ready`: the spec PRs a listing just showed. A (pull request, head, proposal) that is not a draft and was not
    * seen before is announced once, and remembered in the SQLite file so a restart does not announce it again. A draft is
@@ -345,7 +379,7 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
           emit('thread.linked', { thread: t.number, actor: t.opened.actor, nodes: t.opened.linked.nodes, proposal: t.opened.linked.proposal });
         }
         for (const m of t.messages) {
-          if (fresh(t.number, String(m.id), m.stamp)) emit('thread.message', { thread: t.number, comment: m.id, actor: m.actor });
+          if (fresh(t.number, String(m.id), m.stamp)) emit('thread.message', { thread: t.number, comment: m.id, actor: m.actor, message: m.text });
           if (m.linked && fresh(t.number, `link:${m.id}`)) emit('thread.linked', { thread: t.number, comment: m.id, actor: m.actor, nodes: m.linked.nodes, proposal: m.linked.proposal });
         }
         // The last-update time moves with every look that read the thread, so the next look can skip it when nothing changed
@@ -395,7 +429,7 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
     timers.clear();
   }
 
-  return { emit, specsSeen, threadCursors, threadsSeen, watchSessions, close };
+  return { emit, subscribe, specsSeen, threadCursors, threadsSeen, watchSessions, close };
 }
 
 /** The SHA-256 of a proposal file as `read` gives it, or null when it cannot be read (an event still goes out) */

package/server/server.js

@@ -46,9 +46,9 @@
 import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { browserSources, BUILTIN_SOURCES, parseDuration, specPollMs, DEFAULTS, hookWants, ideaLabel } from '../core/config.js';
+import { browserSources, BUILTIN_SOURCES, parseDuration, specPollMs, triggersOf, DEFAULTS, hookWants, ideaLabel } from '../core/config.js';
 import { CLOUD_FILE } from '../core/cloud.js';
 import { decodePath, inside, notFound, sendFile } from './files.js';
 import { serveProposals } from './proposals.js';
@@ -65,6 +65,7 @@ import { createAuth, signInSettings } from './auth.js';
 import { createHooks, hooksSettings } from './hooks.js';
 import { createLander } from './lander.js';
 import { createSpecPoll } from './spec-poll.js';
+import { createTriggers } from './triggers.js';
 
 export const CORNFIELD_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const EXPLORER_DIR = path.join(CORNFIELD_DIR, 'explorer');
@@ -122,6 +123,8 @@ export function clientConfig(config, signIn = false) {
     // Threads (docs/threads.md): the idea label, or false when `threads: false` turns the Threads tab off
     threads: config.threads === false ? false : { label: ideaLabel(config) },
     sources: browserSources(config),
+    // Agent runs are followed (and marked on the map) where there is a forge and a sign-in (docs/agents.md)
+    ...(config.forge && signIn ? { agents: { runs: true } } : {}),
     signIn,
   };
 }
@@ -150,8 +153,13 @@ export function createCornfieldServer(config, opts = {}) {
   const auth = createAuth(config, opts);
   // Hooks listed without a secret (or without sign-in) are a startup error, like a half-configured sign-in
   const hookSettings = hooksSettings(config, env, auth.enabled);
-  const hooks = hookSettings
-    ? createHooks({ hooks: config.hooks, secret: hookSettings.secret, fetch: opts.hookFetch, record: (entry) => auth.record(entry), store: auth.store, now: opts.now, publicUrl: config.publicUrl, timer: opts.hookTimer })
+  // Opt-in triggers (agents.on, server/triggers.js) act as the maintainer whose act caused them and read the forge: both need sign-in and a forge
+  const triggerList = triggersOf(config);
+  if (triggerList.length && !auth.enabled) throw new Error('The config says agents.on, but sign-in is not set up. A trigger requests a run as the maintainer whose act caused it, with their own sign-in, so without sign-in nothing would ever fire: set up sign-in (docs/sign-in.md), or remove agents.on.');
+  if (triggerList.length && !(config.forge && hasAdapter(config.forge.type))) throw new Error('The config says agents.on, but there is no forge to ask on. Set up `forge` (docs/config.md#forge), or remove agents.on.');
+  // With triggers and no hook listed, the hooks object has no destination: it is only the moments the triggers subscribe to (and the thread look's memory)
+  const hooks = hookSettings || triggerList.length
+    ? createHooks({ hooks: hookSettings ? config.hooks : [], secret: hookSettings ? hookSettings.secret : randomBytes(32).toString('hex'), fetch: opts.hookFetch, record: (entry) => auth.record(entry), store: auth.store, now: opts.now, publicUrl: config.publicUrl, timer: opts.hookTimer })
     : null;
   hooks?.watchSessions();
   // Landing on approval needs somebody signed in to land as, like the hooks' events: a half-set key is a startup error
@@ -174,6 +182,8 @@ export function createCornfieldServer(config, opts = {}) {
   const transport = config.agents?.transport ?? 'forge';
   if (transport !== 'forge' && !runs) throw new Error(`agents.transport is "${transport}", which needs sign-in and a forge to ask as a maintainer and to check them: set them up (docs/sign-in.md, docs/config.md#forge).`);
   if (transport === 'push' && !hookWants(config, ['agent.requested'])) throw new Error('agents.transport is "push", so a hook must subscribe to agent.requested: add { url, events: ["agent.requested"] } to "hooks" (docs/config.md#hooks). Without one a request would go nowhere.');
+  // Triggers subscribe to the hooks' moments and call the runs' own request path; nothing a run produces is wired to them (server/triggers.js)
+  if (runs && hooks && triggerList.length) createTriggers({ config, auth, runs, hooks, now: opts.now });
   runs?.resume().catch((err) => console.error(`[cornfield] agent runs could not be picked up: ${err instanceof Error ? err.message : err}`));
   // Looks at the open spec PRs on a timer when a hook wants spec.ready (config `hookPoll`); started when the server listens. The same timer follows
   // agent runs: it is started for them when there is a run to follow, or as one is asked for, and does nothing while there is none

package/server/spec-poll.js

@@ -36,7 +36,7 @@
 import { isMaintainer } from './forge.js';
 import { listPullProposals } from './proposal-pulls.js';
 import { gatherThreads, snapshotOf, POLL_LIMIT } from './threads.js';
-import { hookWants, threadsOn, THREAD_EVENTS } from '../core/config.js';
+import { hookWants, threadsOn, triggersOf, THREAD_EVENTS } from '../core/config.js';
 import { readTopology } from '../core/validate.js';
 
 /** How long after start the first look is made: soon, so the repo's silent first look is not left to the first interval */
@@ -47,6 +47,26 @@ export const MAX_CANDIDATES = 5;
 const iso = (ms) => new Date(ms).toISOString();
 const words = (err) => (err instanceof Error ? err.message : String(err));
 
+/**
+ * The forge as the newest live sign-in of a user who is a maintainer now, and their login, or null when there is none: the sign-ins are
+ * tried newest first, at most `MAX_CANDIDATES` users, and a token the forge refuses passes to the next. The token is only asked who it is and
+ * what it may do on the repo. Shared with the triggers (server/triggers.js), which confirm a commenter with it.
+ * @param {{ auth: { store: () => Promise<import('node:sqlite').DatabaseSync>, forgeForUser: (userId: string) => Promise<import('./forge.js').Forge> }, repo: string, now?: () => number }} opts
+ * @returns {Promise<{ forge: import('./forge.js').Forge, login: string } | null>}
+ */
+export async function findMaintainerForge({ auth, repo, now = Date.now }) {
+  const rows = /** @type {{ user_id: string }[]} */ ((await auth.store()).prepare("SELECT user_id FROM sessions WHERE token <> '' AND expires_at > ? ORDER BY created_at DESC, rowid DESC").all(iso(now())));
+  const users = [...new Set(rows.map((r) => r.user_id))].slice(0, MAX_CANDIDATES);
+  for (const userId of users) {
+    try {
+      const forge = await auth.forgeForUser(userId);
+      const me = await forge.me();
+      if (String(me.id) === userId && isMaintainer(await forge.permission(repo, me.login))) return { forge, login: me.login };
+    } catch { /* this user's token is gone or refused: the next one */ }
+  }
+  return null;
+}
+
 /**
  * @param {{
  *   config: any,
@@ -74,19 +94,9 @@ export function createSpecPoll({ config, where, auth, hooks, runs = null, specs
   /** Whose token the last look used: the log names them each time that changes, so whose sign-in is read with is on record */
   let lookingAs = null;
 
-  /** The forge as the newest live sign-in of a user who is a maintainer now, and their login, or null when there is none */
-  async function maintainerForge() {
-    const rows = /** @type {{ user_id: string }[]} */ ((await auth.store()).prepare("SELECT user_id FROM sessions WHERE token <> '' AND expires_at > ? ORDER BY created_at DESC, rowid DESC").all(iso(now())));
-    const users = [...new Set(rows.map((r) => r.user_id))].slice(0, MAX_CANDIDATES);
-    for (const userId of users) {
-      try {
-        const forge = await auth.forgeForUser(userId);
-        const me = await forge.me();
-        if (String(me.id) === userId && isMaintainer(await forge.permission(repo, me.login))) return { forge, login: me.login };
-      } catch { /* this user's token is gone or refused: the next one */ }
-    }
-    return null;
-  }
+  /** Whether a look reads the threads: a hook wants a thread.* event, or a trigger listens for `/agent` in a message (server/triggers.js) */
+  const wantsThreads = () => threadsOn(config) && (hookWants(config, THREAD_EVENTS) || triggersOf(config).some(([e]) => e === 'thread.message'));
+  const maintainerForge = () => findMaintainerForge({ auth, repo, now });
 
   /** The checkout's nodes, for a hook's `nodes` to be the ones a mention resolves to; none when there is no map */
   function mapNodes() {
@@ -133,13 +143,13 @@ export function createSpecPoll({ config, where, auth, hooks, runs = null, specs
     }
     if (noSession) log('a signed-in maintainer is back; checking the open spec PRs again');
     noSession = false;
-    if (found.login !== lookingAs) log(`looking at the open spec PRs${threadsOn(config) && hookWants(config, THREAD_EVENTS) ? ' and threads' : ''} with the sign-in of @${found.login}, a maintainer`);
+    if (found.login !== lookingAs) log(`looking at the open spec PRs${wantsThreads() ? ' and threads' : ''} with the sign-in of @${found.login}, a maintainer`);
     lookingAs = found.login;
     let out = 'ok';
     if (specs) {
       try {
         const specReady = hookWants(config, ['spec.ready']);
-        const threads = threadsOn(config) && hookWants(config, THREAD_EVENTS);
+        const threads = wantsThreads();
         // One listing of the open PRs serves both: the threads' look makes it itself when it runs
         const problem = threads ? await lookAtThreads(found.forge, specReady) : (await listPullProposals(found.forge, where, { hooks })).problem;
         if (problem) {

package/server/threads.js

@@ -256,7 +256,8 @@ const linkOf = (text, nodes) => {
 
 /**
  * What `hooks.threadsSeen` is handed: for each thread, who opened it, its comments (their id, author, own time and what they
- * link to, resolved against `nodes`), and the spec PRs that name it. Never a text: a hook says that something was said, not what.
+ * link to, resolved against `nodes`), and the spec PRs that name it. A hook says that something was said, not what: the text rides along
+ * as `text` for a trigger's in-process listener only, and no hook body holds it.
  * @param {{ threads: any[], pulls: any[] }} got `gatherThreads`' answer
  * @param {{ id: string, file?: string }[]} nodes the checkout's map
  */
@@ -268,7 +269,8 @@ export function snapshotOf(got, nodes) {
       stamp: t.item.updatedAt,
       unchanged: Boolean(t.unchanged),
       opened: t.kind === 'idea' ? { actor: t.item.author ? t.item.author.login : null, linked: linkOf(t.item.body, nodes) } : null,
-      messages: t.comments.map((c) => ({ id: c.id, actor: c.author ? c.author.login : null, stamp: c.updatedAt, linked: linkOf(c.body, nodes) })),
+      // `text` is for the in-process listeners of thread.message only (an opt-in trigger reads /agent in it): bodyOf never lets it into a hook's body
+      messages: t.comments.map((c) => ({ id: c.id, actor: c.author ? c.author.login : null, stamp: c.updatedAt, linked: linkOf(c.body, nodes), text: { body: c.body, createdAt: c.createdAt, updatedAt: c.updatedAt, bot: Boolean(c.author && c.author.bot) } })),
     })),
     pulls: got.pulls,
   };

package/server/triggers.js

@@ -0,0 +1,284 @@
+/**
+ * @module server/triggers
+ *
+ * Opt-in triggers (issue #83, spec 0005 D10, docs/agents.md#triggers): a run asked for by something a maintainer did, with no click.
+ * Off by default, and set like landing on approval is:
+ *
+ *   agents: { profiles: ['claude'], on: { 'spec.approved': { kind: 'code', profile: 'claude' } } }
+ *
+ * **One internal path.** A trigger subscribes in-process to the moments the hooks fire at (`hooks.subscribe`, server/hooks.js; not over
+ * HTTP) and calls the very function the button calls, `runs.request` (server/agent-runs.js), as the maintainer whose act caused it, with
+ * THEIR sign-in (`auth.forgeForUser`), so the request comment is theirs and the forge keeps the record. The cap, the rate limit and
+ * the one-run-per-subject rule are the request's own, so they apply unchanged. A trigger needs no hook to be configured: the server
+ * makes the hooks object anyway, with no destination, so there is a moment to subscribe to.
+ *
+ * **Only three events, each a maintainer's act.**
+ *
+ *   spec.approved   a maintainer approved a proposal (the button or the review API)     request: kind, about the proposal, posted on its spec PR
+ *   build.opened    a maintainer opened the build issue of an approved proposal         request: about that issue
+ *   thread.message a comment with a line that starts `/agent`, optionally with a brief   request: about that thread (the issue or spec PR)
+ *
+ * `/agent` is honoured only from a maintainer the forge confirms NOW, only in a comment that was not edited, and only once per comment
+ * (a `thread_seen` row keyed `trigger:…`, so a restart never repeats it; the table's other readers skip keys with a colon). The rest of
+ * the line is the brief. A line inside a code span or a fenced block is never a command, nor one in a quote or an indented block.
+ * Every automatic request records its cause in the request itself (`trigger: { event, by, ref }`, core/agent-contract.js).
+ *
+ * **No chaining: a run's OUTPUT never causes a run.** In three layers:
+ *   1. Structural: the only events handled are the three above. Nothing a run produces (a push, a pull request, a check, a report, a run's
+ *      state change: `run.*`, `agent.requested`) is wired to a trigger; `server/agent-runs.js` does not know this module exists.
+ *   2. Who: no trigger fires when the actor is a login in `agents.runners` or a bot account ("[bot]", or the forge's Bot type), or the
+ *      comment holds a `cornfield-run` block.
+ *   3. What: no trigger fires on a run's output: a pull request cornfield holds as a run's linked one (in any state, the run finished or
+ *      not), or a pull request or issue whose text or branch carries a run id (`Cornfield-Run:`) or whose author is a runner or a bot.
+ *   Each posts nothing and sends no hook, but writes a `trigger-ignored` audit row with the reason (`machine`, `run-block`, `edited`,
+ *   `run-output`), so a maintainer can see why nothing happened. A comment that holds no `/agent` command is not a cause at all and writes
+ *   nothing.
+ *
+ * **A run's TARGET is not its output.** The thread, issue or spec pull request a run was requested on may fire again once every run on it is
+ * over (finished, or quiet: what the cap counts). While one is open, the trigger is skipped with `run-open` (`trigger-skipped` and the
+ * hook), whatever its profile; the one-run-per-subject rule of the request path only clashes within a profile.
+ *
+ * **approveLands.** With `proposals.approveLands`, an approval may land the spec pull request before the trigger's request reads it; the
+ * request then finds no open proposal and the trigger is skipped with `not-found` (audited, and the hook). The proposal is on the default
+ * branch by then: ask for the run with the button, or use the `build.opened` trigger, which fires after the build issue is opened.
+ *
+ * **No live sign-in.** If the maintainer has no live session, the trigger does nothing else (cornfield holds no forge token of its own, and
+ * another maintainer's would put words in their name): an audit row (`trigger-skipped`), the hook event `trigger.skipped`
+ * (`reason: 'no-session'`), and the dashboard's notice on the Agents tab, which reads the last 24 hours of those rows
+ * (`runs.list().triggerSkipped`). A request the cap or a limit refuses ends the same way with that refusal's code: nothing is posted.
+ */
+
+import { ForgeError, isMaintainer } from './forge.js';
+import { triggersOf } from '../core/config.js';
+import { EDIT_GRACE_MS, MAX_BRIEF_CHARS, RUN_TAG, TRIGGER_EVENTS, findRunId } from '../core/agent-contract.js';
+import { Refused } from './throttle.js';
+import { findMaintainerForge } from './spec-poll.js';
+
+const iso = (ms) => new Date(ms).toISOString();
+const lower = (s) => String(s).toLowerCase();
+const words = (err) => (err instanceof Error ? err.message : String(err));
+
+/** A bot account by its name: GitHub's apps are "name[bot]"; the forge's own Bot type rides in `Author.bot` */
+export const isBotLogin = (login) => /\[bot\]$/i.test(String(login));
+
+/** A run's own block in a comment: a fence whose info string starts `cornfield-run` (a trigger never fires on one, whoever wrote it) */
+const RUN_FENCE = new RegExp(`^[ \\t]{0,3}(?:\`{3,}|~{3,})[ \\t]*${RUN_TAG}\\b`, 'mi');
+
+/**
+ * The `/agent` command of a comment: the first line that starts with `/agent` (up to three spaces in, as Markdown allows) and has
+ * nothing glued to it, outside fenced code and not in a quote. The rest of that line, trimmed, is the brief. A command inside a code span is no
+ * command (the span is not at the start of the line, so the line does not start with the command); one inside a fence, a quote or an
+ * indented block is not read at all.
+ * @param {string} text
+ * @returns {{ brief: string } | null}
+ */
+export function agentCommand(text) {
+  if (typeof text !== 'string') return null;
+  let fence = null;
+  for (const line of text.split(/\r?\n/)) {
+    if (fence) {
+      // A fence closes with a line of the same mark, at least as long, and nothing else
+      const close = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
+      if (close && close[1][0] === fence[0] && close[1].length >= fence.length) fence = null;
+      continue;
+    }
+    const open = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    // A backtick fence's info string holds no backtick: ```x``` on one line is a code span, not a fence
+    if (open && !(open[1][0] === '`' && line.slice(line.indexOf(open[1]) + open[1].length).includes('`'))) { fence = open[1]; continue; }
+    const m = /^ {0,3}\/agent(?=[ \t]|$)(.*)$/.exec(line);
+    if (m) return { brief: m[1].trim().slice(0, MAX_BRIEF_CHARS) };
+  }
+  return null;
+}
+
+/** The reason a refused request gives in `trigger.skipped` and the audit row: the refusal's own code */
+function reasonOf(err) {
+  if (err instanceof ForgeError) return err.code === 'unauthorized' ? 'no-session' : err.code || 'forge';
+  if (err instanceof Refused) return err.code || 'refused';
+  return 'error';
+}
+
+/**
+ * @param {{
+ *   config: any,
+ *   auth: { store: () => Promise<import('node:sqlite').DatabaseSync>, record: Function, forgeForUser: (userId: string) => Promise<import('./forge.js').Forge> },
+ *   runs: { request: Function },
+ *   hooks: import('./hooks.js').Hooks,
+ *   now?: () => number,
+ * }} opts
+ */
+export function createTriggers({ config, auth, runs, hooks, now = Date.now }) {
+  const repo = config.forge.repo;
+  const agents = config.agents || {};
+  const rules = new Map(triggersOf(config));
+  const runnerSet = new Set((Array.isArray(agents.runners) ? agents.runners : []).map(lower));
+  const log = (what) => console.error(`[cornfield] triggers: ${what}`);
+  /** One event at a time, in the order they came: the cap is checked inside the request, and a test can wait for the queue */
+  let queue = Promise.resolve();
+
+  /** Whether an account is a runner or a bot: what it does is a run's output, never a cause */
+  const machine = (login, bot = false) => bot === true || isBotLogin(login) || runnerSet.has(lower(login));
+
+  /** Whether cornfield holds this number as a run's linked pull request: a run's output, in any state, the run finished or not */
+  async function runOutput(numbers) {
+    const db = await auth.store();
+    const ask = db.prepare('SELECT 1 FROM runs WHERE repo = ? AND pull = ? LIMIT 1');
+    return numbers.some((n) => Number.isInteger(n) && ask.get(repo, n) !== undefined);
+  }
+
+  /**
+   * Whether a pull request or issue is a run's output by what it says: a run id in its text or branch, or an author that is a runner or a bot.
+   * Read with the person's own forge. Fails closed: what cannot be read is treated as a run's.
+   */
+  async function outputOfRun(forge, n) {
+    try {
+      let item;
+      try {
+        item = await forge.pull(n);
+      } catch (err) {
+        if (!(err instanceof ForgeError) || err.code !== 'not-found') throw err;
+        item = await forge.issue(n);
+      }
+      if (item.author && machine(item.author.login, item.author.bot === true)) return true;
+      return findRunId({ body: item.body, branch: item.head?.ref }) !== null;
+    } catch (err) {
+      log(`#${n} could not be read, so no trigger fires on it: ${words(err)}`);
+      return true;
+    }
+  }
+
+  /** A live sign-in's user id for a login, or null */
+  async function sessionOf(login) {
+    const db = await auth.store();
+    const row = /** @type {{ user_id: string } | undefined} */ (db.prepare("SELECT user_id FROM sessions WHERE lower(login) = ? AND token <> '' AND expires_at > ? ORDER BY created_at DESC, rowid DESC LIMIT 1").get(lower(login), iso(now())));
+    return row ? row.user_id : null;
+  }
+
+  /** Remembers that this cause was acted on; false if it was already (a repeat, or a restart) */
+  async function first(number, key) {
+    const db = await auth.store();
+    return db.prepare('INSERT OR IGNORE INTO thread_seen (repo, issue, comment, stamp, at) VALUES (?, ?, ?, ?, ?)').run(repo, number, key, '', iso(now())).changes === 1;
+  }
+
+  /**
+   * A no-chaining exit: an audit row (`trigger-ignored`, with the reason) and nothing else, no hook and nothing posted, so a maintainer can
+   * see why an act of theirs started nothing. Never the comment's text: only the event, who and the reference.
+   */
+  async function ignore(cause, reason) {
+    try {
+      await auth.record({ login: cause.by, action: 'trigger-ignored', target: `${repo}#${cause.subject}`, request: { event: cause.event, by: cause.by, ref: cause.ref }, status: null, answer: { reason } });
+    } catch (err) {
+      log(`an ignored trigger could not be written to the audit table: ${words(err)}`);
+    }
+  }
+
+  /** The trigger did nothing, and says why: an audit row and the `trigger.skipped` hook event. It posts nothing. */
+  async function skip(cause, reason) {
+    try {
+      await auth.record({ login: cause.by, action: 'trigger-skipped', target: `${repo}#${cause.subject}`, request: { event: cause.event, by: cause.by, ref: cause.ref }, status: null, answer: { reason } });
+    } catch (err) {
+      log(`a skipped trigger could not be written to the audit table: ${words(err)}`);
+    }
+    hooks.emit('trigger.skipped', { trigger: { event: cause.event, by: cause.by, ref: cause.ref }, by: cause.by, reason });
+  }
+
+  /** What caused a trigger, from a hook event's payload; null when it is not one a trigger may fire on */
+  function causeOf(event, p) {
+    if (event === 'spec.approved') {
+      if (typeof p.actor !== 'string' || !Number.isInteger(p.pull) || typeof p.slug !== 'string') return null;
+      return { event, by: p.actor, ref: `pull:${p.pull}`, subject: p.pull, owned: [p.pull], checked: [p.pull], refs: { proposal: p.slug }, key: `trigger:spec.approved:${p.headSha ?? ''}`, brief: '' };
+    }
+    if (event === 'build.opened') {
+      if (typeof p.actor !== 'string' || !Number.isInteger(p.issue)) return null;
+      return { event, by: p.actor, ref: `issue:${p.issue}`, subject: p.issue, owned: [p.issue, p.pull], checked: [p.pull, p.issue], refs: { issue: p.issue }, key: `trigger:build.opened:${p.issue}`, brief: '' };
+    }
+    if (event === 'thread.message') {
+      const m = p.message;
+      if (!m || typeof m.body !== 'string' || typeof p.actor !== 'string' || !Number.isInteger(p.thread) || p.comment === undefined) return null;
+      return { event, by: p.actor, ref: `comment:${p.comment}`, subject: p.thread, owned: [p.thread], checked: [p.thread], refs: { thread: p.thread }, key: `trigger:comment:${p.comment}`, message: m, brief: '' };
+    }
+    return null;
+  }
+
+  async function handle(event, p) {
+    const rule = rules.get(event);
+    if (!rule) return;
+    const cause = causeOf(event, p);
+    if (!cause) return;
+
+    // --- a comment with no /agent command is no cause at all: nothing, not even a row (most thread messages are this)
+    const command = cause.message ? agentCommand(cause.message.body) : null;
+    if (cause.message && !command) return;
+    // --- who: a runner or a bot never causes anything; a run's own block is no command; an edited comment is not trusted
+    if (machine(cause.by) || cause.message?.bot === true) return ignore(cause, 'machine');
+    if (cause.message) {
+      const m = cause.message;
+      if (RUN_FENCE.test(m.body)) return ignore(cause, 'run-block');
+      // Both forges give the comment's own created and updated times; one missing or unreadable counts as edited (fails closed)
+      if (!(Date.parse(m.updatedAt) - Date.parse(m.createdAt) <= EDIT_GRACE_MS)) return ignore(cause, 'edited');
+      cause.brief = command.brief;
+    }
+    // --- what: a run's output (its linked pull request) never fires, in any state
+    if (await runOutput(cause.owned)) return ignore(cause, 'run-output');
+    // --- once: a cause is acted on one time, across restarts
+    if (!(await first(cause.subject, cause.key))) return;
+
+    // --- a command is honoured only from a maintainer the forge confirms now (the others get nothing, not even a row)
+    if (cause.message) {
+      const found = await findMaintainerForge({ auth, repo, now });
+      if (!found) { log('no signed-in maintainer to confirm who wrote an /agent comment, so it was not honoured'); return; }
+      let permission;
+      try {
+        permission = await found.forge.permission(repo, cause.by);
+      } catch (err) {
+        log(`the permission of ${cause.by} could not be read, so their /agent comment was not honoured: ${words(err)}`);
+        return;
+      }
+      if (!isMaintainer(permission)) return;
+    }
+
+    // --- a run's target may fire again once its runs are over; while one is open, the trigger is skipped and says so
+    if (typeof runs.openOn === 'function' && await runs.openOn({ number: cause.subject, refs: cause.refs })) return skip(cause, 'run-open');
+
+    // --- the maintainer's own sign-in, or nothing else
+    const userId = await sessionOf(cause.by);
+    if (userId === null) return skip(cause, 'no-session');
+    let forge;
+    try {
+      forge = await auth.forgeForUser(userId);
+    } catch (err) {
+      return skip(cause, reasonOf(err));
+    }
+    // The pull request or issue itself may be a run's (a run id in its text or branch, a runner as its author) before cornfield has linked it
+    for (const n of cause.checked) if (Number.isInteger(n) && await outputOfRun(forge, n)) return ignore(cause, 'run-output');
+
+    const body = { kind: rule.kind, ...(rule.profile ? { profile: rule.profile } : {}), refs: cause.refs, brief: cause.brief || rule.brief || '' };
+    try {
+      await runs.request({
+        forge: () => forge, who: { login: cause.by, userId: String(userId) }, limits: { auth, now },
+        trigger: { event: cause.event, ref: cause.ref },
+      }, { body });
+    } catch (err) {
+      if (!(err instanceof Refused) && !(err instanceof ForgeError)) log(`a ${event} trigger failed: ${err instanceof Error ? err.stack || err.message : err}`);
+      return skip(cause, reasonOf(err));
+    }
+  }
+
+  /** The hooks' moments: the only ones a trigger looks at are the three a maintainer causes */
+  function onEvent(event, payload) {
+    if (!TRIGGER_EVENTS.includes(event) || !rules.has(event)) return queue;
+    queue = queue.then(() => handle(event, payload)).catch((err) => log(`a ${event} trigger failed: ${words(err)}`));
+    return queue;
+  }
+
+  hooks.subscribe(onEvent, [...rules.keys()]);
+
+  return {
+    /** Which events have a trigger */
+    events: [...rules.keys()],
+    /** Resolves when every event handed so far has been dealt with (for tests and for a clean shutdown) */
+    idle: () => queue,
+  };
+}
+
+/** @typedef {ReturnType<typeof createTriggers>} Triggers */