@popcorn245/cornfield 0.6.0 → 0.8.0

package/core/agent-contract.schema.json

@@ -0,0 +1,259 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/popcorn245/CornField/blob/main/core/agent-contract.schema.json",
+  "title": "cornfield agent contract, version 1",
+  "description": "The JSON a cornfield-run fenced block holds: a request, a report or a stop request. docs/agent-contract.md says what each means. Checks the shape; a few rules are the validator's alone (the configured profile list, that a date is a real one), and are listed in the docs.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/request"
+    },
+    {
+      "$ref": "#/$defs/report"
+    },
+    {
+      "$ref": "#/$defs/stopRequest"
+    }
+  ],
+  "$defs": {
+    "runId": {
+      "description": "run- and a 26 character ULID in Crockford base32",
+      "type": "string",
+      "pattern": "^run-[0-7][0-9A-HJKMNP-TV-Z]{25}$"
+    },
+    "request": {
+      "description": "A request for a run. It carries no credential: a property named like a token, a secret or a password is refused.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "version",
+        "runId",
+        "kind",
+        "refs",
+        "brief",
+        "requestedBy",
+        "requestedAt"
+      ],
+      "propertyNames": {
+        "not": {
+          "pattern": "(?:[tT][oO][kK][eE][nN]|[sS][eE][cC][rR][eE][tT]|[pP][aA][sS][sS][wW]|[cC][rR][eE][dD][eE][nN][tT][iI][aA][lL]|[aA][pP][iI][_-]?[kK][eE][yY]|[aA][cC][cC][eE][sS][sS][_-]?[kK][eE][yY]|[pP][rR][iI][vV][aA][tT][eE][_-]?[kK][eE][yY]|[sS][sS][hH][_-]?[kK][eE][yY]|[aA][uU][tT][hH][oO][rR][iI][zZ][aA][tT][iI][oO][nN]|[bB][eE][aA][rR][eE][rR]|[cC][oO][oO][kK][iI][eE])"
+        }
+      },
+      "properties": {
+        "version": {
+          "const": 1
+        },
+        "runId": {
+          "$ref": "#/$defs/runId"
+        },
+        "kind": {
+          "enum": [
+            "code",
+            "summary",
+            "brief",
+            "proposal"
+          ]
+        },
+        "profile": {
+          "type": "string",
+          "maxLength": 64,
+          "not": {
+            "pattern": "(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{30,}|(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{20,}|(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{15,}|(?<![A-Za-z0-9])gto-[A-Za-z0-9]{20,}|(?<![A-Za-z0-9])sk-(?=[A-Za-z0-9_-]{20})[A-Za-z_-]{0,40}[0-9]|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}|(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}|(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{10,}|(?<![A-Za-z0-9])eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{5,}|-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----|(?<![A-Za-z0-9])[bB][eE][aA][rR][eE][rR][ \\t]+(?=[A-Za-z0-9._~+/=-]{20})[A-Za-z._~+/=-]{0,40}[0-9]|(?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}://[^\\s/@:]+:[^\\s/@]+@"
+          },
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
+          "description": "A name the runner maps to a model, a machine and a budget. When the developer configured a list, only those names."
+        },
+        "refs": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "issue": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 2147483647
+            },
+            "proposal": {
+              "type": "string",
+              "maxLength": 120,
+              "not": {
+                "pattern": "(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{30,}|(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{20,}|(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{15,}|(?<![A-Za-z0-9])gto-[A-Za-z0-9]{20,}|(?<![A-Za-z0-9])sk-(?=[A-Za-z0-9_-]{20})[A-Za-z_-]{0,40}[0-9]|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}|(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}|(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{10,}|(?<![A-Za-z0-9])eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{5,}|-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----|(?<![A-Za-z0-9])[bB][eE][aA][rR][eE][rR][ \\t]+(?=[A-Za-z0-9._~+/=-]{20})[A-Za-z._~+/=-]{0,40}[0-9]|(?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}://[^\\s/@:]+:[^\\s/@]+@"
+              },
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$"
+            },
+            "pull": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 2147483647,
+              "description": "The spec pull request that holds the proposal; only with proposal."
+            },
+            "thread": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 2147483647
+            }
+          },
+          "anyOf": [
+            {
+              "required": [
+                "issue"
+              ]
+            },
+            {
+              "required": [
+                "proposal"
+              ]
+            },
+            {
+              "required": [
+                "thread"
+              ]
+            }
+          ],
+          "dependentRequired": {
+            "pull": [
+              "proposal"
+            ]
+          }
+        },
+        "branch": {
+          "type": "string",
+          "maxLength": 200,
+          "not": {
+            "pattern": "(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{30,}|(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{20,}|(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{15,}|(?<![A-Za-z0-9])gto-[A-Za-z0-9]{20,}|(?<![A-Za-z0-9])sk-(?=[A-Za-z0-9_-]{20})[A-Za-z_-]{0,40}[0-9]|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}|(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}|(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{10,}|(?<![A-Za-z0-9])eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{5,}|-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----|(?<![A-Za-z0-9])[bB][eE][aA][rR][eE][rR][ \\t]+(?=[A-Za-z0-9._~+/=-]{20})[A-Za-z._~+/=-]{0,40}[0-9]|(?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}://[^\\s/@:]+:[^\\s/@]+@"
+          },
+          "minLength": 1,
+          "description": "A hint: a safe git ref name.",
+          "allOf": [
+            {
+              "pattern": "^[A-Za-z0-9._/-]+$"
+            },
+            {
+              "not": {
+                "pattern": "^-|^/|/$|//|\\.\\.|\\.$|(^|/)\\.|\\.lock(/|$)"
+              }
+            }
+          ]
+        },
+        "brief": {
+          "type": "string",
+          "maxLength": 20000,
+          "not": {
+            "pattern": "(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{30,}|(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{20,}|(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{15,}|(?<![A-Za-z0-9])gto-[A-Za-z0-9]{20,}|(?<![A-Za-z0-9])sk-(?=[A-Za-z0-9_-]{20})[A-Za-z_-]{0,40}[0-9]|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}|(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}|(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{10,}|(?<![A-Za-z0-9])eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{5,}|-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----|(?<![A-Za-z0-9])[bB][eE][aA][rR][eE][rR][ \\t]+(?=[A-Za-z0-9._~+/=-]{20})[A-Za-z._~+/=-]{0,40}[0-9]|(?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}://[^\\s/@:]+:[^\\s/@]+@"
+          }
+        },
+        "limits": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "minutes": {
+              "type": "number",
+              "exclusiveMinimum": 0
+            },
+            "turns": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            },
+            "cost": {
+              "type": "number",
+              "exclusiveMinimum": 0
+            }
+          }
+        },
+        "nodes": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "type": "string",
+            "maxLength": 200,
+            "not": {
+              "pattern": "(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{30,}|(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{20,}|(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{15,}|(?<![A-Za-z0-9])gto-[A-Za-z0-9]{20,}|(?<![A-Za-z0-9])sk-(?=[A-Za-z0-9_-]{20})[A-Za-z_-]{0,40}[0-9]|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}|(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}|(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{10,}|(?<![A-Za-z0-9])eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{5,}|-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----|(?<![A-Za-z0-9])[bB][eE][aA][rR][eE][rR][ \\t]+(?=[A-Za-z0-9._~+/=-]{20})[A-Za-z._~+/=-]{0,40}[0-9]|(?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}://[^\\s/@:]+:[^\\s/@]+@"
+            },
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$"
+          }
+        },
+        "requestedBy": {
+          "type": "string",
+          "maxLength": 40,
+          "not": {
+            "pattern": "(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{30,}|(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{20,}|(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{15,}|(?<![A-Za-z0-9])gto-[A-Za-z0-9]{20,}|(?<![A-Za-z0-9])sk-(?=[A-Za-z0-9_-]{20})[A-Za-z_-]{0,40}[0-9]|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}|(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}|(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{10,}|(?<![A-Za-z0-9])eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{5,}|-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----|(?<![A-Za-z0-9])[bB][eE][aA][rR][eE][rR][ \\t]+(?=[A-Za-z0-9._~+/=-]{20})[A-Za-z._~+/=-]{0,40}[0-9]|(?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}://[^\\s/@:]+:[^\\s/@]+@"
+          },
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$"
+        },
+        "requestedAt": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,3})?Z$"
+        }
+      }
+    },
+    "report": {
+      "description": "What a runner may say about a run it is doing.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "state"
+      ],
+      "properties": {
+        "state": {
+          "enum": [
+            "claimed",
+            "working",
+            "done",
+            "failed",
+            "stopped"
+          ]
+        },
+        "note": {
+          "type": "string",
+          "maxLength": 4000,
+          "not": {
+            "pattern": "(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{30,}|(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{20,}|(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{15,}|(?<![A-Za-z0-9])gto-[A-Za-z0-9]{20,}|(?<![A-Za-z0-9])sk-(?=[A-Za-z0-9_-]{20})[A-Za-z_-]{0,40}[0-9]|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}|(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}|(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{10,}|(?<![A-Za-z0-9])eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{5,}|-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----|(?<![A-Za-z0-9])[bB][eE][aA][rR][eE][rR][ \\t]+(?=[A-Za-z0-9._~+/=-]{20})[A-Za-z._~+/=-]{0,40}[0-9]|(?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}://[^\\s/@:]+:[^\\s/@]+@"
+          }
+        },
+        "url": {
+          "type": "string",
+          "maxLength": 2000,
+          "not": {
+            "pattern": "(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{30,}|(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{20,}|(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{15,}|(?<![A-Za-z0-9])gto-[A-Za-z0-9]{20,}|(?<![A-Za-z0-9])sk-(?=[A-Za-z0-9_-]{20})[A-Za-z_-]{0,40}[0-9]|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}|(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}|(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{10,}|(?<![A-Za-z0-9])eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{5,}|-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----|(?<![A-Za-z0-9])[bB][eE][aA][rR][eE][rR][ \\t]+(?=[A-Za-z0-9._~+/=-]{20})[A-Za-z._~+/=-]{0,40}[0-9]|(?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}://[^\\s/@:]+:[^\\s/@]+@"
+          },
+          "pattern": "^https?://[^\\s/@?#]+([/?#]\\S*)?$",
+          "description": "Where the runner keeps its logs.",
+          "allOf": [
+            {
+              "not": {
+                "pattern": "[?&#;](?:[^\\s=&#;]*(?:[tT][oO][kK][eE][nN]|[sS][eE][cC][rR][eE][tT]|[pP][aA][sS][sS][wW]|[kK][eE][yY]|[sS][iI][gG][nN][aA][tT][uU][rR][eE])[^\\s=&#;]*|[sS][iI][gG])="
+              }
+            }
+          ]
+        },
+        "tokens": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "cost": {
+          "type": "number",
+          "minimum": 0
+        }
+      }
+    },
+    "stopRequest": {
+      "description": "cornfield asking a runner to stop. The runner decides what stopping means.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "state"
+      ],
+      "properties": {
+        "state": {
+          "const": "stop-requested"
+        },
+        "note": {
+          "type": "string",
+          "maxLength": 4000,
+          "not": {
+            "pattern": "(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{30,}|(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{20,}|(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{15,}|(?<![A-Za-z0-9])gto-[A-Za-z0-9]{20,}|(?<![A-Za-z0-9])sk-(?=[A-Za-z0-9_-]{20})[A-Za-z_-]{0,40}[0-9]|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}|(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}|(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{10,}|(?<![A-Za-z0-9])eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{5,}|-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----|(?<![A-Za-z0-9])[bB][eE][aA][rR][eE][rR][ \\t]+(?=[A-Za-z0-9._~+/=-]{20})[A-Za-z._~+/=-]{0,40}[0-9]|(?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}://[^\\s/@:]+:[^\\s/@]+@"
+          }
+        }
+      }
+    }
+  }
+}

