cornfield 0.9.0 → 0.11.0

package/server/agent-runs.js

@@ -57,13 +57,13 @@
  * @typedef {{ run_id: string, repo: string, kind: string, profile: string | null, issue: number | null, proposal: string | null, thread: number | null,
  *   target: number, comment_id: string, comment_url: string | null, request: string, requested_by: string, requested_by_id: string, requested_at: string,
  *   via: string, state: string, reported_at: string | null, reported_by: string | null, note: string | null, url: string | null, tokens: number | null,
- *   cost: number | null, stop_requested_at: string | null, stop_requested_by: string | null, pull: number | null, pull_state: string | null,
+ *   cost: number | null, transport: 'forge' | 'push' | 'pull', claimed_by: number | null, claimed_at: string | null, stop_requested_at: string | null, stop_requested_by: string | null, pull: number | null, pull_state: string | null,
  *   pull_url: string | null, pull_by: string | null, pull_trusted: number, linked_via: string | null, branch: string | null, head_sha: string | null,
  *   checks: string | null, last_activity: string }} RunRow
  */
 
 import { ForgeError, isMaintainer } from './forge.js';
-import { createRequest, findRunId, formatRunComment, runAuthors, runBlocksOf, runIdFromBranch, MAX_NOTE_CHARS } from '../core/agent-contract.js';
+import { createRequest, findRunId, formatRunComment, runAuthors, runBlocksOf, runIdFromBranch, validateReport, validateRequest, MAX_NOTE_CHARS } from '../core/agent-contract.js';
 import { quietAfterMs } from '../core/config.js';
 import { listPullProposals } from './proposal-pulls.js';
 import { Refused, countAttempt, throttle } from './throttle.js';
@@ -81,12 +81,17 @@ export const FOLLOW_FLOOR_MS = 48 * 3_600_000;
 export const RESERVATION_MS = 10 * 60_000;
 /** The runs a listing answers */
 export const LIST_LIMIT = 200;
+/** The queued requests a runner's listing answers at most, oldest first */
+export const QUEUE_LIMIT = 50;
+/** The runs that are over once the runner has said so */
 /** The keys of a request as the API and the button send it: the contract's fields, less what cornfield writes, plus `force` */
 export const REQUEST_BODY_KEYS = Object.freeze(['kind', 'profile', 'refs', 'branch', 'brief', 'limits', 'nodes', 'requestedBy', 'force']);
 
 /** The states in which a run is over for good unless the runner says more */
 export const FINISHED = Object.freeze(['done', 'failed', 'stopped', 'merged', 'closed']);
 const REPORT_FINISHED = ['done', 'failed', 'stopped'];
+/** Where a run is looked up for the dashboard and the poll: posted on the forge, or (push and pull) there is no comment to wait for */
+const POSTED = "(comment_id <> '' OR transport <> 'forge')";
 
 const iso = (ms) => new Date(ms).toISOString();
 const lower = (s) => String(s).toLowerCase();
