@popcorn245/cornfield 0.10.0 → 0.11.0

package/core/agent-contract.js

@@ -39,7 +39,7 @@
  * @typedef {{ issue?: number, proposal?: string, pull?: number, thread?: number }} RunRefs
  * @typedef {{ minutes?: number, turns?: number, cost?: number }} RunLimits
  * @typedef {{ version: 1, runId: string, kind: RunKind, profile?: string, refs: RunRefs, branch?: string, brief: string,
- *   limits?: RunLimits, nodes?: string[], requestedBy: string, requestedAt: string }} RunRequest
+ *   limits?: RunLimits, nodes?: string[], requestedBy: string, requestedAt: string, trigger?: { event: 'spec.approved' | 'build.opened' | 'thread.message', by: string, ref: string } }} RunRequest
  * @typedef {'claimed' | 'working' | 'done' | 'failed' | 'stopped'} ReportState
  * @typedef {{ state: ReportState, note?: string, url?: string, tokens?: number, cost?: number }} RunReport
  * @typedef {{ state: 'stop-requested', note?: string }} StopRequest
@@ -83,7 +83,10 @@ export const RUN_TAG = 'cornfield-run';
 /** The key of the trailer */
 export const TRAILER_KEY = 'Cornfield-Run';
 
-const REQUEST_KEYS = ['version', 'runId', 'kind', 'profile', 'refs', 'branch', 'brief', 'limits', 'nodes', 'requestedBy', 'requestedAt'];
+const REQUEST_KEYS = ['version', 'runId', 'kind', 'profile', 'refs', 'branch', 'brief', 'limits', 'nodes', 'requestedBy', 'requestedAt', 'trigger'];
+const TRIGGER_KEYS = ['event', 'by', 'ref'];
+/** The events an opt-in trigger may fire on (`agents.on`, spec 0005 D10): each is something a maintainer did */
+export const TRIGGER_EVENTS = Object.freeze(['spec.approved', 'build.opened', 'thread.message']);
 const REF_KEYS = ['issue', 'proposal', 'pull', 'thread'];
 const LIMIT_KEYS = ['minutes', 'turns', 'cost'];
 const REPORT_KEYS = ['state', 'note', 'url', 'tokens', 'cost'];
@@ -101,6 +104,8 @@ export const LOGIN_SOURCE = '^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$';
 export const SLUG_SOURCE = `^[A-Za-z0-9][A-Za-z0-9._-]{0,${MAX_SLUG_CHARS - 1}}$`;
 export const PROFILE_SOURCE = `^[A-Za-z0-9][A-Za-z0-9._-]{0,${MAX_PROFILE_CHARS - 1}}$`;
 export const NODE_ID_SOURCE = `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,${MAX_NODE_CHARS - 1}}$`;
+/** What an automatic request says caused it: a pull request, an issue or a comment, by its number or id */
+export const TRIGGER_REF_SOURCE = '^(pull|issue|comment):[0-9]{1,20}$';
 export const ISO_SOURCE = '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,3})?Z$';
 /** An http(s) link with no user and password in it */
 export const URL_SOURCE = '^https?://[^\\s/@?#]+([/?#]\\S*)?$';
@@ -150,6 +155,7 @@ const SLUG = new RegExp(SLUG_SOURCE);
 const PROFILE = new RegExp(PROFILE_SOURCE);
 const NODE_ID = new RegExp(NODE_ID_SOURCE);
 const ISO = new RegExp(ISO_SOURCE);
+const TRIGGER_REF = new RegExp(TRIGGER_REF_SOURCE);
 const URL_RE = new RegExp(URL_SOURCE);
 const CREDENTIAL_KEY = new RegExp(CREDENTIAL_KEY_SOURCE);
 const CREDENTIAL_VALUE = new RegExp(CREDENTIAL_VALUE_SOURCE);