package/core/config.js

@@ -23,7 +23,8 @@
  *     personas: { roles: null },              // the roles a persona may have (null: any)
  *     releaseNotes: { breakingLabel: 'breaking' },   // the pull request label that lists a change under "Breaking" in the release notes
  *     hooks: [],                              // [{ url, events }]: signed JSON events posted to outside code (docs/config.md#hooks); the secret is env only
- *     hookPoll: { specs: '5m' },              // how often cornfield looks for ready specs on its own, for the spec.ready hook; false turns it off (docs/config.md#hook-poll)
+ *     hookPoll: { specs: '5m' },              // how often cornfield looks for ready specs and thread activity on its own, for the spec.ready and thread.* hooks; false turns it off (docs/config.md#hook-poll)
+ *     threads: { label: 'idea' },             // an idea is an issue with this label, its thread the issue's comments; false turns threads off (docs/threads.md)
  *     links: [],                              // [{ label, href }] shown in the explorer's header
  *     proxy: {},                              // { '/api/': 'http://127.0.0.1:3245' }: same-origin paths for a live source
  *     importMap: {},                          // bare imports a repo-local browser module needs: { name: '/repo/path.js' }
@@ -66,7 +67,12 @@ export const FORGE_TYPES = ['github', 'forgejo'];
 /** How a pull request cornfield lands is merged (`forge.mergeMethod`): the way the repo lands its pull requests */
 export const MERGE_METHODS = ['merge', 'squash', 'rebase'];
 /** The events a hook may ask for (`hooks[].events`), and what each one means: docs/config.md#hooks */