@@ -149,7 +154,8 @@ export function publicRun(row, nowMs, quietMs) {
   return {
     runId: row.run_id, kind: row.kind, profile: row.profile,
     refs: { ...(row.issue != null ? { issue: row.issue } : {}), ...(row.proposal != null ? { proposal: row.proposal } : {}), ...(row.thread != null ? { thread: row.thread } : {}) },
-    status, open, requestedBy: row.requested_by, requestedAt: row.requested_at, via: row.via, target: row.target,
+    status, open, requestedBy: row.requested_by, requestedAt: row.requested_at, via: row.via, transport: row.transport, target: row.target,
+    claimedAt: row.claimed_at,
     comment: row.comment_id ? { id: row.comment_id, url: row.comment_url } : null,
     limits,
     report: row.reported_at ? { state: row.state, at: row.reported_at, by: row.reported_by, note: row.note, url: row.url, tokens: row.tokens, cost: row.cost } : null,
@@ -166,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
  */
 
 /**
@@ -187,6 +195,8 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
   const runnerSet = new Set((Array.isArray(agents.runners) ? agents.runners : []).map(lower));
   const authorSet = new Set((Array.isArray(agents.authors) ? agents.authors : []).map(lower));
   const quietMs = quietAfterMs(config);
+  /** How requests travel from now on (`agents.transport`); a run keeps the transport it was asked for with */
+  const transport = /** @type {'forge' | 'push' | 'pull'} */ (agents.transport ?? 'forge');
   const log = (what) => console.error(`[cornfield] agent runs: ${what}`);
   let following = null;
 
@@ -204,17 +214,17 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
    */
   function openRows(db, at) {
     return /** @type {RunRow[]} */ (db.prepare("SELECT * FROM runs WHERE repo = ? AND state NOT IN ('done', 'failed', 'stopped') ORDER BY requested_at").all(repo))
-      .filter((r) => (r.comment_id !== '' || at - Date.parse(r.requested_at) < RESERVATION_MS) && statusOf(r, at, quietMs).open);
+      .filter((r) => (r.comment_id !== '' || r.transport !== 'forge' || at - Date.parse(r.requested_at) < RESERVATION_MS) && statusOf(r, at, quietMs).open);
   }
 
   /** 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');
     try {
       // What a crash left (a reservation never posted) is dropped here too, not only at the next start
-      db.prepare("DELETE FROM runs WHERE repo = ? AND comment_id = '' AND requested_at < ?").run(repo, iso(at - RESERVATION_MS));
+      db.prepare("DELETE FROM runs WHERE repo = ? AND comment_id = '' AND transport = 'forge' AND requested_at < ?").run(repo, iso(at - RESERVATION_MS));
       const open = openRows(db, at);
       if (open.length >= cap) {
         throw new Refused(409, `${repo} already has ${open.length} open run${open.length === 1 ? '' : 's'}, the most cornfield asks for (agents.maxOpen is ${cap}): ${open.map((r) => r.run_id).join(', ')}. Wait for one to finish or go quiet, or stop one.`, 'cap-reached');
@@ -226,10 +236,10 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
           throw new Refused(409, `${subjectWords(request.refs)} already has an open run${clash.profile ? ` under the profile ${clash.profile}` : ''}: ${clash.run_id} (${statusOf(clash, at, quietMs).status}). To ask for another on purpose, send "force": true${profiles.length ? ', or pick another profile' : ''}.`, 'run-open');
         }
       }
-      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)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+      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));
+          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 */ }
@@ -255,6 +265,7 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
     }
     if (typeof body.brief === 'string') out.briefChars = body.brief.length;
     if (body.force === true) out.force = true;
+    if (transport !== 'forge') out.transport = transport;
     if (via) Object.assign(out, { via: 'api', token: via.token });
     return out;
   }
@@ -279,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
@@ -289,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 });
@@ -327,10 +341,17 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
         }
       }
       target = `${repo}#${number}`;
-      let comment = formatRunComment(made.runId, made, { profiles });
-      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');
+      // On the forge the request is a comment. On push and pull there is none: the run is recorded and the transport delivers it
+      let comment = null;
+      if (transport === 'forge') {
+        comment = formatRunComment(made.runId, made, { profiles });
+        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');
+        }
       }
 
       // The token once more, after every forge call: one revoked or expired meanwhile does not ask