@@ -355,6 +361,17 @@ export function validateRequest(body, { profiles } = {}) {
   if (body.nodes !== undefined) value.nodes = [...body.nodes];
   value.requestedBy = body.requestedBy;
   value.requestedAt = body.requestedAt;
+  if (body.trigger !== undefined) {
+    if (!isObject(body.trigger)) return no('"trigger" is { event, by, ref }: what caused an automatic request.');
+    const triggerKeys = keyProblem(body.trigger, TRIGGER_KEYS, '"trigger"');
+    if (triggerKeys) return no(triggerKeys);
+    if (!TRIGGER_EVENTS.includes(body.trigger.event)) return no(`"trigger.event" is one of ${TRIGGER_EVENTS.join(', ')}.`);
+    if (typeof body.trigger.by !== 'string' || !LOGIN.test(body.trigger.by)) return no('"trigger.by" is the forge login of the maintainer whose act caused the request.');
+    if (typeof body.trigger.ref !== 'string' || !TRIGGER_REF.test(body.trigger.ref)) return no('"trigger.ref" is what the act was on: pull:<number>, issue:<number> or comment:<id>.');
+    // The request is posted as the maintainer whose act caused it, so the two name one person
+    if (body.trigger.by !== body.requestedBy) return no('"trigger.by" is the maintainer the request is made as, the same login as "requestedBy".');
+    value.trigger = { event: body.trigger.event, by: body.trigger.by, ref: body.trigger.ref };
+  }
   return { ok: true, value };
 }
 

package/core/agent-contract.schema.json

@@ -181,6 +181,37 @@
         "requestedAt": {
           "type": "string",
           "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,3})?Z$"
+        },
+        "trigger": {
+          "description": "Only on an automatic request (agents.on): what caused it. A maintainer's act, never a run's output.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "event",
+            "by",
+            "ref"
+          ],
+          "properties": {
+            "event": {
+              "enum": [
+                "spec.approved",
+                "build.opened",
+                "thread.message"
+              ]
+            },
+            "by": {
+              "type": "string",
+              "maxLength": 40,
+              "not": {
+                "pattern": "(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{30,}|(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{20,}|(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{15,}|(?<![A-Za-z0-9])gto-[A-Za-z0-9]{20,}|(?<![A-Za-z0-9])cf_(?:rt|at)_[A-Za-z0-9_-]{20,}|(?<![A-Za-z0-9])sk-(?=[A-Za-z0-9_-]{20})[A-Za-z_-]{0,40}[0-9]|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}|(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}|(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{10,}|(?<![A-Za-z0-9])eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{5,}|-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----|(?<![A-Za-z0-9])[bB][eE][aA][rR][eE][rR][ \\t]+(?=[A-Za-z0-9._~+/=-]{20})[A-Za-z._~+/=-]{0,40}[0-9]|(?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}://[^\\s/@:]+:[^\\s/@]+@"
+              },
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$"
+            },
+            "ref": {
+              "type": "string",
+              "pattern": "^(pull|issue|comment):[0-9]{1,20}$"
+            }
+          }
         }
       }
     },

package/core/config.js

@@ -40,7 +40,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
-import { PROFILE_SOURCE, MAX_NUMBER } from './agent-contract.js';
+import { PROFILE_SOURCE, MAX_NUMBER, MAX_BRIEF_CHARS, RUN_KINDS, TRIGGER_EVENTS, CREDENTIAL_VALUE_SOURCE } from './agent-contract.js';
+
+export { TRIGGER_EVENTS };
 
 export const CONFIG_FILE = 'cornfield.config.js';
 export const CORNFIELD_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -68,7 +70,7 @@ export const FORGE_TYPES = ['github', 'forgejo'];
 /** How a pull request cornfield lands is merged (`forge.mergeMethod`): the way the repo lands its pull requests */
 export const MERGE_METHODS = ['merge', 'squash', 'rebase'];
 /** The events a hook may ask for (`hooks[].events`), and what each one means: docs/config.md#hooks */