-export const HOOK_EVENTS = Object.freeze(['spec.ready', 'spec.approved', 'spec.sentBack', 'build.opened', 'pr.landed', 'session.expiring']);
+export const HOOK_EVENTS = Object.freeze(['spec.ready', 'spec.approved', 'spec.sentBack', 'build.opened', 'pr.landed', 'session.expiring', 'thread.opened', 'thread.message', 'thread.linked']);
+/** The events that come from looking at threads (server/threads.js): a poll that wants any of them looks at threads too */
+export const THREAD_EVENTS = Object.freeze(['thread.opened', 'thread.message', 'thread.linked']);
+/** The keys of `threads` when it is an object, and the label's longest length */
+export const THREADS_KEYS = Object.freeze(['label']);
+export const MAX_LABEL = 50;
 /** The most hooks a config lists */
 export const MAX_HOOKS = 20;
 /** The bounds of `hookPoll.specs` in milliseconds: not under a minute (the forge is not hammered), not over an hour */
@@ -85,14 +91,26 @@ export function parseDuration(v) {
   return m ? Number(m[1]) * { s: 1000, m: 60_000, h: 3_600_000 }[m[2]] : null;
 }
 
+/** Whether some hook subscribes to any of `events` (by name, or with '*') */
+export function hookWants(config, events) {
+  return Array.isArray(config.hooks) && config.hooks.some((h) => h.events === '*' || (Array.isArray(h.events) && h.events.some((e) => events.includes(e))));
+}
+
+/** Whether threads are on: `threads: false` turns them off, anything else (the default included) leaves them on */
+export const threadsOn = (config) => config.threads !== false;
+
+/** The label that makes an issue an idea, or null when threads are off */
+export const ideaLabel = (config) => (threadsOn(config) ? (config.threads && config.threads.label) || DEFAULTS.threads.label : null);
+
 /**
- * How often cornfield looks at the open spec PRs by itself, in milliseconds, or null when it does not: when `hookPoll.specs`
- * is false, or no hook subscribes to `spec.ready` (by name or with '*').
- * @param {{ hooks?: { events: string[] | '*' }[], hookPoll?: { specs?: string | false } | false }} config a loaded config
+ * How often cornfield looks by itself, in milliseconds, or null when it does not: when `hookPoll.specs` is false, or no
+ * hook subscribes to something the look finds (`spec.ready`, or a `thread.*` event while threads are on), by name or with '*'.
+ * One look covers both: the open spec PRs and the threads (server/spec-poll.js).
+ * @param {{ hooks?: { events: string[] | '*' }[], hookPoll?: { specs?: string | false } | false, threads?: false | { label?: string } }} config a loaded config
  * @returns {number | null}
  */
 export function specPollMs(config) {
-  const wanted = Array.isArray(config.hooks) && config.hooks.some((h) => h.events === '*' || (Array.isArray(h.events) && h.events.includes('spec.ready')));
+  const wanted = hookWants(config, ['spec.ready']) || (threadsOn(config) && hookWants(config, THREAD_EVENTS));
   const every = config.hookPoll === false ? false : config.hookPoll ? config.hookPoll.specs : DEFAULTS.hookPoll.specs;
   return wanted && every !== false ? parseDuration(every ?? DEFAULTS.hookPoll.specs) : null;
 }
