cornfield 0.7.0 → 0.8.0

package/server/forge-actions.js

@@ -37,11 +37,17 @@
  * (server/db.js), begun before anything is asked of the forge and finished with the answer after (`auth.begin`,
  * `auth.finish`). Without an audit to write to nothing is done.
  *
+ * One more write is not about a pull request: **a new idea** (docs/threads.md), `POST /api/forge/threads { title, body }`, which opens an issue
+ * with the threads label as the signed-in maintainer (`serveIdea`, below). It goes through the same doors, in the same order:
+ * POST, signed in, the flood ceiling, an audit row begun, same origin, JSON (here up to 32 KB), not twice, the permission asked of
+ * the forge now. The row keeps the title and the text's length, never the text. It only adds: an issue, and on Forgejo the
+ * threads label first when the repo lacks it (the answer, and so the row, says `labelsMade`).
+ *
  * A pull request lands by the config's `forge.mergeMethod` (`merge`, `squash` or `rebase`; `merge` when unset), the way
  * the repo lands its pull requests; the forge refuses a method the repo does not allow, in its own words.
  */
 
-import { ForgeError, RERUN_STATES, canRerun, isMaintainer } from './forge.js';
+import { ForgeError, RERUN_STATES, canRerun, isMaintainer, hasAdapter } from './forge.js';
 import { sameOrigin } from './proposals.js';
 import { planSpec, planBuild, startSpec, openBuildIssue } from './pipeline.js';
 import { PROPOSAL_FILE } from './files.js';
@@ -50,19 +56,22 @@ import { Refused, throttle, countAttempt } from './throttle.js';
 // The limits live in server/throttle.js (reviews share them); these are re-exported for the callers that always had them here
 export { COOLDOWN_MS, PER_MINUTE, ATTEMPTS_PER_MINUTE, countAttempt } from './throttle.js';
 import { proposalPayload, landedPayload } from './hooks.js';
+import { ideaInput, createIdea, threadsOff } from './threads.js';
 
 /** A request body is a sha and a check's id */
 const MAX_BODY = 4096;
+/** A new idea's request: a title and a text of up to 20,000 characters, in JSON (any of it may be escaped) */
+const IDEA_BODY = 96 * 1024;
 
 const STATUS = { unauthorized: 401, forbidden: 403, 'not-found': 404, conflict: 409, invalid: 400, 'rate-limited': 429, unavailable: 502, 'not-green': 409, 'too-large': 413 };
 const SHA = /^[0-9a-f]{7,64}$/i;
 const DIGEST = /^[0-9a-f]{32}$/;
 /** What each action is called in the words of a refusal, and what it asks of the person */
-const DOING = { merge: 'Landing', rerun: 'Re-running', spec: 'Starting a spec', build: 'Opening the build issue' };
-const ONLY_MAINTAINERS = { merge: 'land pull requests or re-run checks', rerun: 'land pull requests or re-run checks', spec: 'start specs', build: 'open build issues' };
+const DOING = { merge: 'Landing', rerun: 'Re-running', spec: 'Starting a spec', build: 'Opening the build issue', idea: 'Opening an idea' };
+const ONLY_MAINTAINERS = { merge: 'land pull requests or re-run checks', rerun: 'land pull requests or re-run checks', spec: 'start specs', build: 'open build issues', idea: 'open ideas' };
 
 /** Reads a small JSON object body, or refuses */
