cornfield 0.6.0 → 0.8.0

package/explorer/index.html

@@ -211,6 +211,7 @@
           <div class="hx-forge-tabs" role="group" aria-label="Show">
             <button type="button" class="hx-forge-tab" data-forge-kind="pulls" aria-pressed="true">Pull requests</button>
             <button type="button" class="hx-forge-tab" data-forge-kind="issues" aria-pressed="false">Issues</button>
+            <button type="button" class="hx-forge-tab" data-forge-kind="threads" aria-pressed="false" title="Ideas and spec conversations, with the nodes they mention">Threads</button>
             <button type="button" class="hx-forge-tab" data-forge-kind="deploys" aria-pressed="false">Deploys</button>
             <button type="button" class="hx-forge-tab" data-forge-kind="work" aria-pressed="false" title="Work grouped by issue and proposal, agent-made work marked">Agents</button>
             <button type="button" class="hx-forge-tab" data-forge-kind="notes" aria-pressed="false">Release notes</button>
@@ -228,6 +229,23 @@
         </div>
         <p id="forge-notice" class="hx-forge-notice" hidden></p>
         <p id="forge-act-note" class="hx-forge-notice" hidden></p>
+        <!-- New idea (forge-panel.js): opens an issue with the threads label as you, on the forge; the thread itself lives there -->
+        <section id="forge-idea" class="hx-forge-notes" aria-label="New idea" hidden>
+          <div class="hx-forge-actions">
+            <button type="button" id="idea-open" class="hx-btn hx-btn--approve" data-action="idea-open" aria-expanded="false" aria-controls="idea-form">New idea …</button>
+          </div>
+          <p id="idea-message" class="hx-forge-msg" role="status" hidden></p>
+          <div id="idea-form" class="hx-forge-confirm" role="group" aria-labelledby="idea-form-title" hidden>
+            <h3 id="idea-form-title" class="hx-forge-confirm-title">New idea</h3>
+            <p id="idea-words"></p>
+            <label class="hx-forge-field">Title<input type="text" id="idea-title" class="hx-forge-input" maxlength="256" autocomplete="off" /></label>
+            <label class="hx-forge-field">What is the idea?<textarea id="idea-body" class="hx-forge-preview hx-thread-compose" rows="6" maxlength="20000" spellcheck="true"></textarea></label>
+            <div class="hx-forge-actions">
+              <button type="button" id="idea-send" class="hx-btn hx-btn--approve" data-action="idea-send">Open the idea</button>
+              <button type="button" class="hx-btn hx-btn--quiet" data-action="idea-cancel">Cancel</button>
+            </div>
+          </div>
+        </section>
         <!-- Release notes (forge-panel.js): the pull requests merged since a tag, grouped by the map; copy them, or have the forge keep them as a draft release -->
         <section id="forge-notes" class="hx-forge-notes" aria-label="Release notes" hidden>
           <label class="hx-forge-field">Since tag<select id="notes-since" class="hx-forge-select"></select></label>

package/explorer/panels.js

@@ -125,6 +125,26 @@ function dataSummary(node) {
   return '';
 }
 
+// ---------------------------------------------------------------------------
+//  Threads that mention the node
+// ---------------------------------------------------------------------------
+
+/** "Mentioned in": the threads whose text names the node (an idea, or a spec PR's conversation); each opens in the issues and PRs panel */
+function threadsSection(node) {
+  const index = state.threadIndex;
+  const threads = index ? index.for(node.id) : null;
+  if (!threads || !threads.length) return '';
+  const rows = threads.map((t) => `<div class="hx-line"><span class="hx-glyph" style="--glyph:#fbbf24">◆</span><span><button type="button" class="hx-btn hx-thread-open" data-thread-open="${t.number}" aria-label="Open thread #${t.number}, ${escHtml(t.title)}, in the issues and pull requests panel">#${t.number} ${escHtml(t.title)}</button> <span class="hx-faint">${t.kind === 'proposal' ? 'proposal' : 'idea'}</span></span></div>`);
+  return section(`Mentioned in ${threads.length} ${threads.length === 1 ? 'thread' : 'threads'}:`, rows);
+}
+
+/** Draws "Mentioned in" again in the open panel (the list was just read, or the map changed); nothing else in the panel moves */
+export function repaintThreads() {
+  const box = $('drawer-threads');
+  if (!box || !state.selectedNode) return;
+  box.innerHTML = threadsSection(state.selectedNode);
+}
+
 // ---------------------------------------------------------------------------
 //  The drawer
 // ---------------------------------------------------------------------------
