cornfield 0.10.0 → 0.12.0

package/core/agent-contract.js

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

package/core/agent-contract.schema.json

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

package/core/config.js

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

package/explorer/explorer.css

@@ -796,11 +796,13 @@ button.hx-proposal-item:focus-visible { outline: 2px solid var(--hx-indigo); out
 .hx-forge * { touch-action: pan-y; }
 .hx-forge.forge-open { pointer-events: auto; }
 @media (min-width: 768px) {
-  .hx-forge { position: absolute; top: 0; left: 0; bottom: 0; width: min(400px, calc(100% - 24px)); border-left: 0; transform: translateX(-100%); box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.5); }
+  /* The panel's width is the stage's `--hx-forge-w`, so what makes room for it reads the same number (the Runs view's compare widens it, below) */
+  .hx-stage { --hx-forge-w: min(400px, calc(100% - 24px)); }
+  .hx-forge { position: absolute; top: 0; left: 0; bottom: 0; width: var(--hx-forge-w); border-left: 0; transform: translateX(-100%); box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.5); }
   .hx-forge.forge-open { transform: translateX(0); }
-  /* The proposal bar and the player make room for it */
-  .hx-stage:has(.forge-open) .hx-proposal-bar { left: 412px; width: min(720px, calc(100% - 436px)); }
-  .hx-stage:has(.forge-open):has(.drawer-open) .hx-proposal-bar { width: min(720px, calc(100% - 940px)); }
+  /* The proposal bar and the player make room for it: 12px past its edge, and the node panel's 480px (+24) when that is open too */
+  .hx-stage:has(.forge-open) .hx-proposal-bar { left: calc(var(--hx-forge-w) + 12px); width: min(720px, calc(100% - var(--hx-forge-w) - 36px)); }
+  .hx-stage:has(.forge-open):has(.drawer-open) .hx-proposal-bar { width: min(720px, calc(100% - var(--hx-forge-w) - 540px)); }
 }
 @media (max-width: 767px) {
   .hx-forge:not(.forge-open) { display: none; }
@@ -924,3 +926,46 @@ a.hx-forge-row:hover, button.hx-forge-row:hover { background: var(--hx-control-h
 .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; }
+
+/* ---- agent runs on the map (explorer/runs-map.js, issue #82) ---- */
+.hx-run-overlay { position: absolute; inset: 0; z-index: 2; overflow: hidden; pointer-events: none; }
+.hx-run-overlay[hidden] { display: none; }
+.hx-run-mark { position: absolute; width: 0; height: 0; --r: 14px; }
+.hx-run-ring { position: absolute; left: calc(var(--r) * -1); top: calc(var(--r) * -1); width: calc(var(--r) * 2); height: calc(var(--r) * 2); box-sizing: border-box; border-radius: 50%; border: 2px solid var(--hx-teal-text); }
+/* In flight: the ring pulses outward and fades; when motion is reduced it is a still, slightly thicker ring */
+.hx-run-mark--flight .hx-run-ring { animation: hx-run-pulse 1.8s ease-out infinite; }
+@keyframes hx-run-pulse { 0% { transform: scale(0.9); opacity: 1; } 100% { transform: scale(1.55); opacity: 0.1; } }
+.hx-run-overlay.is-static .hx-run-ring { animation: none; transform: none; opacity: 1; border-width: 3px; }
+@media (prefers-reduced-motion: reduce) { .hx-run-ring { animation: none !important; transform: none; opacity: 1; border-width: 3px; } }
+/* Collision: dashed, a sign and words; the same ring whether or not colour is seen */
+.hx-run-mark--collision .hx-run-ring { border: 3px dashed var(--hx-amber); animation: none; }
+.hx-run-tag { position: absolute; left: 0; top: calc(var(--r) + 4px); transform: translateX(-50%); white-space: nowrap; padding: 1px 7px; border-radius: 9999px; border: 1px solid var(--hx-amber); background: var(--hx-well); color: var(--hx-amber); font-size: 11px; font-weight: 700; }
+.hx-run-swatch { display: inline-block; width: 14px; height: 14px; flex: none; box-sizing: border-box; border-radius: 50%; border: 2px solid var(--hx-teal-text); }
+.hx-run-swatch--collision { border: 2px dashed var(--hx-amber); }
+
+/* The Runs view (forge-panel.js, runs-view.js): each run, its limits beside what was reported, its timeline; the compare puts profiles side by side */
+.hx-runs-list { display: flex; flex-direction: column; gap: 8px; margin: 0; padding: 0; list-style: none; }
+.hx-run { display: flex; flex-direction: column; gap: 4px; padding: 8px 10px; border: 1px solid var(--hx-line); border-radius: 10px; background: var(--hx-control); overflow-wrap: anywhere; min-width: 0; }
+.hx-run-head { display: flex; flex-wrap: wrap; align-items: baseline; gap: 4px 8px; }
+.hx-run-actions { display: flex; flex-wrap: wrap; gap: 6px; }
+.hx-run-collide { margin: 0; padding: 2px 8px; border: 1px dashed var(--hx-amber); border-radius: 8px; color: var(--hx-amber); font-weight: 600; }
+.hx-run-limits { display: grid; grid-template-columns: auto 1fr; gap: 0 10px; margin: 0; font-size: 11px; }
+.hx-run-limits dt { color: var(--hx-slate-300); font-weight: 600; }
+.hx-run-limits dd { margin: 0; color: var(--hx-text-2); }
+.hx-run-timeline { display: flex; flex-direction: column; gap: 4px; margin: 0; padding: 0 0 0 18px; font-size: 11px; }
+.hx-run-timeline li { color: var(--hx-text-2); }
+.hx-run-timeline time { color: var(--hx-slate-300); margin-right: 6px; }
+.hx-run-note { display: block; color: var(--hx-slate-300); white-space: pre-wrap; }
+.hx-run-compare { border: 1px solid var(--hx-line); border-left: 4px solid var(--hx-teal-strong); border-radius: 10px; padding: 8px; display: flex; flex-direction: column; gap: 6px; }
+.hx-run-compare-title { margin: 0; font-size: 12px; font-weight: 700; color: var(--hx-text-1); }
+.hx-run-columns { display: grid; grid-template-columns: 1fr; gap: 8px; margin: 0; padding: 0; list-style: none; }
+@media (min-width: 1100px) {
+  .hx-stage:has(.hx-forge .hx-run-compare) { --hx-forge-w: min(780px, calc(100% - 24px)); }
+  .hx-run-columns { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+}
+/* With the node panel open as well, a 780px compare only fits beside it from 1600px: below that the panel keeps its width and the
+   profiles stack, so neither panel nor the proposal bar between them is covered */
+@media (min-width: 1100px) and (max-width: 1599px) {
+  .hx-stage:has(.hx-forge .hx-run-compare):has(.drawer-open) { --hx-forge-w: min(400px, calc(100% - 24px)); }
+  .hx-stage:has(.drawer-open) .hx-run-columns { grid-template-columns: 1fr; }
+}

package/explorer/forge-panel.js

@@ -69,8 +69,10 @@ import { relativeTime } from './review-model.js';
 import { LAYER_DEFS, toggleLayer } from './layers.js';
 import { WORK_URL, groupWork, filterGroups, groupWords, workStatus, markWords } from './agents-model.js';
 import {
-  RUNS_URL, runsUrl, stopUrl, KINDS, aboutWords, statusWords, statusWhy, runMeta, canStop, runsStatus, startBody, startWords, stopWords, confirmStartWords,
+  RUNS_URL, runsUrl, stopUrl, KINDS, aboutWords, statusWords, statusWhy, runMeta, canStop, runsStatus, triggerNotice, startBody, startWords, stopWords, confirmStartWords, litOfRun, changeWords,
 } from './runs-model.js';
+import { runsHtml } from './runs-view.js';
+import { setRunsOnMap, clearRunsOnMap } from './runs-map.js';
 import {
   STATES, defaultFilters, listUrl, pullUrl, serverState, filterItems, facetsOf, stateWords, metaWords, checkWords, checksWords, litFor, errorWords,
   landingUrl, cancelLandingUrl, landingWords, mergeBlock, rerunWhy, confirmMerge, mergeBody, actionUrl, actionWords,
@@ -116,6 +118,8 @@ const ui = {
   notes: freshNotes(), // the Release notes view
   runs: null, // { data, error } of the Agents tab's runs: what /api/agent-runs answered
   runNote: null, // { text, ok }: what the last Stop came to
+  runSel: null, // the run lit on the map (Light on the map), by id
+  runTimelines: new Set(), // the runs whose timeline is open
   agent: null, // { opener, refs, posting } while the Start an agent dialog is open
 };
 
@@ -130,6 +134,9 @@ function freshIdea() {
 }
 
 let wired = false;
+let runsTimer = 0;
+/** How often the runs are read again while one is open */
+export const RUNS_POLL_MS = 60_000;
 let threadToken = 0;
 let indexToken = 0;
 let indexLoading = false;
@@ -188,11 +195,46 @@ async function loadWork(refresh, token) {
 }
 
 /** Loads the runs for the Agents tab (a refresh also has cornfield look at the forge for their reports first); a failure is a line, never a blank panel */
-async function loadRuns(refresh) {
+async function loadRuns(refresh, { say = true } = {}) {
+  const before = ui.runs && ui.runs.data ? ui.runs.data.runs : null;
   const res = await request(runsUrl(refresh), refresh);
   ui.runs = res.ok && Array.isArray(res.body.runs) ? { data: res.body, error: '' } : { data: ui.runs && ui.runs.data, error: errorWords(res.status, res.body) };
+  if (!(ui.runs && ui.runs.data)) return;
+  // The map shows the open runs' nodes; a run lit on the map follows its nodes; what changed is said, once the first answer is in
+  setRunsOnMap(ui.runs.data.runs);
+  syncRunsPoll();
+  if (ui.runSel) relightRun();
+  const said = say ? changeWords(before, ui.runs.data.runs) : [];
+  if (said.length) announce(said.join('. '));
 }
 
+/**
+ * Looks at the runs again in `RUNS_POLL_MS`, but only while one is open: a run's answer that has none open disarms it, and the next answer
+ * with one open (a run requested here, or a look from elsewhere) arms it again. One timer at most; never while the page is hidden or put
+ * away (`pagehide`). So the marks on the map and the words follow the runs.
+ */
+function syncRunsPoll() {
+  const open = !!(ui.runs && ui.runs.data && ui.runs.data.open > 0);
+  if (!open || pageAway) {
+    clearTimeout(runsTimer);
+    runsTimer = 0;
+    return;
+  }
+  if (runsTimer) return;
+  runsTimer = setTimeout(async () => {
+    runsTimer = 0;
+    if (!(typeof document !== 'undefined' && document.hidden)) {
+      await loadRuns(false);
+      paint();
+    }
+    syncRunsPoll();
+  }, RUNS_POLL_MS);
+}
+/** The page is being put away (closed, or into the back-forward cache): no look until it is shown again */
+let pageAway = false;
+function onPageHide() { pageAway = true; syncRunsPoll(); }
+function onPageShow() { pageAway = false; syncRunsPoll(); }
+
 /** Loads the list the kind and state name (again, past the server's cache, on a refresh) */
 async function loadList(refresh = false, quiet = false) {
   const token = ++listToken;
@@ -293,7 +335,10 @@ export function clearPull() {
 /** What the selected pull request lights, worked out again: for the nodes now on the map */
 function relight() {
   ui.nodesSeen = state.nodes;
-  if (ui.threadDetail) {
+  if (ui.runSel) {
+    const run = runById(ui.runSel);
+    state.forgeLit = run ? litOfRun(run) : null;
+  } else if (ui.threadDetail) {
     ui.litThread = litForThread(ui.threadDetail.thread, state.nodes);
     state.forgeLit = { changed: ui.litThread.changed, failing: ui.litThread.failing };
   } else if (ui.deployItem) {
@@ -359,6 +404,7 @@ export function clearDeploy() {
 
 /** Forgets the selected thread without painting: another thing is being selected */
 function dropThread() {
+  ui.runSel = null;
   threadToken++;
   ui.thread = null;
   ui.threadDetail = null;
@@ -370,6 +416,7 @@ function dropThread() {
 async function selectThread(n) {
   const token = ++threadToken;
   pullToken++;
+  ui.runSel = null;
   ui.selected = null;
   ui.detail = null;
   ui.detailError = '';
@@ -924,6 +971,8 @@ function findAgain(el) {
   if (el.dataset.forgeRerun) return `[data-forge-rerun="${el.dataset.forgeRerun}"]`;
   if (el.dataset.forgeAgent) return `[data-forge-agent="${el.dataset.forgeAgent}"]`;
   if (el.dataset.forgeStop) return `[data-forge-stop="${el.dataset.forgeStop}"]`;
+  if (el.dataset.runSelect) return `[data-run-select="${el.dataset.runSelect}"]`;
+  if (el.dataset.runTimeline) return `[data-run-timeline="${el.dataset.runTimeline}"]`;
   return null;
 }
 
@@ -1002,22 +1051,59 @@ function paintRuns() {
   note.hidden = !words;
   note.className = `hx-forge-notice${!(ui.runs && ui.runs.error) && ui.runNote && ui.runNote.ok ? ' hx-forge-notice--ok' : ''}`;
   note.textContent = words;
+  const trig = $('forge-runs-trigger');
+  if (trig) {
+    const skipped = data ? triggerNotice(data) : '';
+    trig.hidden = !skipped;
+    trig.textContent = skipped;
+  }
   const list = $('forge-runs-list');
   if (!data) { list.innerHTML = ''; return; }
-  list.innerHTML = data.runs.length ? data.runs.map(runHtml).join('') : '<li class="hx-forge-empty hx-faint">No agent has been asked for yet. Start one from an issue or a proposal.</li>';
+  list.innerHTML = data.runs.length ? runsHtml(viewContext(), data.runs) : '<li class="hx-forge-empty hx-faint">No agent has been asked for yet. Start one from an issue or a proposal.</li>';
+}
+
+/** What the Runs view needs to know of the page */
+function viewContext() {
+  const f = ui.config && ui.config.forge;
+  const base = f && safeUrl(f.url) ? f.url.replace(/\/+$/, '') : null;
+  return {
+    esc: escHtml, safeUrl, forgeName: forgeName(), forgeType: f ? f.type : 'github', repoUrl: base && f.repo ? `${base}/${f.repo}` : null,
+    now: now(), nodes: state.nodes, selected: ui.runSel, timelines: ui.runTimelines, busy: !!ui.busy,
+  };
 }
 
-function runHtml(run) {
-  const links = [
-    safeUrl(run.comment && run.comment.url) ? `<a class="hx-link" href="${escHtml(run.comment.url)}" target="_blank" rel="noreferrer">Request on ${escHtml(forgeName())} <span class="hx-sr-only">(new tab)</span></a>` : '',
-    run.pull && safeUrl(run.pull.url) ? `<a class="hx-link" href="${escHtml(run.pull.url)}" target="_blank" rel="noreferrer">Pull request #${run.pull.number} <span class="hx-sr-only">(new tab)</span></a>${run.pull.trusted ? '' : ' <span class="hx-faint">(not from a runner, so it moves nothing)</span>'}` : '',
-    run.report && safeUrl(run.report.url) ? `<a class="hx-link" href="${escHtml(run.report.url)}" target="_blank" rel="noreferrer">Runner\'s logs <span class="hx-sr-only">(new tab)</span></a>` : '',
-  ].filter(Boolean).join(' · ');
-  const why = statusWhy(run);
-  const note = run.report && run.report.note ? `<p class="hx-forge-meta">Runner: ${escHtml(run.report.note)}</p>` : '';
-  const stop = canStop(run) ? `<button type="button" class="hx-btn hx-forge-act" data-forge-stop="${escHtml(run.runId)}" aria-label="Stop run ${escHtml(run.runId)}"${ui.busy ? ' disabled' : ''}>Stop</button>` : '';
-  return `<li class="hx-forge-file"><span class="hx-forge-state hx-forge-state--${escHtml(run.status === 'done' || run.status === 'merged' ? 'success' : run.status === 'failed' ? 'failure' : run.status === 'quiet' || run.status === 'stop-requested' ? 'queued' : 'running')}">${escHtml(statusWords(run))}</span> <span class="hx-name">${escHtml(run.kind)} on ${escHtml(aboutWords(run.refs))}</span> ${stop}
-    <p class="hx-forge-meta">${escHtml(runMeta(run, now()))}</p>${why ? `<p class="hx-forge-why hx-faint">${escHtml(why)}</p>` : ''}${note}${links ? `<p class="hx-forge-meta">${links}</p>` : ''}</li>`;
+const runById = (id) => ((ui.runs && ui.runs.data && ui.runs.data.runs) || []).find((r) => r.runId === id) || null;
+
+/** The nodes of a selected run, worked out again (the runs were read again, or the map changed) */
+function relightRun() {
+  if (!runById(ui.runSel)) ui.runSel = null;
+  relight();
+}
+
+/** Lights the nodes of a run on the map, like a pull request; the same button lets go of it */
+function selectRun(id) {
+  const run = runById(id);
+  if (!run) return;
+  if (ui.runSel === id) {
+    ui.runSel = null;
+    relight();
+    announce(`Run ${id} no longer lit on the map`);
+    return;
+  }
+  const had = ui.runSel;
+  pullToken++;
+  dropThread();
+  Object.assign(ui, { selected: null, detail: null, detailError: '', lit: null, landing: null, note: null, deploy: null, deployItem: null, litDeploy: null });
+  ui.runSel = id;
+  relight();
+  const n = (run.nodes || []).length;
+  announce(n ? `Run ${id}: ${n} ${n === 1 ? 'node' : 'nodes'} lit on the map${had ? '' : ''}` : `Run ${id} has no node on the map yet`);
+}
+
+/** Opens or closes the timeline of a run (it stays open when the list is drawn again) */
+function toggleTimeline(id) {
+  if (ui.runTimelines.has(id)) ui.runTimelines.delete(id); else ui.runTimelines.add(id);
+  paint();
 }
 
 /** The panel's lines for the Release notes view: the status, a failure, the rate limit; the rest is paintNotes */
@@ -1039,11 +1125,11 @@ function drawNotes() {
 function paintButton() {
   const btn = $('forge-btn');
   if (!btn) return;
-  const lit = ui.selected !== null || !!ui.deployItem || ui.thread !== null;
+  const lit = ui.selected !== null || !!ui.deployItem || ui.thread !== null || !!ui.runSel;
   const tag = $('forge-btn-lit');
   tag.hidden = !lit;
-  tag.textContent = ui.thread !== null ? `thread #${ui.thread}` : ui.deployItem ? 'deploy' : lit ? `#${ui.selected}` : '';
-  btn.setAttribute('aria-label', ui.thread !== null ? `Issues and pull requests, thread ${ui.thread} selected` : ui.deployItem ? 'Issues and pull requests, a deploy selected' : lit ? `Issues and pull requests, pull request ${ui.selected} selected` : 'Issues and pull requests');
+  tag.textContent = ui.runSel ? 'run' : ui.thread !== null ? `thread #${ui.thread}` : ui.deployItem ? 'deploy' : lit ? `#${ui.selected}` : '';
+  btn.setAttribute('aria-label', ui.runSel ? 'Issues and pull requests, a run lit on the map' : ui.thread !== null ? `Issues and pull requests, thread ${ui.thread} selected` : ui.deployItem ? 'Issues and pull requests, a deploy selected' : lit ? `Issues and pull requests, pull request ${ui.selected} selected` : 'Issues and pull requests');
   btn.setAttribute('aria-expanded', String(ui.open));
 }
 
@@ -1374,7 +1460,7 @@ async function stopRun(runId) {
   ui.busy = '';
   ui.runNote = { text: stopWords(res.status, res.body, runId), ok: res.ok };
   announce(ui.runNote.text);
-  await loadRuns(false);
+  await loadRuns(false, { say: false });
   paint();
 }
 
@@ -1508,6 +1594,10 @@ function onClick(e) {
   if (agent) { openAgent(agent.dataset.forgeAgent, `[data-forge-agent="${agent.dataset.forgeAgent}"]`); return; }
   const stop = t.closest('[data-forge-stop]');
   if (stop) { stopRun(stop.dataset.forgeStop); return; }
+  const pick = t.closest('[data-run-select]');
+  if (pick) { selectRun(pick.dataset.runSelect); return; }
+  const timeline = t.closest('[data-run-timeline]');
+  if (timeline) { toggleTimeline(timeline.dataset.runTimeline); return; }
   const unland = t.closest('[data-forge-landing-cancel]');
   if (unland) { cancelLanding(Number(unland.dataset.forgeLandingCancel)); return; }
   const merge = t.closest('[data-forge-merge]');
@@ -1604,6 +1694,10 @@ export function initForgePanel(config, opts = {}) {
   registerSheet('forge', panel);
   paintFilters();
   paint();
+  // The map shows the open runs whether or not the panel is open: read them once now, and again now and then while any is open
+  if (config.agents && config.agents.runs) {
+    loadRuns(false).then(() => { if (ui.kind === 'work') paint(); }, () => {});
+  }
   if (!wired) {
     wired = true;
     btn.addEventListener('click', toggleForge);
@@ -1611,6 +1705,10 @@ export function initForgePanel(config, opts = {}) {
     panel.addEventListener('change', onChange);
     panel.addEventListener('input', onInput);
     panel.addEventListener('keydown', onKey);
+    if (typeof window !== 'undefined') {
+      window.addEventListener('pagehide', onPageHide);
+      window.addEventListener('pageshow', onPageShow);
+    }
     const agent = agentEl();
     if (agent) {
       agent.addEventListener('click', onAgentClick);
@@ -1651,5 +1749,9 @@ export function resetForgePanelForTests(clock = () => Date.now()) {
   indexCache = null;
   state.forgeLit = null;
   state.threadIndex = null;
-  Object.assign(ui, { thread: null, threadDetail: null, threadError: '', litThread: null, idea: freshIdea(), config: null, open: false, kind: 'pulls', filters: defaultFilters(), lists: {}, work: null, workFilters: { agentsOnly: false, finished: false }, loading: false, error: '', selected: null, detail: null, landing: null, detailError: '', lit: null, deploy: null, deployItem: null, litDeploy: null, nodesSeen: null, busy: '', note: null, confirm: null, actNote: null, notes: freshNotes(), runs: null, runNote: null, agent: null });
+  clearTimeout(runsTimer);
+  runsTimer = 0;
+  pageAway = false;
+  clearRunsOnMap();
+  Object.assign(ui, { runSel: null, runTimelines: new Set(), thread: null, threadDetail: null, threadError: '', litThread: null, idea: freshIdea(), config: null, open: false, kind: 'pulls', filters: defaultFilters(), lists: {}, work: null, workFilters: { agentsOnly: false, finished: false }, loading: false, error: '', selected: null, detail: null, landing: null, detailError: '', lit: null, deploy: null, deployItem: null, litDeploy: null, nodesSeen: null, busy: '', note: null, confirm: null, actNote: null, notes: freshNotes(), runs: null, runNote: null, agent: null });
 }

package/explorer/index.html

@@ -48,6 +48,13 @@
           <div id="flow-legend" hidden></div>
           <div id="cloud-legend" class="hx-menu-section" hidden></div>
 
+          <!-- What the marks of agent runs mean, while there are runs on the map (runs-map.js) -->
+          <div id="runs-legend" class="hx-menu-section" hidden>
+            <div class="hx-menu-title"><span>Agent runs</span></div>
+            <div class="hx-legend-row"><span class="hx-run-swatch hx-run-swatch--flight" aria-hidden="true"></span><span>In flight: a pulsing ring (still under reduced motion)</span></div>
+            <div class="hx-legend-row"><span class="hx-run-swatch hx-run-swatch--collision" aria-hidden="true"></span><span>Collision: dashed ring, ⚠ and the words, where two open runs change one node</span></div>
+          </div>
+
           <!-- What a proposal's marks mean, while one is open (proposal.js) -->
           <div id="proposal-legend" class="hx-menu-section" hidden>
             <div class="hx-menu-title"><span>Proposal marks</span></div>
@@ -171,6 +178,8 @@
     <p id="map-announcer" class="hx-sr-only" role="status" aria-live="polite"></p>
     <!-- Every label, drawn on its own transparent canvas over the map (explorer/labels.js); the map canvas still gets the pointer -->
     <canvas id="label-canvas" aria-hidden="true"></canvas>
+    <!-- The nodes agent runs are changing, marked over the map (explorer/runs-map.js): a picture; the Runs view says the same in words -->
+    <div id="run-overlay" class="hx-run-overlay" aria-hidden="true" hidden></div>
 
     <!-- Below 768px the proposal bar, the scenario player and the node panel stack here as bottom sheets (sheets.js); from 768px the dock is display: contents -->
     <div id="sheet-dock" class="hx-dock">
@@ -270,6 +279,7 @@
           <h3 id="forge-runs-title" class="hx-forge-runs-title">Agent runs</h3>
           <p id="forge-runs-status" class="hx-forge-meta hx-faint"></p>
           <p id="forge-runs-note" class="hx-forge-notice" hidden></p>
+          <p id="forge-runs-trigger" class="hx-forge-notice" hidden></p>
           <ul id="forge-runs-list" class="hx-forge-files" aria-label="Runs"></ul>
         </section>
         <section id="forge-detail" class="hx-forge-detail" aria-label="Selected pull request" hidden></section>

package/explorer/layers.js

@@ -34,6 +34,7 @@ export const LAYER_DEFS = [
   { key: 'container', label: 'Containers', color: '#d6d3d1', desc: 'One service of a stack, from its compose file' },
   { key: 'device', label: 'Devices', color: '#2dd4bf', desc: 'Cameras, and live: phones, NFC tags, Home Assistant devices', live: true },
   { key: 'house', label: 'House', color: '#a3e635', desc: 'Floors and rooms (live)', live: true },
+  { key: 'runs', label: 'Runs in flight', color: '#5eead4', desc: 'A pulsing ring on the nodes an open agent run is changing; a dashed ring and a warning where two runs change the same node', overlay: true },
   { key: 'persona', label: 'People', color: '#fb7185', desc: 'Personas, with a live count of their accounts (never a name)', live: true },
 ];
 
@@ -68,6 +69,7 @@ export function renderLayerToggles() {
   const counts = {};
   state.nodes.forEach((n) => { const key = n.type === 'external' ? externalLayer(n) : layerOf(n.type); counts[key] = (counts[key] || 0) + 1; });
   counts.flow = state.edges.filter((e) => e.kind === 'flow').length;
+  counts.runs = state.runsMap ? state.runsMap.flight.size : 0;
 
   container.innerHTML = LAYER_DEFS.map((layer) => {
     const on = state.activeLayers[layer.key] !== false;

package/explorer/render.js

@@ -150,6 +150,14 @@ function paint() {
   // The labels repaint only when the camera, the scene or the size changed, never on a packet frame
   const labels = getLabelLayer();
   if (labels) labels.draw(scene, state.camera);
+  paintHooks.forEach((fn) => fn(scene, state.camera));
+}
+
+/** Things drawn over the map by the page itself (the runs' marks, explorer/runs-map.js): called after each draw with the scene and the camera */
+const paintHooks = new Set();
+export function onPaint(fn) {
+  paintHooks.add(fn);
+  return () => paintHooks.delete(fn);
 }
 
 const scheduler = createFrameScheduler({