-function readJson(req) {
+function readJson(req, max = MAX_BODY) {
   return new Promise((resolve, reject) => {
     if (!/^application\/json(?:\s*;|$)/i.test(String(req.headers['content-type'] || ''))) {
       req.resume();
@@ -75,7 +84,7 @@ function readJson(req) {
     req.on('data', (c) => {
       if (over) return;
       size += c.length;
-      if (size <= MAX_BODY) { chunks.push(c); return; }
+      if (size <= max) { chunks.push(c); return; }
       // Too large: answered now, and the rest is not read (the connection closes once the answer is sent)
       over = true;
       req.pause();
@@ -289,3 +298,95 @@ export async function serveAction(req, res, what, ctx, send) {
   if (closeAfter) res.on('finish', () => req.destroy());
   send(out.status, out.body, out.headers);
 }
+
+/**
+ * POST /api/forge/threads { title, body }: a new idea, an issue with the threads label, opened as the signed-in maintainer. The
+ * caller has found the path and the method to be this; every refusal is in words and written down, as in `serveAction`.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {{ config: any, session: { login: string, userId: string } | null, auth: { store: null | (() => Promise<import('node:sqlite').DatabaseSync>), forgeFor: Function, begin: Function, finish: Function }, now?: () => number, publicHost?: string | null }} ctx
+ * @param {(status: number, body: object, headers?: object) => void} send
+ */
+export async function serveIdea(req, res, ctx, send) {
+  const { config, session, auth, now = Date.now } = ctx;
+  if (!config.forge || !hasAdapter(config.forge.type)) {
+    req.resume();
+    return send(config.forge ? 501 : 404, { ok: false, error: config.forge ? `cornfield has no adapter for the forge type ${JSON.stringify(config.forge.type)} yet.` : 'No forge is configured: set `forge` in cornfield.config.js.', code: config.forge ? 'unavailable' : 'not-found' });
+  }
+  if (threadsOff(config)) {
+    req.resume();
+    return send(404, { ok: false, error: 'Threads are off in this config (threads: false).', code: 'not-found' });
+  }
+  if (!session || !auth.store) {
+    req.resume();
+    return send(403, { ok: false, error: `${DOING.idea} is done as the signed-in maintainer: set up sign-in first (docs/sign-in.md).`, code: 'forbidden' });
+  }
+  const flood = countAttempt(ctx, session.userId, now());
+  if (flood) {
+    req.resume();
+    return send(flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
+  }
+  const target = config.forge.repo;
+  /** @type {Record<string, unknown>} */
+  const request = { action: 'idea' };
+  let rowId = null;
+  let closeAfter = false;
+  let release = () => {};
+  /** @type {{ status: number, body: object, headers?: object, forgeStatus?: number | null }} */
+  let out;
+  try {
+    try {
+      rowId = await auth.begin({ login: session.login, action: 'idea', target, request });
+    } catch (err) {
+      console.error(`[cornfield] the audit row of idea ${target} could not be written: ${err instanceof Error ? err.message : err}`);
+      throw new Refused(503, 'cornfield cannot write its audit log, so it will not act on the forge.', 'unavailable');
+    }
+    if (!sameOrigin(req, ctx.publicHost ?? null)) {
+      req.resume();
+      throw new Refused(403, 'Do this from cornfield\'s own page.', 'forbidden');
+    }
+    let asked;
+    try {
+      asked = await readJson(req, IDEA_BODY);
+    } catch (err) {
+      closeAfter = Boolean(err && err.closeAfter);
+      throw err;
+    }
+    let idea;
+    try {
+      idea = ideaInput(asked);
+    } catch (err) {
+      throw new Refused(400, err instanceof Error ? err.message : 'That is not an idea.', 'invalid');
+    }
+    // The audit keeps what was asked for, not the words: the title, and how long the text was
+    request.title = idea.title;
+    request.bodyLength = idea.body.length;
+    release = throttle(ctx, session.userId, `idea|${idea.title.toLowerCase().slice(0, 80)}`, now());
+    const forge = auth.forgeFor(session);
+    await assertMaintainerNow(forge, session, config, 'idea');
+    const issue = await createIdea(forge, config, idea);
+    await forgetKept(auth, config);
+    // A label the forge did not have yet and that cornfield made for it (Forgejo) is part of the answer, and so of the audit row
+    out = { status: 201, body: { ok: true, action: 'idea', created: true, number: issue.number, issue: { number: issue.number, title: issue.title, url: issue.url }, ...(issue.labelsMade ? { labelsMade: issue.labelsMade } : {}) } };
+  } catch (err) {
+    if (err instanceof Refused) out = { status: err.status, body: { ok: false, error: err.message, code: err.code }, headers: err.headers };
+    else if (err instanceof ForgeError) {
+      const wait = err.rateLimit && err.rateLimit.retryAfter != null ? { 'Retry-After': String(Math.ceil(err.rateLimit.retryAfter)) } : {};
+      out = { status: STATUS[err.code] || 502, body: { ok: false, error: err.message, code: err.code }, headers: wait, forgeStatus: err.status ?? (err.code === 'unavailable' ? null : STATUS[err.code] || null) };
+    } else {
+      out = { status: 500, body: { ok: false, error: 'Something went wrong in cornfield; the log says what.', code: 'unavailable' } };
+      console.error(`[cornfield] idea ${target}: ${err instanceof Error ? err.stack || err.message : err}`);
+    }
+  } finally {
+    release();
+  }
+  if (rowId !== null) {
+    try {
+      await auth.finish(rowId, { target, request, status: 'forgeStatus' in out ? out.forgeStatus ?? null : out.status, answer: out.body });
+    } catch (err) {
+      console.error(`[cornfield] the audit row of idea ${target} could not be finished: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  if (closeAfter) res.on('finish', () => req.destroy());
+  send(out.status, out.body, out.headers);
+}

package/server/forge-forgejo.js

@@ -9,7 +9,8 @@
  *   - **Permission.** Forgejo has three levels, so a repo's people are `admin`, `write` or `read` and never
  *     `maintain` or `triage`; its admins are cornfield's. The signed-in user's own comes from the repo itself
  *     (`permissions`); anyone else's from the collaborator endpoint, which only a repo admin may ask (else 403).
- *   - **Issues.** `type=issues` leaves the pull requests out.
+ *   - **Issues.** `type=issues` leaves the pull requests out. A new issue's labels are given as ids (Forgejo's API takes no names),
+ *     so each is looked up and made when the repo lacks it.
  *   - **Checks.** Forgejo Actions reports each job as a commit status, so the commit's statuses are all the checks
  *     there are. Its API cannot re-run one: none is `rerunnable`.
  *   - **Runs.** `actions/runs` (Forgejo 11 and later, Gitea 1.24 and later), where Actions is on for the repo; an older
@@ -142,6 +143,17 @@ export function createForgejoForge(forge, { token = null, fetch, apiUrl, timeout
     return meOnce;
   };
 
+  /**
+   * The id of the repo's label called `name`, making the label (plain grey) when it is not there: `{ id, made }`. Only
+   * `createIssue` calls this, so a label is only ever made on a write the maintainer asked for, never on a read.
+   */
+  async function labelId(name) {
+    const have = (await client.list(`repos/${repo}/labels?limit=${PER_PAGE}`, { what: `the labels of ${forge.repo}` })).find((l) => typeof l.name === 'string' && l.name.toLowerCase() === name.toLowerCase());
+    if (have) return { id: have.id, made: false };
+    const { body } = await client.request('POST', `repos/${repo}/labels`, { body: { name, color: '#ededed' }, what: `the label ${name} in ${forge.repo}` });
+    return { id: body.id, made: true };
+  }
+
   return {
     me,
 
@@ -208,16 +220,25 @@ export function createForgejoForge(forge, { token = null, fetch, apiUrl, timeout
       return toPull((await client.request('POST', `repos/${repo}/pulls`, { body: { title: draft ? `WIP: ${title}` : title, body, head, base }, what: `a pull request in ${forge.repo}` })).body);
     },
 
-    async createIssue({ title, body }) {
-      return toIssue((await client.request('POST', `repos/${repo}/issues`, { body: { title, body }, what: `an issue in ${forge.repo}` })).body);
+    async createIssue({ title, body, labels = [] }) {
+      // Forgejo takes label ids, not names: each is looked up, and made when the repo lacks it; the issue says which were made
+      const ids = [];
+      const made = [];
+      for (const name of labels) {
+        const label = await labelId(name);
+        ids.push(label.id);
+        if (label.made) made.push(name);
+      }
+      const issue = toIssue((await client.request('POST', `repos/${repo}/issues`, { body: { title, body, ...(ids.length ? { labels: ids } : {}) }, what: `an issue in ${forge.repo}` })).body);
+      return made.length ? { ...issue, labelsMade: made } : issue;
     },
 
     async pullFiles(n) {
       return (await client.list(`repos/${repo}/pulls/${n}/files?limit=${PER_PAGE}`, { what: `the files of ${pullWhat(n)}` })).map(toFile);
     },
 
-    async comments(n) {
-      return (await client.list(`repos/${repo}/issues/${n}/comments?limit=${PER_PAGE}`, { what: `the comments on #${n} in ${forge.repo}` })).map(toComment);
+    async comments(n, { since } = {}) {
+      return (await client.list(`repos/${repo}/issues/${n}/comments?limit=${PER_PAGE}${since ? `&since=${enc(since)}` : ''}`, { what: `the comments on #${n} in ${forge.repo}` })).map(toComment);
     },
 
     async comment(n, body) {

package/server/forge-github.js

@@ -221,16 +221,17 @@ export function createGitHubForge(forge, { token = null, fetch, apiUrl, timeoutM
       return toPull((await client.request('POST', `repos/${repo}/pulls`, { body: { title, body, head, base, draft }, what: `a pull request in ${forge.repo}` })).body);
     },
 
-    async createIssue({ title, body }) {
-      return toIssue((await client.request('POST', `repos/${repo}/issues`, { body: { title, body }, what: `an issue in ${forge.repo}` })).body);
+    async createIssue({ title, body, labels = [] }) {
+      // GitHub makes a label that is not there yet when the label's name comes with a new issue (the user pushes to the repo)
+      return toIssue((await client.request('POST', `repos/${repo}/issues`, { body: { title, body, ...(labels.length ? { labels } : {}) }, what: `an issue in ${forge.repo}` })).body);
     },
 
     async pullFiles(n) {
       return (await client.list(`repos/${repo}/pulls/${n}/files?per_page=${PER_PAGE}`, { what: `the files of ${pullWhat(n)}` })).map(toFile);
     },
 
-    async comments(n) {
-      return (await client.list(`repos/${repo}/issues/${n}/comments?per_page=${PER_PAGE}`, { what: `the comments on #${n} in ${forge.repo}` })).map(toComment);
+    async comments(n, { since } = {}) {
+      return (await client.list(`repos/${repo}/issues/${n}/comments?per_page=${PER_PAGE}${since ? `&since=${enc(since)}` : ''}`, { what: `the comments on #${n} in ${forge.repo}` })).map(toComment);
     },
 
     async comment(n, body) {

package/server/forge-routes.js

@@ -19,6 +19,10 @@
  *   GET  /api/forge/issues/<n>/spec                                    the plan of step 1: what starting a spec on the issue would make (server/pipeline.js), never kept
  *   GET  /api/forge/pulls/<n>/build?slug=<proposal>                    the plan of step 2: the build issue of an approved proposal, never kept
  *   POST /api/forge/issues/<n>/spec | /pulls/<n>/build                 do them, with the plan's digest (server/forge-actions.js)
+ *   GET /api/forge/threads?state=open|closed|all&limit=100             the threads (docs/threads.md): ideas (issues with the threads label) and spec PRs' conversations,
+ *                                                                      newest activity first, each with the `[[mentions]]` its text holds, as written (404 when `threads: false`)
+ *   GET /api/forge/threads/<n>                                         one thread's messages, as written, to read; replying is on the forge
+ *   POST /api/forge/threads                                            { title, body }: a new idea, an issue with the label, as the maintainer (server/forge-actions.js `serveIdea`)
  *   GET /api/forge/work                                                what the agents view groups: pull requests and issues (any state), branches, open spec PRs, and the config's `agents` rules
  *   GET /api/forge/deploys?limit=100                                   the latest workflow runs that are deploys, each with what the
  *                                                                      config says it restarted (server/deploys.js, docs/deploys.md)
@@ -47,7 +51,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { ForgeError, canRerun, hasAdapter, isMaintainer, isTagName, rateLimitWords } from './forge.js';
-import { actionOf, countAttempt, serveAction } from './forge-actions.js';
+import { actionOf, countAttempt, serveAction, serveIdea } from './forge-actions.js';
+import { listThreads, readThread, snapshotOf, threadsOff } from './threads.js';
+import { ideaLabel } from '../core/config.js';
 import { landingOf, serveLanding } from './lander.js';
 import { planSpec, planBuild, pullSpecs } from './pipeline.js';
 import { listPullProposals } from './proposal-pulls.js';
@@ -133,6 +139,28 @@ function routeOf(reqPath, url, config, where, hooks = null) {
     const mapping = createHash('sha256').update(JSON.stringify(config.deploys || null)).digest('hex').slice(0, 12);
     return { key: `deploys?limit=${limit}&config=${mapping}`, load: async (forge) => ({ items: deploysOf(await forge.runs({ limit }), config.deploys) }) };
   }
+  if (reqPath === '/api/forge/threads' || /^\/api\/forge\/threads\/[1-9]\d{0,8}$/.test(reqPath)) {
+    if (threadsOff(config)) throw new ForgeError('Threads are off in this config (threads: false).', { code: 'not-found' });
+    const label = ideaLabel(config);
+    if (reqPath === '/api/forge/threads') {
+      const q = listQuery(url, false);
+      return {
+        key: `threads?state=${q.state}&limit=${q.limit}&label=${label}`,
+        load: async (forge) => {
+          const found = await listThreads(forge, config, where || config, { state: q.state, limit: q.limit, hooks });
+          // Whatever a look reads is news to the hooks once (thread.opened, thread.message, thread.linked), as the spec PRs are
+          if (hooks) {
+            let nodes = [];
+            try { nodes = readTopology(config)?.nodes || []; } catch { nodes = []; }
+            hooks.threadsSeen(forge.repo, snapshotOf(found.gathered, nodes)).catch(() => {});
+          }
+          return { items: found.items, label, problem: found.problem };
+        },
+      };
+    }
+    const n = Number(reqPath.split('/').pop());
+    return { key: `threads/${n}&label=${label}`, load: async (forge) => ({ thread: await readThread(forge, config, where || config, n) }) };
+  }
   if (reqPath === '/api/forge/work') {
     return {
       key: 'work',
@@ -236,6 +264,10 @@ export async function serveForge(req, res, reqPath, url, ctx) {
     send(req, res, out.status, out.body, out.headers);
     return true;
   }
+  if (reqPath === '/api/forge/threads' && req.method === 'POST') {
+    await serveIdea(req, res, ctx, (status, body, headers) => send(req, res, status, body, headers));
+    return true;
+  }
   const act = actionOf(reqPath);
   if (act) {
     if (!config.forge || !hasAdapter(config.forge.type)) {

package/server/forge.js

@@ -14,7 +14,8 @@
  *   issue(n)                          one issue (not a pull request: that is `not-found`)
  *   searchIssues(words)               the issues whose text holds the words (one page; the forge's search, which can lag a moment)
  *   pullFiles(n)                      the files a pull request changes
- *   comments(n)                       the comments on an issue or pull request, oldest first
+ *   comments(n, { since })            the comments on an issue or pull request, oldest first; `since` (an ISO time) only those
+ *                                     created or edited after it, which is how a thread is followed without reading it all again
  *   comment(n, body)                  posts one, and answers it
  *   checks(ref)                       the checks on a commit (a branch, a tag or a sha)
  *   rerun(check)                      re-runs one that can be (`check.rerunnable`)
@@ -36,7 +37,9 @@
  *   createBranch(name, { from })      a branch at the head of the branch `from` (`conflict` when it exists)
  *   createFile({ branch, path, content, message })   one new file on a branch, as one commit (`invalid` when it exists)
  *   createPull({ title, body, head, base, draft })   a pull request; a draft one is `draft: true` (Forgejo: the "WIP: " title it uses)
- *   createIssue({ title, body })      an issue
+ *   createIssue({ title, body, labels })   an issue; `labels` (names) are put on it, a label the repo lacks is made first (an idea is
+ *                                     an issue with the threads label, docs/threads.md). Where cornfield makes the label itself
+ *                                     (Forgejo), the issue carries `labelsMade: [names]`; GitHub makes it on its own and says nothing
  *
  * An adapter module (server/forge-github.js, server/forge-forgejo.js) implements these at its forge's level, with
  * `mergeAt(n, { sha, method })` in place of `merge`; `wrap` checks the arguments and builds `merge` once for every
@@ -78,9 +81,9 @@
  *   createBranch(name: string, opts: { from: string }): Promise<{ name: string, sha: string }>,
  *   createFile(file: { branch: string, path: string, content: string, message: string }): Promise<{ sha: string }>,
  *   createPull(pull: { title: string, body: string, head: string, base: string, draft: boolean }): Promise<Pull>,
- *   createIssue(issue: { title: string, body: string }): Promise<Issue>,
+ *   createIssue(issue: { title: string, body: string, labels?: string[] }): Promise<Issue>,
  *   pullFiles(n: number): Promise<PullFile[]>,
- *   comments(n: number): Promise<Comment[]>,
+ *   comments(n: number, opts?: { since?: string }): Promise<Comment[]>,
  *   comment(n: number, body: string): Promise<Comment>,
  *   checks(ref: string): Promise<Check[]>,
  *   rerun(check: Check): Promise<void>,
@@ -120,6 +123,9 @@ export const DEFAULT_LIMIT = 1000;
 /** The runs a listing returns unless asked for fewer: one forge page */
 export const DEFAULT_RUN_LIMIT = 100;
 
+/** The most labels one new issue is given */
+const MAX_LABELS = 5;
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/;
 const MERGE_METHODS = ['merge', 'squash', 'rebase'];
 const STATES = ['open', 'closed', 'all'];
 const REPO = /^[\w.-]+\/[\w.-]+$/;
@@ -270,7 +276,12 @@ export function wrap(a, forge) {
       return a.searchIssues(words.trim());
     },
     pullFiles: async (n) => a.pullFiles(number(n)),
-    comments: async (n) => a.comments(number(n)),
+    comments: async (n, opts) => {
+      if (opts !== undefined && (opts === null || typeof opts !== 'object' || Array.isArray(opts))) throw invalid('The options are an object.');
+      const since = opts && opts.since;
+      if (since !== undefined && (typeof since !== 'string' || !ISO_TIME.test(since) || Number.isNaN(Date.parse(since)))) throw invalid('since is a time like 2026-11-05T09:00:00Z.');
+      return a.comments(number(n), since === undefined ? {} : { since: new Date(since).toISOString() });
+    },
     comment: async (n, body) => a.comment(number(n), text(body, 'The comment')),
     checks: async (ref) => a.checks(text(ref, 'The commit')),
     rerun: async (check) => {
@@ -339,7 +350,9 @@ export function wrap(a, forge) {
     },
     createIssue: async (issue) => {
       if (!issue || typeof issue !== 'object') throw invalid('Open which issue?');
-      return a.createIssue({ title: bounded(issue.title, 'The title', MAX_TITLE), body: bounded(issue.body ?? ' ', 'The description', MAX_BODY) });
+      const labels = issue.labels ?? [];
+      if (!Array.isArray(labels) || labels.length > MAX_LABELS || labels.some((l) => typeof l !== 'string' || l.trim() === '' || l.trim() !== l || l.length > 50 || l.includes(',') || l.includes('\0'))) throw invalid(`The labels are at most ${MAX_LABELS} names, without commas.`);
+      return a.createIssue({ title: bounded(issue.title, 'The title', MAX_TITLE), body: bounded(issue.body ?? ' ', 'The description', MAX_BODY), labels: [...new Set(labels)] });
     },
     defaultBranch: async () => a.defaultBranch(),
     tags: async () => a.tags(),

package/server/hooks.js

@@ -13,6 +13,14 @@
  *   spec.approved   a maintainer approved a proposal          spec.sentBack   a maintainer sent one back
  *   build.opened    the build issue of an approved proposal was opened
  *   pr.landed       a pull request was landed through cornfield (its Land it); a merge made on the forge sends nothing
+ *   thread.opened  a new idea (an issue with the threads label, docs/threads.md) was first seen
+ *   thread.message a comment was added to a thread: an idea's, or a spec PR's conversation. Once per comment
+ *   thread.linked  a thread now points at the map: a message holds a `[[node]]` mention or a `cornfield-thread` block that
+ *                  resolves, or a spec PR names the thread with `Thread: #n`. Its body adds `nodes` and `proposal`
+ *                  Like `spec.ready`, these fire when cornfield next looks (the dashboard's threads list, or the poll,
+ *                  server/spec-poll.js); a comment's text is never in the payload: `{ event, at, thread, comment?, actor, nodes?,
+ *                  proposal?, mapUrl }`, so the receiver reads the words from the forge itself. The first look at a repo records
+ *                  what is there and sends nothing; each (repo, thread, comment) is sent once, across restarts (`thread_seen`)
  *   session.expiring  a maintainer's sign-in ends within a day (`watchSessions`, below). Its body is its own:
  *                   `{ event, at, actor, expiresAt, mapUrl }`
  *
@@ -186,6 +194,16 @@ 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 thread's event is only which thread, which comment, who and what it links to: never the words said
+    if (event.startsWith('thread.')) {
+      const out = { event, at: new Date(now()).toISOString(), thread: p.thread ?? null };
+      if (p.comment !== undefined) out.comment = p.comment;
+      out.actor = p.actor ?? null;
+      if (p.nodes !== undefined) out.nodes = p.nodes;
+      if (p.proposal !== undefined) out.proposal = p.proposal;
+      out.mapUrl = publicUrl || null;
+      return JSON.stringify(out);
+    }
     const out = {
       event, at: new Date(now()).toISOString(), slug: p.slug ?? null, pull: p.pull ?? null, headSha: p.headSha ?? null,
       proposalSha256: p.proposalSha256 ?? null, actor: p.actor ?? null,
@@ -261,6 +279,68 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
     })().catch((err) => console.error(`[cornfield] the spec PRs could not be checked for spec.ready: ${err instanceof Error ? err.message : err}`));
   }
 
+  /**
+   * Where each thread was last looked at: for the poll to ask the forge only for what is new. `looked` is whether the repo's
+   * threads have been looked at before (the first look sends nothing); `threads` maps a thread's number to the forge's
+   * last-update time when it was looked at (`stamp`) and the time of the newest comment seen (`since`, '' for none).
+   * @param {string} repo
+   * @returns {Promise<{ looked: boolean, threads: Map<number, { stamp: string, since: string }> }>}
+   */
+  async function threadCursors(repo) {
+    const none = { looked: false, threads: new Map() };
+    if (!store) return none;
+    const db = await store();
+    const rows = db.prepare('SELECT issue, comment, stamp FROM thread_seen WHERE repo = ?').all(repo);
+    const threads = new Map();
+    for (const r of rows) {
+      if (r.issue === 0) continue;
+      const t = threads.get(r.issue) || { stamp: '', since: '' };
+      if (r.comment === '') t.stamp = r.stamp;
+      else if (!r.comment.includes(':') && r.stamp > t.since) t.since = r.stamp;
+      threads.set(r.issue, t);
+    }
+    return { looked: rows.some((r) => r.issue === 0 && r.comment === ''), threads };
+  }
+
+  /**
+   * `thread.opened`, `thread.message` and `thread.linked`: the threads a look just read (server/threads.js `snapshotOf`).
+   * Everything is recorded in `thread_seen` (repo, thread, comment) before it is announced, so a restart sends none twice,
+   * and the first look at a repo records what is there and announces nothing. Returns a promise that resolves once the
+   * events are queued; it never rejects.
+   * @param {string} repo 'owner/name'
+   * @param {{ threads: any[], pulls: { pull: number, thread: number, slug: string }[] }} snapshot
+   */
+  async function threadsSeen(repo, snapshot) {
+    if (closed || !store || !snapshot || !Array.isArray(snapshot.threads)) return;
+    try {
+      const db = await store();
+      const at = new Date(now()).toISOString();
+      const looked = db.prepare("SELECT 1 FROM thread_seen WHERE repo = ? AND issue = 0 AND comment = ''").get(repo) !== undefined;
+      const insert = db.prepare('INSERT OR IGNORE INTO thread_seen (repo, issue, comment, stamp, at) VALUES (?, ?, ?, ?, ?)');
+      const move = db.prepare("INSERT INTO thread_seen (repo, issue, comment, stamp, at) VALUES (?, ?, '', ?, ?) ON CONFLICT(repo, issue, comment) DO UPDATE SET stamp = excluded.stamp");
+      /** Whether this (thread, key) is news: new to the table, and not the silent first look */
+      const fresh = (thread, key, stamp = '') => insert.run(repo, thread, key, stamp, at).changes === 1 && looked;
+      for (const t of snapshot.threads) {
+        if (t.opened && fresh(t.number, '', t.stamp)) emit('thread.opened', { thread: t.number, actor: t.opened.actor });
+        if (t.opened && t.opened.linked && fresh(t.number, 'link:body')) {
+          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 (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
+        move.run(repo, t.number, t.stamp, at);
+      }
+      for (const p of snapshot.pulls || []) {
+        if (fresh(p.thread, `pr:${p.pull}`)) emit('thread.linked', { thread: p.thread, actor: null, nodes: [], proposal: p.slug });
+      }
+      if (!looked) insert.run(repo, 0, '', '', at);
+    } catch (err) {
+      console.error(`[cornfield] the threads could not be checked for thread events: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+
   /**
    * `session.expiring`: once an hour (and once now), the live sessions of maintainers (the ones that keep a forge token)
    * that end within 24 hours are announced, each once: the row's `expiring_sent_at` is set before the event is
@@ -296,7 +376,7 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
     timers.clear();
   }
 
-  return { emit, specsSeen, watchSessions, close };
+  return { emit, 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/proposal-pulls.js

@@ -84,7 +84,7 @@ function entryOf(pull, file) {
  * @param {import('./forge.js').Forge} forge
  * @param {{ proposals: string }} where
  * @param {{ hooks?: { specsSeen: Function } | null }} [opts]
- * @returns {Promise<{ entries: PullEntry[], problem: string | null }>}
+ * @returns {Promise<{ entries: PullEntry[], problem: string | null, pulls: import('./forge.js').Pull[] }>} `pulls`: the open pull requests listed (a thread look reads their text, server/threads.js)
  */
 export async function listPullProposals(forge, where, { hooks = null } = {}) {
   const folder = folderOf(where);
@@ -92,7 +92,7 @@ export async function listPullProposals(forge, where, { hooks = null } = {}) {
   try {
     pulls = await forge.pulls({ state: 'open' });
   } catch (err) {
-    return { entries: [], problem: forgeWords(err) };
+    return { entries: [], problem: forgeWords(err), pulls: [] };
   }
   let problem = null;
   const found = pulls.map(() => []);
@@ -112,7 +112,7 @@ export async function listPullProposals(forge, where, { hooks = null } = {}) {
   if (hooks) {
     try { hooks.specsSeen(forge.repo, entries, (entry) => readPullProposal(forge, where, entry)); } catch { /* a hook never gets in the way */ }
   }
-  return { entries, problem };
+  return { entries, problem, pulls };
 }
 
 /**

package/server/server.js

@@ -42,7 +42,7 @@ import http from 'node:http';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { browserSources, BUILTIN_SOURCES, specPollMs } from '../core/config.js';
+import { browserSources, BUILTIN_SOURCES, specPollMs, 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';
@@ -59,7 +59,7 @@ import { createSpecPoll } from './spec-poll.js';
 export const CORNFIELD_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const EXPLORER_DIR = path.join(CORNFIELD_DIR, 'explorer');
 /** The pure core modules the explorer imports (no Node built-ins, no files): the only ones of core/ served */
-export const BROWSER_CORE = ['schema.js', 'proposal.js', 'personas.js', 'cloud.js', 'text.js'];
+export const BROWSER_CORE = ['schema.js', 'proposal.js', 'personas.js', 'cloud.js', 'text.js', 'mentions.js'];
 /** cornfield's own browser sources, by request path */
 const BROWSER_PLUGINS = new Map(Object.values(BUILTIN_SOURCES).map((p) => [p, path.join(CORNFIELD_DIR, p)]));
 const PKG = JSON.parse(fs.readFileSync(path.join(CORNFIELD_DIR, 'package.json'), 'utf8'));
@@ -109,6 +109,8 @@ export function clientConfig(config, signIn = false) {
     title: config.title,
     links: config.links || [],
     forge: config.forge ? { type: config.forge.type, url: config.forge.url || (config.forge.type === 'github' ? 'https://github.com' : null), repo: config.forge.repo, mergeMethod: config.forge.mergeMethod || 'merge', ...(config.approveLands ? { approveLands: true } : {}) } : null,
+    // Threads (docs/threads.md): the idea label, or false when `threads: false` turns the Threads tab off
+    threads: config.threads === false ? false : { label: ideaLabel(config) },
     sources: browserSources(config),
     signIn,
   };

package/server/spec-poll.js

@@ -1,7 +1,8 @@
 /**
  * @module server/spec-poll
  *
- * `spec.ready` without anyone at the dashboard (PIPE-10, docs/config.md#hook-poll). cornfield notices a spec PR when it
+ * `spec.ready` and the `thread.*` events without anyone at the dashboard (PIPE-10, docs/config.md#hook-poll, docs/threads.md).
+ * cornfield notices a spec PR when it
  * lists the open ones, and that listing used to run only when a maintainer opened the proposals menu or the issues and PRs
  * panel. A team that reviews from chat never does, so this lists them on a timer.
  *
@@ -11,6 +12,12 @@
  * nothing here decides what is news. The forge answers come through the same per-head cache, so a tick with nothing new
  * costs the open-PR listing (a call a page) plus the two calls that check the token's owner; see the docs for the count.
  *
+ * **Threads ride the same tick.** When a hook wants `thread.opened`, `thread.message` or `thread.linked` (and threads are on),
+ * the look also reads the ideas and the spec PRs' conversations (server/threads.js) with the same sign-in, the same timer and
+ * the same backoff: one look, one set of calls to the forge for the open PRs, then what the database says is new
+ * (`hooks.threadCursors`: an idea whose update time is the one last seen is not read again, and the rest are read from their
+ * newest seen comment on). A failure in either half is the tick's failure.
+ *
  * **Whose token.** Never one from the config. The newest live sign-in of a user the forge confirms is a maintainer now
  * (`auth.forgeForUser`, then `me()` and `permission()` with that token; the same check the review API and the lander make).
  * A user who is not, or whose token the forge refuses, is passed over for the next newest, at most `MAX_CANDIDATES`; their
@@ -24,6 +31,9 @@
 
 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 { 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 */
 export const FIRST_MS = 15_000;
@@ -71,6 +81,24 @@ export function createSpecPoll({ config, where, auth, hooks, intervalMs, now = D
     return null;
   }
 
+  /** 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() {
+    try {
+      const topology = readTopology(config);
+      return topology && Array.isArray(topology.nodes) ? topology.nodes : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /** The ideas and the spec PRs' conversations, read from where the database left off and handed to the hooks */
+  async function lookAtThreads(forge, withSpecs) {
+    const cursors = await hooks.threadCursors(repo);
+    const got = await gatherThreads(forge, config, where, { state: 'all', limit: POLL_LIMIT, hooks: withSpecs ? hooks : null, cursors: cursors.looked ? cursors.threads : null });
+    await hooks.threadsSeen(repo, snapshotOf(got, mapNodes()));
+    return got.problem;
+  }
+
   /** One look. Resolves to what happened; never rejects. */
   async function look() {
     let found;
@@ -90,10 +118,13 @@ export function createSpecPoll({ config, where, auth, hooks, intervalMs, now = D
     }
     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 with the sign-in of @${found.login}, a maintainer`);
+    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`);
     lookingAs = found.login;
     try {
-      const { problem } = await listPullProposals(found.forge, where, { hooks });
+      const specs = hookWants(config, ['spec.ready']);
+      const threads = threadsOn(config) && hookWants(config, THREAD_EVENTS);
+      // One listing of the open PRs serves both: the threads' look makes it itself when it runs
+      const problem = threads ? await lookAtThreads(found.forge, specs) : (await listPullProposals(found.forge, where, { hooks })).problem;
       if (problem) {
         log(`the forge could not be asked: ${problem}`);
         return 'error';