@@ -339,21 +360,23 @@ 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 });
-      let posted;
-      try {
-        posted = await forge.comment(number, comment);
-      } catch (err) {
-        db.prepare('DELETE FROM runs WHERE run_id = ?').run(made.runId);
-        throw err;
+      reserve(db, made, { target: number, who, via, force: force === true, trigger: Boolean(made.trigger) });
+      let posted = null;
+      if (comment !== null) {
+        try {
+          posted = await forge.comment(number, comment);
+        } catch (err) {
+          db.prepare('DELETE FROM runs WHERE run_id = ?').run(made.runId);
+          throw err;
+        }
+        db.prepare('UPDATE runs SET comment_id = ?, comment_url = ? WHERE run_id = ?').run(posted.id, posted.url ?? null, made.runId);
       }
-      db.prepare('UPDATE runs SET comment_id = ?, comment_url = ? WHERE run_id = ?').run(posted.id, posted.url ?? null, made.runId);
       status = 201;
-      await audit({ login: me.login, action: 'agent-request', target, request: { ...asked, target: number }, status, answer: { comment: posted.id, url: posted.url ?? null } });
+      await audit({ login: me.login, action: 'agent-request', target, request: { ...asked, target: number }, status, answer: posted ? { comment: posted.id, url: posted.url ?? null } : { transport, queued: transport === 'pull' } });
       hooks?.emit('agent.requested', { request: made, actor: me.login });
       try { onAsk?.(); } catch { /* the poll is a convenience */ }
       const row = /** @type {RunRow} */ (db.prepare('SELECT * FROM runs WHERE run_id = ?').get(made.runId));
-      return { run: publicRun(row, now(), quietMs), request: made, comment: { id: posted.id, url: posted.url ?? null, number } };
+      return { run: publicRun(row, now(), quietMs), request: made, comment: posted ? { id: posted.id, url: posted.url ?? null, number } : null };
     } catch (err) {
       if (status === null) {
         const out = describe(err);
@@ -407,30 +430,45 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
         const why = await ctx.stillAllowed();
         if (why) throw new Refused(403, why, 'forbidden');
       }
-      let comment;
-      try {
-        comment = formatRunComment(row.run_id, { state: 'stop-requested', ...(note ? { note } : {}) }, { line: `Asked run \`${row.run_id}\` to stop (${me.login}, in cornfield${via ? `, through the agent API with the token \`${via.token.label}\`` : ''}).` });
-      } catch (err) {
-        throw new Refused(400, words(err), 'invalid');
-      }
-      const posted = await forge.comment(row.target, comment);
       const stamp = iso(now());
+      /** A pull run nobody has claimed has no runner to stop: cornfield ends it itself, saying so (the one `stopped` it writes) */
+      const unclaimed = row.transport === 'pull' && row.claimed_by == null && row.state === 'requested';
+      let posted = null;
+      if (row.transport === 'forge') {
+        let comment;
+        try {
+          comment = formatRunComment(row.run_id, { state: 'stop-requested', ...(note ? { note } : {}) }, { line: `Asked run \`${row.run_id}\` to stop (${me.login}, in cornfield${via ? `, through the agent API with the token \`${via.token.label}\`` : ''}).` });
+        } catch (err) {
+          throw new Refused(400, words(err), 'invalid');
+        }
+        posted = await forge.comment(row.target, comment);
+      }
       // Judged already: the follow that reads this comment back must not fire the hook again
       db.exec('BEGIN IMMEDIATE');
       try {
         db.prepare('UPDATE runs SET stop_requested_at = ?, stop_requested_by = ?, last_activity = MAX(last_activity, ?) WHERE run_id = ?').run(stamp, me.login, stamp, row.run_id);
-        db.prepare('INSERT OR IGNORE INTO run_seen (run_id, key, at) VALUES (?, ?, ?)').run(row.run_id, `c:${posted.id}:${row.run_id}:stop-request:0`, stamp);
-        db.prepare('INSERT OR IGNORE INTO run_seen (run_id, key, at) VALUES (?, ?, ?)').run(row.run_id, `ev:stop:${posted.id}:c:${posted.id}:${row.run_id}:stop-request:0`, stamp);
+        if (posted) {
+          db.prepare('INSERT OR IGNORE INTO run_seen (run_id, key, at) VALUES (?, ?, ?)').run(row.run_id, `c:${posted.id}:${row.run_id}:stop-request:0`, stamp);
+          db.prepare('INSERT OR IGNORE INTO run_seen (run_id, key, at) VALUES (?, ?, ?)').run(row.run_id, `ev:stop:${posted.id}:c:${posted.id}:${row.run_id}:stop-request:0`, stamp);
+        }
+        if (unclaimed) {
+          const ended = db.prepare("UPDATE runs SET state = 'stopped', reported_at = ?, reported_by = ?, note = ? WHERE run_id = ? AND state = 'requested' AND claimed_by IS NULL").run(stamp, me.login, 'Stopped before a runner claimed it.', row.run_id).changes;
+          if (ended !== 1) throw new Refused(409, `Run ${row.run_id} was claimed just now; ask again to stop it.`, 'conflict');
+        }
         db.exec('COMMIT');
       } catch (err) {
         try { db.exec('ROLLBACK'); } catch { /* nothing was begun */ }
         throw err;
       }
       done = true;
-      await audit({ login: me.login, action: 'agent-stop', target, request: { ...asked, ...(note ? { noteChars: note.length } : {}) }, status: 201, answer: { comment: posted.id, url: posted.url ?? null } });
+      await audit({ login: me.login, action: 'agent-stop', target, request: { ...asked, ...(note ? { noteChars: note.length } : {}) }, status: 201, answer: posted ? { comment: posted.id, url: posted.url ?? null } : { transport: row.transport, ...(unclaimed ? { stopped: true } : {}) } });
       const after = /** @type {RunRow} */ (db.prepare('SELECT * FROM runs WHERE run_id = ?').get(row.run_id));
       hooks?.emit('run.stopRequested', runPayload(after, me.login));
-      return { run: publicRun(after, now(), quietMs), comment: { id: posted.id, url: posted.url ?? null } };
+      if (unclaimed) {
+        hooks?.emit('run.state', { ...runPayload(after, me.login), state: 'stopped' });
+        hooks?.emit('run.finished', { ...runPayload(after, me.login), state: 'stopped' });
+      }
+      return { run: publicRun(after, now(), quietMs), comment: posted ? { id: posted.id, url: posted.url ?? null } : null };
     } catch (err) {
       if (!done) {
         const out = describe(err);
@@ -456,21 +494,32 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
   async function list({ limit = LIST_LIMIT } = {}) {
     const db = await auth.store();
     const at = now();
-    const rows = /** @type {RunRow[]} */ (db.prepare("SELECT * FROM runs WHERE repo = ? AND comment_id <> '' 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 };
+    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));
+    // 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 */
   async function get(runId) {
     const db = await auth.store();
-    const row = typeof runId === 'string' ? /** @type {RunRow | undefined} */ (db.prepare("SELECT * FROM runs WHERE run_id = ? AND repo = ? AND comment_id <> ''").get(runId, repo)) : undefined;
+    const row = typeof runId === 'string' ? /** @type {RunRow | undefined} */ (db.prepare(`SELECT * FROM runs WHERE run_id = ? AND repo = ? AND ${POSTED}`).get(runId, repo)) : undefined;
     return row ? publicRun(row, now(), quietMs) : null;
   }
 
   /** The runs a follow looks at: posted, not over for good (a trusted pull request merged or closed), and active within the follow window */
   function followable(db, at) {
     const window = Math.max(2 * quietMs, FOLLOW_FLOOR_MS);
-    return /** @type {RunRow[]} */ (db.prepare("SELECT * FROM runs WHERE repo = ? AND comment_id <> '' AND last_activity > ? AND NOT (pull_trusted = 1 AND pull_state IN ('merged', 'closed')) ORDER BY last_activity DESC LIMIT ?")
+    return /** @type {RunRow[]} */ (db.prepare(`SELECT * FROM runs WHERE repo = ? AND ${POSTED} AND last_activity > ? AND NOT (pull_trusted = 1 AND pull_state IN ('merged', 'closed')) ORDER BY last_activity DESC LIMIT ?`)
       .all(repo, iso(at - window), MAX_FOLLOWED));
   }
 
@@ -607,7 +656,8 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
     // ---- the comments -----------------------------------------------------
     /** @type {Map<number, Set<string>>} */
     const places = new Map();
-    for (const r of cur.values()) for (const n of [r.target, r.pull]) if (n != null) places.set(n, (places.get(n) ?? new Set()).add(r.run_id));
+    // A run asked for over push or pull is reported to over the API, with a runner token: a comment on the forge does not move it
+    for (const r of cur.values()) if (r.transport === 'forge') for (const n of [r.target, r.pull]) if (n != null) places.set(n, (places.get(n) ?? new Set()).add(r.run_id));
     /** @type {{ row: RunRow, id: string, key: string, at: string, by: string | null, block: any }[]} */
     const heard = [];
     for (const [number, ids] of places) {
@@ -756,14 +806,135 @@ export function createRuns({ config, where, auth, hooks = null, now = Date.now,
     return out;
   }
 
+  // -------------------------------------------------------------------------
+  //  Runners: pull and push (a runner token, server/runner-api.js; spec 0005 D2, D5)
+  // -------------------------------------------------------------------------
+
+  /** @typedef {{ id: number, label: string }} RunnerToken the runner token a call came with */
+
+  const runnerActor = (token) => `runner:${token.label}`;
+
+  /** A run for a runner: the state it is in as cornfield derives it, and whether a maintainer asked it to stop. Nothing else about the run, no credential */
+  function runnerView(row) {
+    const st = statusOf(row, now(), quietMs);
+    return { runId: row.run_id, state: st.status, reported: row.state === 'requested' ? null : row.state, stopRequested: row.stop_requested_at != null, ...(row.stop_requested_at ? { stopRequestedAt: row.stop_requested_at } : {}), open: st.open, finished: st.finished };
+  }
+
+  /** The run a runner token names, or a `Refused`: 404 when there is none, 403 when the token may not touch it */
+  function runnerRun(db, token, runId) {
+    const row = typeof runId === 'string' ? /** @type {RunRow | undefined} */ (db.prepare(`SELECT * FROM runs WHERE run_id = ? AND repo = ? AND ${POSTED}`).get(runId, repo)) : undefined;
+    if (!row) throw new Refused(404, 'cornfield has no such run.', 'not-found');
+    if (row.transport === 'forge') throw new Refused(403, 'This run was asked for on the forge, not over push or pull. A runner token does not reach it: report it as a cornfield-run comment.', 'forbidden');
+    if (row.transport === 'pull' && row.claimed_by == null) throw new Refused(403, 'Nobody has claimed this run. Claim it first: POST /api/agent-requests/<runId>/claim.', 'forbidden');
+    if (row.claimed_by != null && row.claimed_by !== token.id) throw new Refused(403, 'Another runner token holds this run. Only the token that claimed it (for a pushed run, the first to report on it) reads and reports on it.', 'forbidden');
+    return row;
+  }
+
+  /**
+   * The requests waiting for a runner to claim: pull runs nobody has claimed, not asked to stop, not quiet, oldest first, at most `QUEUE_LIMIT`.
+   * Each is the contract's request as it was made, checked once more on the way out.
+   */
+  async function queued() {
+    const db = await auth.store();
+    const at = now();
+    const rows = /** @type {RunRow[]} */ (db.prepare("SELECT * FROM runs WHERE repo = ? AND transport = 'pull' AND state = 'requested' AND claimed_by IS NULL AND stop_requested_at IS NULL AND last_activity > ? ORDER BY requested_at, run_id LIMIT ?")
+      .all(repo, iso(at - quietMs), QUEUE_LIMIT));
+    return rows.flatMap((r) => {
+      const checked = validateRequest(safeJson(r.request));
+      if (!checked.ok) { log(`the request ${r.run_id} is not a valid request any more and is not offered: ${checked.error}`); return []; }
+      return [checked.value];
+    });
+  }
+
+  const safeJson = (text) => { try { return JSON.parse(text); } catch { return null; } };
+
+  /**
+   * Claims a queued request for a runner token. ONE statement decides who wins (`UPDATE … WHERE claimed_by IS NULL`), so two claims at once
+   * cannot both succeed: the second is a 409. Answers the request and the run as the runner sees it.
+   * @param {RunnerToken} token
+   * @param {unknown} runId
+   */
+  async function claim(token, runId) {
+    const db = await auth.store();
+    const at = now();
+    const stamp = iso(at);
+    const won = typeof runId === 'string' ? db.prepare(`UPDATE runs SET claimed_by = ?, claimed_at = ?, state = 'claimed', reported_at = ?, reported_by = ?, note = NULL, last_activity = MAX(last_activity, ?)
+      WHERE run_id = ? AND repo = ? AND transport = 'pull' AND state = 'requested' AND claimed_by IS NULL AND stop_requested_at IS NULL AND last_activity > ?`)
+      .run(token.id, stamp, stamp, token.label, stamp, runId, repo, iso(at - quietMs)).changes === 1 : false;
+    const row = typeof runId === 'string' ? /** @type {RunRow | undefined} */ (db.prepare('SELECT * FROM runs WHERE run_id = ? AND repo = ?').get(runId, repo)) : undefined;
+    if (!row) throw new Refused(404, 'cornfield has no such request.', 'not-found');
+    if (!won) {
+      if (row.transport !== 'pull') throw new Refused(409, `This request goes over ${row.transport === 'push' ? 'push (an agent.requested hook event), not pull' : 'the forge, not pull'}; there is nothing to claim.`, 'conflict');
+      if (row.claimed_by != null) throw new Refused(409, 'Another runner claimed this request first.', 'already-claimed');
+      if (row.stop_requested_at) throw new Refused(409, 'A maintainer asked to stop this run before anyone claimed it.', 'conflict');
+      if (statusOf(row, at, quietMs).quiet) throw new Refused(409, 'This request has waited past agents.quietAfter and is no longer offered.', 'conflict');
+      throw new Refused(409, `This request is ${row.state}; there is nothing to claim.`, 'conflict');
+    }
+    const checked = validateRequest(safeJson(row.request));
+    hooks?.emit('run.claimed', { ...runPayload(row, runnerActor(token)), state: 'claimed' });
+    hooks?.emit('run.state', { ...runPayload(row, runnerActor(token)), state: 'claimed' });
+    return { request: checked.ok ? checked.value : null, run: runnerView(row), row };
+  }
+
+  /** One run as the runner that holds it sees it: `GET /api/runs/<runId>`, how a runner learns it was asked to stop */
+  async function runnerGet(token, runId) {
+    const db = await auth.store();
+    return runnerView(runnerRun(db, token, runId));
+  }
+
+  /**
+   * A runner's report: the contract's report JSON, from the token that holds the run (the one that claimed it; for a pushed run, the first to
+   * report). The same run state and hooks as a report on the forge. A run that is over takes no more.
+   * @param {RunnerToken} token
+   * @param {unknown} runId
+   * @param {unknown} body
+   */
+  async function report(token, runId, body) {
+    const db = await auth.store();
+    const row = runnerRun(db, token, runId);
+    const checked = validateReport(body);
+    if (!checked.ok) throw new Refused(400, checked.error, 'invalid');
+    const r = checked.value;
+    const at = now();
+    const was = statusOf(row, at, quietMs);
+    if (was.finished) throw new Refused(409, `Run ${row.run_id} is ${was.status}; it takes no more reports.`, 'conflict');
+    const stamp = iso(at);
+    const changed = db.prepare(`UPDATE runs SET state = ?, reported_at = ?, reported_by = ?, note = ?, url = ?, tokens = COALESCE(?, tokens), cost = COALESCE(?, cost),
+      claimed_by = COALESCE(claimed_by, ?), claimed_at = COALESCE(claimed_at, ?), last_activity = MAX(last_activity, ?)
+      WHERE run_id = ? AND (claimed_by IS NULL OR claimed_by = ?) AND state NOT IN ('done', 'failed', 'stopped')`)
+      .run(r.state, stamp, token.label, r.note ?? null, r.url ?? null, r.tokens ?? null, r.cost ?? null, token.id, stamp, stamp, row.run_id, token.id).changes;
+    if (changed !== 1) throw new Refused(409, `Run ${row.run_id} changed while the report was being taken; read it again (GET /api/runs/${row.run_id}).`, 'conflict');
+    const after = /** @type {RunRow} */ (db.prepare('SELECT * FROM runs WHERE run_id = ?').get(row.run_id));
+    const actor = runnerActor(token);
+    if (r.state === 'claimed' && row.state !== 'claimed') hooks?.emit('run.claimed', { ...runPayload(after, actor), state: r.state });
+    if (r.state !== row.state) hooks?.emit('run.state', { ...runPayload(after, actor), state: r.state });
+    if (REPORT_FINISHED.includes(r.state)) hooks?.emit('run.finished', { ...runPayload(after, actor), state: r.state });
+    return { run: runnerView(after), row: after, was: row };
+  }
+
   /** Drops what a crash left: a request that was never posted. Run once at start. */
   async function resume() {
     const db = await auth.store();
-    const gone = db.prepare("DELETE FROM runs WHERE comment_id = '' AND requested_at < ?").run(iso(now() - RESERVATION_MS)).changes;
+    const gone = db.prepare("DELETE FROM runs WHERE comment_id = '' AND transport = 'forge' AND requested_at < ?").run(iso(now() - RESERVATION_MS)).changes;
     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, maxOpen: cap, profiles };
+  /**
+   * 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/auth.js

@@ -42,6 +42,7 @@ import { createCipheriv, createDecipheriv, createHash, createHmac, hkdfSync, ran
 import { createForge as defaultCreateForge, isMaintainer, ForgeError } from './forge.js';
 import { githubApiUrl } from './forge-github.js';
 import { sameOrigin } from './proposals.js';
+import { revokeOwnerTokens } from './review-tokens.js';
 
 /** How often a session's permission is asked of the forge again */
 export const RECHECK_MS = 15 * 60 * 1000;
@@ -335,6 +336,8 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
       forgeFor: () => { throw new Error('Sign-in is not configured.'); },
       forgeForUser: async () => { throw new Error('Sign-in is not configured.'); },
       record: async () => { throw new Error('Sign-in is not configured.'); },
+      knownPermission: async () => null,
+      demoted: async () => {},
       begin: async () => { throw new Error('Sign-in is not configured.'); },
       finish: async () => { throw new Error('Sign-in is not configured.'); },
       store: null,
@@ -610,6 +613,19 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
       return true;
     };
     const due = () => expiresAt !== null && Date.parse(expiresAt) - REFRESH_SKEW_MS <= now();
+    /** Who the forge says this token is: the login a `permission` question about the owner names */
+    let ownLogin = row.login;
+    /**
+     * What the call answered, looked at once on its way out: when the forge says the owner themself does not maintain the repo, their API
+     * tokens (review, agent, runner) are revoked there and then, wherever in cornfield the question was asked
+     */
+    const noted = async (prop, args, result) => {
+      if (prop === 'me' && result && typeof result.login === 'string') ownLogin = result.login;
+      if (prop === 'permission' && args[0] === forgeConfig.repo && typeof args[1] === 'string' && args[1].toLowerCase() === ownLogin.toLowerCase() && !isMaintainer(result)) {
+        await demoted(row.user_id, ownLogin, result);
+      }
+      return result;
+    };
     return new Proxy({}, {
       get(_, prop) {
         const member = forge[prop];
@@ -625,18 +641,40 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
             }
           }
           try {
-            return await forge[prop](...args);
+            return await noted(prop, args, await forge[prop](...args));
           } catch (err) {
             if (!(err instanceof ForgeError) || err.code !== 'unauthorized') throw err;
             // The forge refused the token: renew it (when it can be) and ask once more; else its refusal stands
             if (!(await renewNow())) throw err;
           }
-          return forge[prop](...args);
+          return noted(prop, args, await forge[prop](...args));
         };
       },
     });
   }
 
+  /**
+   * A token owner the forge says no longer maintains the repo: every API token of theirs (review, agent and runner) is revoked at once, and
+   * the revoking is a row in the audit table. Never throws: what learned it goes on with its own answer.
+   * @param {string} userId
+   * @param {string} login
+   * @param {string} permission what the forge said
+   */
+  async function demoted(userId, login, permission) {
+    try {
+      const n = revokeOwnerTokens(await store(), userId, now());
+      if (!n) return;
+      try {
+        (await store()).prepare('INSERT INTO actions (at, login, action, target, request, status, answer) VALUES (?, ?, ?, ?, ?, ?, ?)')
+          .run(iso(now()), login, 'token-revoke', forgeConfig.repo, JSON.stringify({ reason: 'owner-not-maintainer', permission }), null, JSON.stringify({ revoked: n }));
+      } catch (err) {
+        console.error(`[cornfield] the revoking of ${login}'s tokens could not be written to the audit table: ${err instanceof Error ? err.message : err}`);
+      }
+    } catch (err) {
+      console.error(`[cornfield] the tokens of ${login}, no longer a maintainer, could not be revoked: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+
   async function callback(req, res, url) {
     // The state cookie is cleared only by an answer to the sign-in it belongs to: a link from anywhere else
     // (`/auth/callback?error=x`) cannot cancel one in progress
@@ -668,7 +706,11 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
     file.prepare('INSERT INTO sessions (id, forge, user_id, login, token, permission, created_at, checked_at, expires_at, refresh_token, token_expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
       .run(id, forgeConfig.type, String(user.id), user.login, keep ? sealFor(id, 'token', token) : NO_TOKEN, permission, iso(at), iso(at), iso(at + sessionMs),
         keep && given.refreshToken !== '' ? sealFor(id, 'refresh_token', given.refreshToken) : '', keep ? given.expiresAt : null);
-    if (!keep) await revoke(token);
+    if (!keep) {
+      await revoke(token);
+      // Signed in, and not a maintainer: whatever API tokens they made while they were one stop working now
+      await demoted(String(user.id), user.login, permission);
+    }
     redirect(res, '/', [cookie(SESSION_COOKIE, value, { maxAge: sessionMs / 1000, secure }), clearState]);
   }
 
@@ -740,6 +782,19 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
      * decides what happens when this throws (the action it records has usually happened already).
      * @param {{ login: string, action: string, target: string, request?: object, status?: number | null, answer?: object | null }} entry
      */
+    /**
+     * What cornfield last heard of a user's permission on the repo: their newest sign-in's (asked of the forge at sign-in and every 15 minutes
+     * while they use cornfield), or null when it has no sign-in of theirs at all. A runner token is not asked of the forge per call; this is its
+     * cheap guard (server/runner-api.js).
+     * @param {string} userId
+     * @returns {Promise<string | null>}
+     */
+    async knownPermission(userId) {
+      const row = /** @type {{ permission: string } | undefined} */ ((await store()).prepare('SELECT permission FROM sessions WHERE user_id = ? ORDER BY checked_at DESC, rowid DESC LIMIT 1').get(String(userId)));
+      return row ? row.permission : null;
+    },
+    /** Revokes a user's API tokens when cornfield has learned they no longer maintain the repo (see `demoted`) */
+    demoted,
     async record({ login, action, target, request = {}, status = null, answer = null }) {
       (await store()).prepare('INSERT INTO actions (at, login, action, target, request, status, answer) VALUES (?, ?, ?, ?, ?, ?, ?)')
         .run(iso(now()), login, action, target, JSON.stringify(request), status, answer === null ? null : JSON.stringify(answer));

package/server/db.js

@@ -17,6 +17,7 @@
  *                 a row with `issue = 0` says the repo's threads have been looked at once
  *   runs          the agent runs cornfield asked for: the request, where it was posted, the latest report, the pull request found for
  *                 it and when anything last happened (server/agent-runs.js, migration 7); review_tokens also keep a scope
+ *                 (review, agent, or runner: migration 8, which also gives a run its transport and the runner token that claimed it)
  *   run_seen      what has been seen of each run (a comment judged, a hook event sent), so a restart sends and judges nothing twice
  *                 sessions also keep a forge refresh token, the access token's expiry and when `session.expiring` was sent (migration 5)
  *
@@ -201,6 +202,36 @@ export const MIGRATIONS = Object.freeze([
     PRIMARY KEY (run_id, key)
   ) STRICT;
   `,
+  // 8: push and pull transports, and runner tokens (server/agent-runs.js, server/runner-api.js, spec 0005 D2, D5): a run records how its request
+  // travels and which runner token claimed it; the token scope check gains 'runner'. SQLite cannot change a CHECK, so review_tokens is rebuilt
+  // (the documented way: a new table, the rows copied with their ids, the old one dropped, the new one renamed) and keeps its id sequence
+  `
+  ALTER TABLE runs ADD COLUMN transport  TEXT NOT NULL DEFAULT 'forge' CHECK (transport IN ('forge', 'push', 'pull'));  -- how the request reaches the runner; a push or pull run has no request comment (comment_id stays '')
+  ALTER TABLE runs ADD COLUMN claimed_by INTEGER;   -- the runner token (review_tokens.id) that claimed a pull run, or that first reported on a push run
+  ALTER TABLE runs ADD COLUMN claimed_at TEXT;
+  CREATE INDEX runs_queue ON runs (repo, transport, state, requested_at);
+
+  CREATE TABLE review_tokens_new (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    token_hash  TEXT NOT NULL UNIQUE,
+    user_id     TEXT NOT NULL,
+    login       TEXT NOT NULL,
+    label       TEXT NOT NULL,
+    created_at  TEXT NOT NULL,
+    expires_at  TEXT NOT NULL,
+    revoked_at  TEXT,
+    last_used   TEXT,
+    scope       TEXT NOT NULL DEFAULT 'review' CHECK (scope IN ('review', 'agent', 'runner'))  -- what the token may call: POST /api/reviews, POST /api/agent-requests, or the runner routes
+  ) STRICT;
+  INSERT INTO review_tokens_new (id, token_hash, user_id, login, label, created_at, expires_at, revoked_at, last_used, scope)
+    SELECT id, token_hash, user_id, login, label, created_at, expires_at, revoked_at, last_used, scope FROM review_tokens;
+  UPDATE sqlite_sequence SET seq = MAX(seq, COALESCE((SELECT seq FROM sqlite_sequence WHERE name = 'review_tokens'), 0)) WHERE name = 'review_tokens_new';
+  INSERT INTO sqlite_sequence (name, seq) SELECT 'review_tokens_new', seq FROM sqlite_sequence WHERE name = 'review_tokens'
+    AND NOT EXISTS (SELECT 1 FROM sqlite_sequence WHERE name = 'review_tokens_new');
+  DROP TABLE review_tokens;
+  ALTER TABLE review_tokens_new RENAME TO review_tokens;
+  CREATE INDEX review_tokens_user_id ON review_tokens (user_id);
+  `,
 ]);
 
 /** The version a file is at: its `user_version` */

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') {