-export const HOOK_EVENTS = Object.freeze(['spec.ready', 'spec.approved', 'spec.sentBack', 'build.opened', 'pr.landed', 'session.expiring', 'thread.opened', 'thread.message', 'thread.linked', 'agent.requested', 'run.claimed', 'run.state', 'run.stopRequested', 'run.finished']);
+export const HOOK_EVENTS = Object.freeze(['spec.ready', 'spec.approved', 'spec.sentBack', 'build.opened', 'pr.landed', 'session.expiring', 'thread.opened', 'thread.message', 'thread.linked', 'agent.requested', 'run.claimed', 'run.state', 'run.stopRequested', 'run.finished', 'trigger.skipped']);
 /** The events that come from looking at threads (server/threads.js): a poll that wants any of them looks at threads too */
 export const THREAD_EVENTS = Object.freeze(['thread.opened', 'thread.message', 'thread.linked']);
 /** The keys of `threads` when it is an object, and the label's longest length */
@@ -111,7 +113,7 @@ export const ideaLabel = (config) => (threadsOn(config) ? (config.threads && con
  * @returns {number | null}
  */
 export function specPollMs(config) {
-  const wanted = hookWants(config, ['spec.ready']) || (threadsOn(config) && hookWants(config, THREAD_EVENTS));
+  const wanted = hookWants(config, ['spec.ready']) || (threadsOn(config) && (hookWants(config, THREAD_EVENTS) || triggersOf(config).some(([e]) => e === 'thread.message')));
   const every = config.hookPoll === false ? false : config.hookPoll ? config.hookPoll.specs : DEFAULTS.hookPoll.specs;
   return wanted && every !== false ? parseDuration(every ?? DEFAULTS.hookPoll.specs) : null;
 }
@@ -150,7 +152,7 @@ export const DEFAULTS = Object.freeze({
   personas: { roles: null, parent: 'root' },
   cloud: { parent: 'root' },
   releaseNotes: { breakingLabel: 'breaking' },
-  agents: { authors: [], labels: [], branchPrefixes: [], bots: true, transport: 'forge', maxOpen: DEFAULT_MAX_OPEN, profiles: [], runners: [], quietAfter: DEFAULT_QUIET_AFTER, limits: {} },
+  agents: { authors: [], labels: [], branchPrefixes: [], bots: true, transport: 'forge', maxOpen: DEFAULT_MAX_OPEN, profiles: [], runners: [], quietAfter: DEFAULT_QUIET_AFTER, limits: {}, on: {} },
   hooks: [],
   hookPoll: { specs: '5m' },
   threads: { label: 'idea' },
@@ -163,7 +165,7 @@ export const DEFAULTS = Object.freeze({
 const KEYS = Object.keys(DEFAULTS);
 /** The keys of `proposals` when it is an object: the folder, and whether an approval also lands the spec PR (opt-in, off unless true) */
 export const PROPOSALS_KEYS = Object.freeze(['dir', 'approveLands']);
-const AGENT_KEYS = ['authors', 'labels', 'branchPrefixes', 'bots', 'transport', 'maxOpen', 'profiles', 'runners', 'quietAfter', 'limits'];
+const AGENT_KEYS = ['authors', 'labels', 'branchPrefixes', 'bots', 'transport', 'maxOpen', 'profiles', 'runners', 'quietAfter', 'limits', 'on'];
 const PROFILE_NAME = new RegExp(PROFILE_SOURCE);
 const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 const isText = (v) => typeof v === 'string' && v.trim() !== '';
@@ -237,6 +239,7 @@ export function configProblems(c) {
       }
       if (c.agents.bots !== undefined && typeof c.agents.bots !== 'boolean') out.push('agents.bots is true or false: whether a bot account ("[bot]" or the forge\'s Bot type) counts as an agent.');
       out.push(...agentRunProblems(c.agents));
+      if (isObject(c.agents.on) && c.agents.on['thread.message'] !== undefined && c.threads === false) out.push('agents.on["thread.message"] needs threads, which are off (threads: false): the /agent command is read in a thread.');
     }
   }
   if (c.deploys !== undefined && c.deploys !== null) {
@@ -332,6 +335,30 @@ export function configProblems(c) {
   return out;
 }
 
+/**
+ * What is wrong with `agents.on`, the opt-in triggers (spec 0005 D10): `{ '<event>': { kind, profile?, brief? } }` for the events a
+ * maintainer causes. Off by default (no key, no trigger). `kind` is checked against the contract and `profile` against `agents.profiles`.
+ */
+function triggerProblems(a) {
+  const out = [];
+  const on = a.on;
+  if (!isObject(on)) return [`agents.on is { ${TRIGGER_EVENTS.map((e) => `"${e}": { kind, profile? }`).join(', ')} }: which events request a run by themselves (none unless set).`];
+  const profiles = Array.isArray(a.profiles) ? a.profiles : [];
+  for (const [event, t] of Object.entries(on)) {
+    const at = `agents.on[${JSON.stringify(event)}]`;
+    if (!TRIGGER_EVENTS.includes(event)) { out.push(`${at}: a trigger fires only on ${TRIGGER_EVENTS.join(', ')}: something a maintainer did, never a run's output.`); continue; }
+    if (!isObject(t)) { out.push(`${at} is { kind, profile?, brief? }.`); continue; }
+    for (const k of Object.keys(t)) if (!['kind', 'profile', 'brief'].includes(k)) out.push(`${at}.${k}: the keys are kind, profile, brief.`);
+    if (!RUN_KINDS.includes(t.kind)) out.push(`${at}.kind is one of ${RUN_KINDS.join(', ')}.`);
+    if (t.profile !== undefined && !(typeof t.profile === 'string' && profiles.includes(t.profile))) out.push(`${at}.profile ${JSON.stringify(t.profile)} is not one of agents.profiles (${profiles.join(', ') || 'none listed'}).`);
+    if (t.brief !== undefined && !(typeof t.brief === 'string' && t.brief.length <= MAX_BRIEF_CHARS && !new RegExp(CREDENTIAL_VALUE_SOURCE).test(t.brief))) out.push(`${at}.brief is text of at most ${MAX_BRIEF_CHARS} characters, and holds nothing shaped like a credential.`);
+  }
+  return out;
+}
+
+/** The triggers a config turns on, as `[event, { kind, profile?, brief? }]` (none when off, which is the default) */
+export const triggersOf = (config) => Object.entries(isObject(config.agents?.on) ? config.agents.on : {}).filter(([e]) => TRIGGER_EVENTS.includes(e));
+
 /** What is wrong with the keys of `agents` that ask for and follow runs (spec 0005), in words */
 function agentRunProblems(a) {
   const out = [];
@@ -353,6 +380,7 @@ function agentRunProblems(a) {
     else if (ms < QUIET_MIN_MS) out.push(`agents.quietAfter ${JSON.stringify(a.quietAfter)} is under the floor of 5m; use "5m" or more.`);
     else if (ms > QUIET_MAX_MS) out.push(`agents.quietAfter ${JSON.stringify(a.quietAfter)} is over the ceiling of 30 days; use "720h" or less.`);
   }
+  if (a.on !== undefined) out.push(...triggerProblems(a));
   if (a.limits !== undefined) {
     if (!isObject(a.limits)) out.push('agents.limits is { minutes?, turns?, cost? }: hints the runner may enforce.');
     else {

package/explorer/forge-panel.js

@@ -69,7 +69,7 @@ import { relativeTime } from './review-model.js';
 import { LAYER_DEFS, toggleLayer } from './layers.js';
 import { WORK_URL, groupWork, filterGroups, groupWords, workStatus, markWords } from './agents-model.js';
 import {
-  RUNS_URL, runsUrl, stopUrl, KINDS, aboutWords, statusWords, statusWhy, runMeta, canStop, runsStatus, startBody, startWords, stopWords, confirmStartWords,
+  RUNS_URL, runsUrl, stopUrl, KINDS, aboutWords, statusWords, statusWhy, runMeta, canStop, runsStatus, triggerNotice, startBody, startWords, stopWords, confirmStartWords,
 } from './runs-model.js';
 import {
   STATES, defaultFilters, listUrl, pullUrl, serverState, filterItems, facetsOf, stateWords, metaWords, checkWords, checksWords, litFor, errorWords,
@@ -1002,6 +1002,12 @@ function paintRuns() {
   note.hidden = !words;
   note.className = `hx-forge-notice${!(ui.runs && ui.runs.error) && ui.runNote && ui.runNote.ok ? ' hx-forge-notice--ok' : ''}`;
   note.textContent = words;
+  const trig = $('forge-runs-trigger');
+  if (trig) {
+    const skipped = data ? triggerNotice(data) : '';
+    trig.hidden = !skipped;
+    trig.textContent = skipped;
+  }
   const list = $('forge-runs-list');
   if (!data) { list.innerHTML = ''; return; }
   list.innerHTML = data.runs.length ? data.runs.map(runHtml).join('') : '<li class="hx-forge-empty hx-faint">No agent has been asked for yet. Start one from an issue or a proposal.</li>';

package/explorer/index.html

@@ -270,6 +270,7 @@
           <h3 id="forge-runs-title" class="hx-forge-runs-title">Agent runs</h3>
           <p id="forge-runs-status" class="hx-forge-meta hx-faint"></p>
           <p id="forge-runs-note" class="hx-forge-notice" hidden></p>
+          <p id="forge-runs-trigger" class="hx-forge-notice" hidden></p>
           <ul id="forge-runs-list" class="hx-forge-files" aria-label="Runs"></ul>
         </section>
         <section id="forge-detail" class="hx-forge-detail" aria-label="Selected pull request" hidden></section>

package/explorer/runs-model.js

@@ -64,6 +64,24 @@ export function runMeta(run, nowMs) {
   return parts.join(' · ');
 }
 
+/**
+ * The notice over the runs when an opt-in trigger (`agents.on`) did nothing in the last day, from the audit rows the server counted
+ * (`triggerSkipped`: { count, reasons }), or '' when none did. No live sign-in is the case the person can mend, so it says how.
+ */
+export function triggerNotice(data) {
+  const n = data && data.triggerSkipped;
+  if (!n || !(n.count > 0)) return '';
+  const reasons = n.reasons || {};
+  const out = [];
+  if (reasons['no-session']) out.push('A trigger was skipped: sign in to let triggers request runs.');
+  const refused = Object.entries(reasons).filter(([why]) => why !== 'no-session');
+  if (refused.length) {
+    const count = refused.reduce((sum, [, c]) => sum + c, 0);
+    out.push(`${count} ${count === 1 ? 'trigger was' : 'triggers were'} refused in the last day (${refused.map(([why, c]) => `${why} ${c}`).join(', ')}), so nothing was asked.`);
+  }
+  return out.join(' ');
+}
+
 /** Whether a Stop is offered: the run is open and nobody has asked it to stop yet */
 export const canStop = (run) => run.open === true && !run.stopRequested;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popcorn245/cornfield",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "A self-hostable dev dashboard with the topology map at its centre: proposals on the map, scenarios, outages and what-if edits, for any repo.",
   "license": "MIT",
   "author": "popcorn245 (https://github.com/popcorn245)",

package/server/agent-runs.js

@@ -172,6 +172,8 @@ export function publicRun(row, nowMs, quietMs) {
  * @property {{ auth: object, now?: () => number }} limits what server/throttle.js counts by
  * @property {{ token: { id: number, label: string } } | null} [via] set when the request came through the API: the token it came with
  * @property {() => string | null | Promise<string | null>} [stillAllowed] asked once more just before the cap is taken: null to go on, or why not
+ * @property {{ event: string, ref: string }} [trigger] set only by an opt-in trigger (server/triggers.js): what caused this request. It is written into the
+ *   request (`trigger: { event, by, ref }`, `by` being the maintainer asking) and the audit row, and the run's `via` is 'trigger'. A caller's body can never set it
  */
 
 /**
@@ -216,7 +218,7 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
   }
 
   /** Takes a place for a run: the cap and the one-per-subject rule are checked and the row inserted in one transaction. Throws a `Refused`. */
-  function reserve(db, request, { target, who, via, force }) {
+  function reserve(db, request, { target, who, via, force, trigger = false }) {
     const at = now();
     const mine = subjectKeys(request.refs);
     db.exec('BEGIN IMMEDIATE');
@@ -237,7 +239,7 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
       db.prepare(`INSERT INTO runs (run_id, repo, kind, profile, issue, proposal, thread, target, request, requested_by, requested_by_id, requested_at, via, last_activity, transport)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
         .run(request.runId, repo, request.kind, request.profile ?? null, request.refs.issue ?? null, request.refs.proposal ?? null, request.refs.thread ?? null,
-          target, JSON.stringify(request), request.requestedBy, String(who.userId), request.requestedAt, via ? 'api' : 'dashboard', iso(at), transport);
+          target, JSON.stringify(request), request.requestedBy, String(who.userId), request.requestedAt, via ? 'api' : trigger ? 'trigger' : 'dashboard', iso(at), transport);
       db.exec('COMMIT');
     } catch (err) {
       try { db.exec('ROLLBACK'); } catch { /* nothing was begun */ }
@@ -288,7 +290,9 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
     try {
       if (problem) throw new Refused(problem.status, problem.message, 'invalid');
       if (!isObject(body)) throw new Refused(400, `A request is a JSON object: { kind, refs, profile?, brief?, branch?, limits?, nodes?, force? }.`, 'invalid');
-      const { force, requestedBy, ...fields } = body;
+      const { force, requestedBy, trigger: forged, ...fields } = body;
+      // What caused a request is cornfield's to write, from a trigger's own call; a caller cannot say it was a trigger
+      if (forged !== undefined) throw new Refused(400, '"trigger" is written by cornfield for an automatic request; leave it out.', 'invalid');
       if (force !== undefined && typeof force !== 'boolean') throw new Refused(400, '"force" is true or false: whether to ask for another run on an issue or proposal that has an open one.', 'invalid');
       const build = (login, pull) => {
         // The config's limits are hints the request starts from; what the person sent wins key by key
@@ -298,10 +302,11 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
         else if (isObject(limits)) limits = { ...base, ...limits };
         // The brief is required by the contract and may be empty; the spec PR that holds a proposal is named beside it
         const refs = pull != null && isObject(fields.refs) ? { ...fields.refs, pull } : fields.refs;
-        const made = createRequest({ brief: '', ...fields, refs, ...(limits !== undefined ? { limits } : {}), requestedBy: login }, { profiles, now: at });
+        const made = createRequest({ brief: '', ...fields, refs, ...(limits !== undefined ? { limits } : {}), requestedBy: login, ...(ctx.trigger ? { trigger: { event: ctx.trigger.event, by: login, ref: ctx.trigger.ref } } : {}) }, { profiles, now: at });
         if (!made.ok) throw new Refused(400, made.error, 'invalid');
         return /** @type {RunRequest} */ (made.value);
       };
+      if (ctx.trigger) Object.assign(asked, { trigger: { event: ctx.trigger.event, ref: ctx.trigger.ref } });
       let made = build(who.login);
       runId = made.runId;
       Object.assign(asked, { runId });
@@ -343,6 +348,9 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
         if (via) {
           const [head, ...rest] = comment.split('\n\n');
           comment = [`${head} Sent through the agent API with the token \`${via.token.label}\`.`, ...rest].join('\n\n');
+        } else if (made.trigger) {
+          const [head, ...rest] = comment.split('\n\n');
+          comment = [`${head} Asked by the trigger on ${made.trigger.event} (${made.trigger.ref}), after an act of ${made.trigger.by}'s.`, ...rest].join('\n\n');
         }
       }
 
@@ -352,7 +360,7 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
         if (why) throw new Refused(403, why, 'forbidden');
       }
       const db = await auth.store();
-      reserve(db, made, { target: number, who, via, force: force === true });
+      reserve(db, made, { target: number, who, via, force: force === true, trigger: Boolean(made.trigger) });
       let posted = null;
       if (comment !== null) {
         try {
@@ -487,7 +495,18 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
     const db = await auth.store();
     const at = now();
     const rows = /** @type {RunRow[]} */ (db.prepare(`SELECT * FROM runs WHERE repo = ? AND ${POSTED} ORDER BY requested_at DESC, run_id DESC LIMIT ?`).all(repo, limit));
-    return { runs: rows.map((r) => publicRun(r, at, quietMs)), open: openRows(db, at).length, maxOpen: cap, profiles, limits: agents.limits || {}, quietAfter: agents.quietAfter, runners: [...runnerSet].length };
+    // The dashboard's notice for triggers that did nothing (server/triggers.js writes a `trigger-skipped` row each time): the last day's, by reason
+    const skipped = /** @type {{ at: string, answer: string | null }[]} */ (db.prepare("SELECT at, answer FROM actions WHERE action = 'trigger-skipped' AND (target = ? OR target LIKE ?) AND at > ? ORDER BY id DESC LIMIT 200").all(repo, `${repo}#%`, iso(at - 24 * 3_600_000)));
+    const reasons = {};
+    for (const r of skipped) {
+      let why = 'error';
+      try { why = JSON.parse(r.answer ?? '{}').reason || why; } catch { /* a row that is not JSON is counted as an error */ }
+      reasons[why] = (reasons[why] || 0) + 1;
+    }
+    return {
+      runs: rows.map((r) => publicRun(r, at, quietMs)), open: openRows(db, at).length, maxOpen: cap, profiles, limits: agents.limits || {}, quietAfter: agents.quietAfter, runners: [...runnerSet].length,
+      triggerSkipped: skipped.length ? { count: skipped.length, last: skipped[0].at, reasons } : null,
+    };
   }
 
   /** One run, or null */
@@ -900,7 +919,22 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
     if (gone) log(`${gone} request${gone === 1 ? '' : 's'} that never reached the forge ${gone === 1 ? 'was' : 'were'} dropped`);
   }
 
-  return { request, stop, list, get, follow, hasWork, resume, queued, claim, runnerGet, report, maxOpen: cap, profiles, transport };
+  /**
+   * The open run on a subject, under any profile, or null: one whose request was posted on `number` (its target), or that is about the
+   * same issue, thread or proposal as `refs`. Open as the cap counts it (not finished, not quiet). An opt-in trigger asks before it requests
+   * (server/triggers.js), so a maintainer's act on a target whose run is still going is skipped with `run-open`, whatever the profile.
+   * @param {{ number?: number, refs?: { issue?: number, thread?: number, proposal?: string } }} about
+   * @returns {Promise<string | null>} the run id
+   */
+  async function openOn({ number, refs = {} }) {
+    const db = await auth.store();
+    const mine = subjectKeys(refs);
+    const hit = openRows(db, now()).find((r) => (Number.isInteger(number) && (r.target === number || r.issue === number || r.thread === number))
+      || subjectKeys({ issue: r.issue ?? undefined, thread: r.thread ?? undefined, proposal: r.proposal ?? undefined }).some((k) => mine.includes(k)));
+    return hit ? hit.run_id : null;
+  }
+
+  return { request, stop, list, get, follow, hasWork, resume, queued, claim, runnerGet, report, openOn, maxOpen: cap, profiles, transport };
 }
 
 /** @typedef {ReturnType<typeof createRuns>} Runs */

package/server/forge-actions.js

@@ -255,7 +255,7 @@ export async function serveAction(req, res, what, ctx, send) {
       if (!plan.existing && plan.digest !== digest) throw new ForgeError(`What the build issue for ${slug} would say has changed since it was shown (a new review, or a push); look again.`, { code: 'conflict' });
       const done = await openBuildIssue(forge, plan);
       // Only an issue this ask made is news: a second ask that found the first one's says nothing again
-      if (done.created) ctx.hooks?.emit('build.opened', () => proposalPayload(forge, ctx.where || { proposals: config.proposals }, plan, { actor: session.login }));
+      if (done.created) ctx.hooks?.emit('build.opened', async () => ({ ...(await proposalPayload(forge, ctx.where || { proposals: config.proposals }, plan, { actor: session.login })), issue: done.issue.number }));
       await forgetKept(auth, config);
       out = { status: done.created ? 201 : 200, body: { ok: true, action, created: done.created, number: n, slug, issue: done.issue, path: plan.path } };
     } else if (action === 'merge') {

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');
@@ -150,8 +151,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 +180,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 */