@@ -179,6 +199,10 @@ export async function selectNode(node) {
   const mockups = nodeMockupsHtml(node.id);
   if (mockups) (proposed ? metaList.firstElementChild : metaList).insertAdjacentHTML(proposed ? 'afterend' : 'afterbegin', mockups);
 
+  // The threads that mention it (docs/threads.md): filled in place once the list is read
+  metaList.insertAdjacentHTML('beforeend', `<div id="drawer-threads">${threadsSection(node)}</div>`);
+  if (state.threadIndex) state.threadIndex.ensure();
+
   // What the live layer knows of it (spec 0029): a count, a linked machine's item, contents and sets; repainted in place by live.js
   metaList.insertAdjacentHTML('beforeend', `<div id="drawer-live">${liveSection(node)}</div>`);
   hydrateLivePhotos($('drawer-live'));

package/explorer/state.js

@@ -119,6 +119,13 @@ export const state = {
    */
   forgeLit: null,
 
+  /**
+   * Which threads mention which nodes (forge-panel.js, docs/threads.md), for a node's panel: `{ for(nodeId) -> thread[] | null,
+   * ensure(), open(number) }`, or null when threads are off or there is no forge. `for` answers null until the list has been
+   * read; `ensure` reads it (once) and repaints the panel's "Mentioned in"; `open` shows a thread in the issues and PRs panel.
+   */
+  threadIndex: null,
+
   /**
    * Changes whenever anything the scene is built from changes (scene.js). render.js rebuilds the
    * scene only when this moved: never for a camera change or a packet frame.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cornfield",
-  "version": "0.6.0",
+  "version": "0.8.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)",
@@ -31,6 +31,7 @@
     "./plugins/*": "./plugins/*",
     "./deriver-kit": "./core/deriver-kit.js",
     "./server": "./server/server.js",
+    "./agent-contract.schema.json": "./core/agent-contract.schema.json",
     "./package.json": "./package.json"
   },
   "files": [

package/server/db.js

@@ -12,6 +12,9 @@
  *   hook_seen     the (pull request, head, proposal) triples whose `spec.ready` event was sent, so a restart sends none twice;
  *                 a row with `pr = 0` says the repo has been looked at once (server/hooks.js)
  *   landings      the spec PRs an approval is waiting to land (`proposals.approveLands`), so a restart picks them up (server/lander.js)
+ *   thread_seen   the (repo, issue, comment) triples whose thread.* hook event was sent, and each thread's last-seen time, so a
+ *                 restart sends none twice and a look asks the forge only for what is new (server/hooks.js, server/threads.js);
+ *                 a row with `issue = 0` says the repo's threads have been looked at once
  *                 sessions also keep a forge refresh token, the access token's expiry and when `session.expiring` was sent (migration 5)
  *
  * The schema is a list of numbered migrations (`MIGRATIONS`); the file's `PRAGMA user_version` is the number of
@@ -133,6 +136,18 @@ export const MIGRATIONS = Object.freeze([
   ALTER TABLE sessions ADD COLUMN token_expires_at TEXT;                   -- when the access token stops working; NULL when it does not expire
   ALTER TABLE sessions ADD COLUMN expiring_sent_at TEXT;                   -- when the \`session.expiring\` hook event was sent; NULL before
   `,
+  // 6: threads (server/threads.js, server/hooks.js): which comments of a thread have been announced. The thread itself is the
+  // forge's (an issue's comments, or a spec PR's conversation); this only remembers what was told, never what was said
+  `
+  CREATE TABLE thread_seen (
+    repo        TEXT NOT NULL,                  -- 'owner/name'
+    issue       INTEGER NOT NULL,               -- the issue or pull request number of the thread; 0 with comment '' says the repo has been looked at once
+    comment     TEXT NOT NULL,                  -- '' the thread itself (opened); a comment's id (message); 'link:<id>' or 'link:body' (linked); 'pr:<n>' a spec PR that names the thread
+    stamp       TEXT NOT NULL DEFAULT '',       -- the forge's own time: the comment's last edit, or (on the '' row) the thread's last update when it was looked at
+    at          TEXT NOT NULL,                  -- when cornfield first saw it
+    PRIMARY KEY (repo, issue, comment)
+  ) STRICT;
+  `,
 ]);
 
 /** The version a file is at: its `user_version` */

package/server/defuse.js

@@ -1,16 +1,7 @@
 /**
  * @module server/defuse
  *
- * Breaking the mentions and references in text cornfield posts on the forge for someone else: `@user`, `@org/team`,
- * `#1`, `owner/repo#1`, `GH-1`, and the links the forge would make of `https://…` or `www.…`. A zero-width space after
- * the character keeps the text as it reads and stops it notifying anyone or linking anything. The pipeline's issues
- * (server/pipeline.js) and a review that came through the review API (server/reviews.js) use it.
+ * Moved to core/defuse.js, so core/ (core/agent-contract.js) can use it without importing server code. Re-exported here so
+ * the server's imports keep working.
  */
-
-/** A zero-width space: it ends a mention or a reference without showing */
-export const ZW = '​';
-
-/** Text with every mention, reference and auto-link broken (see the module's head) */
-export function defuse(text) {
-  return String(text).replace(/[@#]/g, (c) => `${c}${ZW}`).replace(/\b(GH)-(?=\d)/gi, `$1${ZW}-`).replace(/:\/\//g, `:${ZW}//`).replace(/\b(www)\./gi, `$1${ZW}.`);
-}
+export { ZW, defuse } from '../core/defuse.js';

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) */