@@ -115,6 +133,7 @@ export const DEFAULTS = Object.freeze({
   agents: { authors: [], labels: [], branchPrefixes: [], bots: true },
   hooks: [],
   hookPoll: { specs: '5m' },
+  threads: { label: 'idea' },
   links: [],
   proxy: {},
   importMap: {},
@@ -241,6 +260,14 @@ export function configProblems(c) {
       }
     }
   }
+  if (c.threads !== undefined && c.threads !== false) {
+    if (!isObject(c.threads)) out.push('"threads" is { label: "idea" }, or false to turn threads off.');
+    else {
+      for (const k of Object.keys(c.threads)) if (!THREADS_KEYS.includes(k)) out.push(`threads.${k}: the key is ${THREADS_KEYS.join(', ')}.`);
+      const l = c.threads.label;
+      if (l !== undefined && (!isText(l) || l.includes(',') || l.trim() !== l || l.length > MAX_LABEL)) out.push(`threads.label is the name of the label that makes an issue an idea, like "idea": text of at most ${MAX_LABEL} characters, no comma, no space at either end.`);
+    }
+  }
   if (c.releaseNotes !== undefined) {
     if (!isObject(c.releaseNotes)) out.push('"releaseNotes" is { breakingLabel }.');
     else if (c.releaseNotes.breakingLabel !== undefined && (!isText(c.releaseNotes.breakingLabel) || c.releaseNotes.breakingLabel.includes(','))) out.push('releaseNotes.breakingLabel is a label\'s name, like "breaking".');
@@ -323,7 +350,7 @@ export async function loadConfig(root, { env = process.env, file } = {}) {
     if (problems.length) throw new Error(`${path.relative(absRoot, configFile) || CONFIG_FILE}:\n  ${problems.join('\n  ')}`);
   }
   const config = {
-    ...structuredClone({ ...DEFAULTS, sources: { ...DEFAULTS.sources }, personas: { ...DEFAULTS.personas }, cloud: { ...DEFAULTS.cloud }, agents: { ...DEFAULTS.agents }, releaseNotes: { ...DEFAULTS.releaseNotes } }),
+    ...structuredClone({ ...DEFAULTS, sources: { ...DEFAULTS.sources }, personas: { ...DEFAULTS.personas }, cloud: { ...DEFAULTS.cloud }, agents: { ...DEFAULTS.agents }, releaseNotes: { ...DEFAULTS.releaseNotes }, threads: { ...DEFAULTS.threads } }),
     ...raw,
     sources: { ...DEFAULTS.sources, ...(raw.sources || {}) },
     personas: { ...DEFAULTS.personas, ...(raw.personas || {}) },
@@ -332,6 +359,8 @@ export async function loadConfig(root, { env = process.env, file } = {}) {
     deploys: { ...DEFAULTS.deploys, ...(raw.deploys || {}) },
     agents: { ...DEFAULTS.agents, ...(raw.agents || {}) },
   };
+  // `threads: false` stays false; an object is read over the default
+  config.threads = raw.threads === false ? false : { ...DEFAULTS.threads, ...(raw.threads || {}) };
   // `hookPoll: false` is `{ specs: false }`; an object is read over the default
   config.hookPoll = raw.hookPoll === false ? { specs: false } : { ...DEFAULTS.hookPoll, ...(raw.hookPoll || {}) };
   // `proposals` is the folder to everything downstream, whichever way the file wrote it; the options are read from `approveLands`

package/core/defuse.js

@@ -0,0 +1,17 @@
+/**
+ * @module core/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), a review that came through the review API (server/reviews.js) and the agent contract
+ * (core/agent-contract.js) use it. It imports nothing, so Node and the browser can both load it.
+ */
+
+/** 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}.`);
+}

package/core/mentions.js

@@ -0,0 +1,239 @@
+/**
+ * @module core/mentions
+ *
+ * How a thread points at the map (spec 0005, D7). Pure: no I/O, no DOM, no Node built-ins, so the server (a hook's
+ * payload) and the explorer (the lights, a node's "Mentioned in") load the same file.
+ *
+ *   - **Mentions.** People write `[[core-server-auth]]` (a node's id) or `[[server/auth.js]]` (a repo path) in prose.
+ *     `parseMentions` reads them outside code: a fenced block and an inline code span are text about code, not links.
+ *   - **A block.** Tools and agents may write a fenced block for precise links:
+ *
+ *         ```cornfield-thread
+ *         { "nodes": ["core-server-auth", "server/hooks.js"], "proposal": "0013-meals" }
+ *         ```
+ *
+ *     `nodes` are read like mentions (an id or a path); `proposal` is a proposal's slug. A block that is not that shape
+ *     is ignored, and prose is read as before.
+ *   - **Resolving.** `resolveMention` answers a reference in this order: a node's id; a node whose `file` is exactly
+ *     that path; the node(s) that own the path (the deepest `file` that is the path or a folder above it, as a file
+ *     lights its node for a pull request, `nodesForFile`). A reference that is none of these resolves to nothing and
+ *     stays plain text, which reads sensibly on the forge without cornfield.
+ *   - **Caps.** At most `MAX_MENTIONS` distinct references are read from one text, and a reference is at most
+ *     `MAX_REF` characters, so a comment cannot make the map light up everything or cost a lot to read.
+ *   - **Links.** `threadOfPull` reads the thread a spec PR names: `Thread: #n` or `Closes #n` (also Fixes and Resolves).
+ */
+
+/** The most distinct references read from one text, and the longest one */
+export const MAX_MENTIONS = 50;
+export const MAX_REF = 200;
+/** The most a `cornfield-thread` block may name */
+export const MAX_BLOCK_NODES = 50;
+/** The fence's info string that marks a block of links */
+export const THREAD_BLOCK = 'cornfield-thread';
+
+const SLUG = /^[a-z0-9][a-z0-9._-]{0,99}$/i;
+
+const clean = (p) => String(p).replace(/^\.\//, '').replace(/\/+$/, '');
+
+/**
+ * The node(s) whose `file` holds a path: the node's `file` is the path itself or a folder above it, and the deepest
+ * (longest) `file` wins. A file that holds several nodes (a page and what renders it) lights all of them. (The explorer's
+ * forge panel lights a pull request's files with this same rule.)
+ * @param {string} path a repo-relative path
+ * @param {{ id: string, file?: string }[]} nodes
+ * @returns {object[]} the nodes, [] when none holds it
+ */
+export function nodesForFile(path, nodes) {
+  const p = clean(path);
+  let best = -1;
+  let out = [];
+  for (const node of nodes) {
+    if (typeof node.file !== 'string' || node.file === '') continue;
+    const file = clean(node.file);
+    if (p !== file && !p.startsWith(`${file}/`)) continue;
+    if (file.length > best) { best = file.length; out = [node]; } else if (file.length === best) out.push(node);
+  }
+  return out;
+}
+
+/**
+ * Splits text into prose and code: `prose` is the text with every fenced block and inline code span blanked (same length,
+ * so offsets hold), `fences` are the fenced blocks as `{ info, body }`.
+ * @param {string} text
+ * @returns {{ prose: string, fences: { info: string, body: string }[] }}
+ */
+export function scan(text) {
+  const src = String(text ?? '');
+  const lines = src.split('\n');
+  const fences = [];
+  const out = [];
+  let open = null; // { char, len, info, body: [] }
+  for (const line of lines) {
+    if (open) {
+      const close = new RegExp(`^ {0,3}${open.char}{${open.len},}[ \\t]*\\r?$`).test(line);
+      if (close) { fences.push({ info: open.info, body: open.body.join('\n') }); open = null; } else open.body.push(line.replace(/\r$/, ''));
+      out.push(' '.repeat(line.length));
+      continue;
+    }
+    const m = /^ {0,3}(`{3,}|~{3,})[ \t]*([^\r]*)$/.exec(line);
+    // An info string of a backtick fence cannot hold a backtick (then it is an inline span, not a fence)
+    if (m && !(m[1][0] === '`' && m[2].includes('`'))) {
+      open = { char: m[1][0], len: m[1].length, info: m[2].trim(), body: [] };
+      out.push(' '.repeat(line.length));
+      continue;
+    }
+    out.push(line);
+  }
+  // A fence left open runs to the end of the text, as the forge's Markdown reads it
+  if (open) fences.push({ info: open.info, body: open.body.join('\n') });
+  return { prose: blankSpans(out.join('\n')), fences };
+}
+
+/** Inline code spans blanked: a run of backticks closes at the next run of the same length */
+function blankSpans(text) {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] !== '`') { out += text[i++]; continue; }
+    let n = 0;
+    while (text[i + n] === '`') n++;
+    let j = i + n;
+    let end = -1;
+    while (j < text.length) {
+      if (text[j] !== '`') { j++; continue; }
+      let m = 0;
+      while (text[j + m] === '`') m++;
+      if (m === n) { end = j + m; break; }
+      j += m;
+    }
+    if (end === -1) { out += text.slice(i, i + n); i += n; continue; }
+    out += text.slice(i, end).replace(/[^\n]/g, ' ');
+    i = end;
+  }
+  return out;
+}
+
+/** A reference as written, made comparable: no `./`, no trailing slash, no `#L10` or `:10` line suffix; or null when it is not one */
+export function normalizeRef(raw) {
+  let ref = String(raw ?? '').trim();
+  if (ref === '' || ref.length > MAX_REF || /[\0\n\r]/.test(ref)) return null;
+  ref = ref.replace(/#.*$/, '').replace(/:\d+(?:-\d+)?$/, '');
+  ref = clean(ref).trim();
+  if (ref === '' || ref.startsWith('/') || ref.split('/').some((p) => p === '..' || p === '.')) return null;
+  return ref;
+}
+
+/**
+ * The `cornfield-thread` block of a text, or null: the first well-formed one wins.
+ * @param {{ info: string, body: string }[]} fences
+ * @returns {{ nodes: string[], proposal: string | null } | null}
+ */
+function blockOf(fences) {
+  for (const f of fences) {
+    if (f.info.split(/\s+/)[0] !== THREAD_BLOCK) continue;
+    let json;
+    try { json = JSON.parse(f.body); } catch { continue; }
+    if (json === null || typeof json !== 'object' || Array.isArray(json)) continue;
+    const nodes = Array.isArray(json.nodes) ? json.nodes.map((n) => (typeof n === 'string' ? normalizeRef(n) : null)).filter((r) => r !== null).slice(0, MAX_BLOCK_NODES) : [];
+    const proposal = typeof json.proposal === 'string' && SLUG.test(json.proposal) ? json.proposal : null;
+    if (!nodes.length && !proposal) continue;
+    return { nodes: [...new Set(nodes)], proposal };
+  }
+  return null;
+}
+
+/**
+ * What a text points at, before the map is asked: the `[[…]]` references outside code (each once, in order, at most
+ * `MAX_MENTIONS`), and the `cornfield-thread` block when there is one.
+ * @param {string} text
+ * @returns {{ refs: string[], block: { nodes: string[], proposal: string | null } | null, truncated: boolean }}
+ */
+export function parseMentions(text) {
+  const { prose, fences } = scan(text);
+  const refs = [];
+  let truncated = false;
+  for (const m of prose.matchAll(/(?<!\\)\[\[([^[\]\n]{1,400})\]\]/g)) {
+    const ref = normalizeRef(m[1]);
+    if (ref === null || refs.includes(ref)) continue;
+    if (refs.length >= MAX_MENTIONS) { truncated = true; break; }
+    refs.push(ref);
+  }
+  return { refs, block: blockOf(fences), truncated };
+}
+
+/**
+ * The nodes one reference stands for, in order of how sure it is: the id; else nodes whose `file` is exactly the path;
+ * else the nodes that own the path.
+ * @param {string} ref
+ * @param {{ id: string, file?: string }[]} nodes
+ * @returns {object[]}
+ */
+export function resolveMention(ref, nodes) {
+  const r = normalizeRef(ref);
+  if (r === null) return [];
+  const byId = nodes.filter((n) => n.id === r);
+  if (byId.length) return byId;
+  const exact = nodes.filter((n) => typeof n.file === 'string' && n.file !== '' && clean(n.file) === r);
+  if (exact.length) return exact;
+  return nodesForFile(r, nodes);
+}
+
+/**
+ * References resolved against a map.
+ * @param {string[]} refs references as `parseMentions` gives them (or a block's `nodes`)
+ * @param {{ id: string, file?: string }[]} nodes
+ * @returns {{ resolved: { ref: string, ids: string[] }[], ids: string[], unresolved: string[] }} `ids`: every node once, in
+ *   order; `unresolved`: the references that are on no node (they stay text)
+ */
+export function resolveMentions(refs, nodes) {
+  const resolved = [];
+  const unresolved = [];
+  const seen = new Set();
+  const list = Array.isArray(refs) ? refs.slice(0, MAX_MENTIONS + MAX_BLOCK_NODES) : [];
+  for (const ref of list) {
+    const found = resolveMention(ref, nodes);
+    if (!found.length) { unresolved.push(ref); continue; }
+    const ids = found.map((n) => n.id);
+    resolved.push({ ref, ids });
+    for (const id of ids) seen.add(id);
+  }
+  return { resolved, ids: [...seen], unresolved };
+}
+
+/**
+ * Everything a set of texts (a thread's messages) points at, before the map is asked: the references of every text and of
+ * its blocks, each once, and the proposal a block names (the first).
+ * @param {string[]} texts
+ * @returns {{ refs: string[], proposal: string | null, truncated: boolean }}
+ */
+export function linksOf(texts) {
+  const refs = [];
+  let proposal = null;
+  let truncated = false;
+  const cap = MAX_MENTIONS * 2;
+  for (const text of texts) {
+    const got = parseMentions(text);
+    truncated ||= got.truncated;
+    for (const ref of [...got.refs, ...(got.block ? got.block.nodes : [])]) {
+      if (refs.includes(ref)) continue;
+      if (refs.length >= cap) { truncated = true; break; }
+      refs.push(ref);
+    }
+    if (proposal === null && got.block && got.block.proposal) proposal = got.block.proposal;
+  }
+  return { refs, proposal, truncated };
+}
+
+/**
+ * The thread a spec PR's text names: `Thread: #n`, or `Closes #n` (also Fixes and Resolves, and their other tenses), outside
+ * code. The first one named. An issue in another repo (`owner/name#n`) is not this repo's thread.
+ * @param {string} body
+ * @returns {number | null}
+ */
+export function threadOfPull(body) {
+  const { prose } = scan(body);
+  // `(?:\s*:)?\s+` and not `\s*:?\s+`: two whitespace runs side by side backtrack against each other, which made a long
+  // run of spaces after "Closes" (or a code block, blanked to spaces) quadratic; this way each run is read once
+  const m = /(?:^|[\s(])(?:thread\s*:|(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)(?:\s*:)?)\s+#([1-9]\d{0,8})\b/i.exec(prose);
+  return m ? Number(m[1]) : null;
+}

package/explorer/explorer.css

@@ -913,3 +913,12 @@ a.hx-forge-row:hover, button.hx-forge-row:hover { background: var(--hx-control-h
 :root[data-theme="light"] .hx-forge-tab[aria-pressed="true"] { box-shadow: 0 1px 3px rgba(15, 23, 42, 0.25); }
 :root[data-theme="light"] .hx-forge { box-shadow: 10px 0 30px -12px rgba(15, 23, 42, 0.18); }
 :root[data-theme="light"] .hx-forge:not(.forge-open) { box-shadow: none; }
+
+/* Threads (forge-panel.js, docs/threads.md): messages as written, read-only; a node's "Mentioned in" opens one */
+.hx-thread-msgs { display: flex; flex-direction: column; gap: 8px; margin: 0; padding: 0; list-style: none; }
+.hx-thread-msg { display: flex; flex-direction: column; gap: 4px; padding: 8px 10px; border: 1px solid var(--hx-line); border-radius: 10px; background: var(--hx-control); }
+.hx-thread-body { margin: 0; color: var(--hx-ink); line-height: 1.5; white-space: pre-wrap; overflow-wrap: anywhere; user-select: text; }
+.hx-thread-nodes { padding-left: 0; }
+.hx-thread-compose { font-family: inherit; min-height: 8em; }
+.hx-thread-open { display: block; max-width: 100%; text-align: left; overflow-wrap: anywhere; }
+#forge-idea[hidden], #idea-form[hidden], #idea-message[hidden] { display: none; }