cornfield 0.11.0 → 0.12.0

package/core/config.js

@@ -152,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: {}, on: {} },
+  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' },
@@ -165,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', 'on'];
+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() !== '';
@@ -363,6 +363,7 @@ export const triggersOf = (config) => Object.entries(isObject(config.agents?.on)
 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) {

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, triggerNotice, 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;
 }
 
@@ -1010,20 +1059,51 @@ function paintRuns() {
   }
   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,
+  };
+}
+
+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`);
 }
 
-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>`;
+/** 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 */
@@ -1045,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));
 }
 
@@ -1380,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();
 }
 
@@ -1514,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]');
@@ -1610,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);
@@ -1617,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);
@@ -1657,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">

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({

package/explorer/runs-map.js

@@ -0,0 +1,135 @@
+/**
+ * @module explorer/runs-map
+ *
+ * Agent runs on the map (issue #82, spec 0005 D9): the nodes an open run is changing **pulse**, and a node two or more open runs are
+ * changing carries a **collision** mark. The marks are a layer of their own over the map (`#run-overlay`, a DOM layer, so one drawing serves the
+ * Canvas 2D and the WebGL renderer, and the pulse is plain CSS that `prefers-reduced-motion` turns into a still ring):
+ *
+ *   - in flight   a ring that pulses (still under reduced motion: a thicker ring, no movement)
+ *   - collision   a dashed ring, a warning sign and the words "Collision" with how many runs: shape and text, never colour alone
+ *
+ * The layer is a toggle in the Layers menu ("Runs in flight", on unless turned off). The layer is decoration for the eye (`aria-hidden`):
+ * what a screen reader gets is the Runs view, which names each run's nodes and collisions in words, and the live region, which says when a
+ * state or a collision changes. The positions come from the scene the map just drew, so they follow every view, zoom and pan.
+ */
+
+import { state } from './state.js';
+import { render, onPaint } from './render.js';
+import { overlayOf } from './runs-model.js';
+import { flowReduceMotion } from './flows.js';
+
+/** The most marks drawn at once: past this the Runs view still lists them all */
+export const MAX_MARKS = 80;
+
+/** The key of the layer in the Layers menu and `state.activeLayers` */
+export const RUNS_LAYER = 'runs';
+
+/** @type {Map<string, HTMLElement>} the marks on the page by `<kind>:<node id>`, kept so a pulse is not restarted by every pan */
+const marks = new Map();
+let wired = false;
+/** What the marks were last placed for: a paint with the same scene, camera, runs, layer and motion moves nothing (packet frames) */
+let placed = '';
+let placedFor = null;
+let placedScene = null;
+let placedLayer = null;
+let reduce = null;
+
+/** Whether motion is reduced: the page's setting, or a test's */
+const reducedMotion = () => (reduce === null ? flowReduceMotion : reduce);
+/** For tests: force reduced motion on or off (null: follow the page's setting) */
+export function setReducedMotionForTests(on) { reduce = on; }
+
+/** Whether the layer is on */
+export const runsLayerOn = () => state.activeLayers[RUNS_LAYER] !== false;
+
+/** Hands the map the runs the API listed: what pulses and what collides is worked out here, and the map is drawn again */
+export function setRunsOnMap(runs) {
+  state.runsMap = Array.isArray(runs) && runs.length ? { ...overlayOf(runs), runs } : null;
+  wire();
+  paintLegend();
+  render();
+}
+
+/** Takes the marks off (the panel is reset, or there is no forge) */
+export function clearRunsOnMap() {
+  state.runsMap = null;
+  clearMarks();
+  paintLegend();
+}
+
+function wire() {
+  if (wired) return;
+  wired = true;
+  onPaint((scene, camera) => syncRunOverlay(scene, camera));
+}
+
+function clearMarks() {
+  for (const el of marks.values()) el.remove();
+  marks.clear();
+  placed = '';
+}
+
+/** The words on a collision mark */
+export const collisionTag = (n) => `Collision · ${n} runs`;
+
+/**
+ * Puts the marks on the nodes the scene drew, at the camera. Marks are kept between frames (only their place changes), so a pan does not
+ * restart the pulse.
+ * @param {{ nodes: { id: string, x: number, y: number, r: number, alpha: number }[] }} scene
+ * @param {{ x: number, y: number, zoom: number }} camera
+ */
+export function syncRunOverlay(scene, camera) {
+  const layer = typeof document !== 'undefined' ? document.getElementById('run-overlay') : null;
+  if (!layer) return;
+  const map = state.runsMap;
+  if (!map || !runsLayerOn() || (!map.flight.size && !map.collide.size)) { if (marks.size) clearMarks(); layer.hidden = true; placed = ''; return; }
+  // The map paints every frame while packets move; the marks only move with the scene or the camera
+  const key = `${scene.version}|${camera.x}|${camera.y}|${camera.zoom}|${reducedMotion()}`;
+  if (key === placed && placedFor === map && placedScene === scene && placedLayer === layer) return;
+  placed = key;
+  placedLayer = layer;
+  placedFor = map;
+  placedScene = scene;
+  layer.hidden = false;
+  layer.classList.toggle('is-static', reducedMotion());
+  const seen = new Set();
+  let n = 0;
+  for (const node of scene.nodes) {
+    if (n >= MAX_MARKS) break;
+    const runs = map.collide.get(node.id) || map.flight.get(node.id);
+    if (!runs || !(node.alpha > 0.2)) continue;
+    const kind = map.collide.has(node.id) ? 'collision' : 'flight';
+    const key = `${kind}:${node.id}`;
+    n += 1;
+    seen.add(key);
+    let el = marks.get(key);
+    if (!el) {
+      el = document.createElement('span');
+      el.className = `hx-run-mark hx-run-mark--${kind}`;
+      el.dataset.node = node.id;
+      el.dataset.kind = kind;
+      el.innerHTML = `<span class="hx-run-ring"></span>${kind === 'collision' ? `<span class="hx-run-tag"><span class="hx-run-sign">⚠</span> ${collisionTag(runs.length)}</span>` : ''}`;
+      layer.append(el);
+      marks.set(key, el);
+    }
+    const r = Math.max(10, (node.r + 9) * camera.zoom);
+    el.style.left = `${(node.x * camera.zoom + camera.x).toFixed(1)}px`;
+    el.style.top = `${(node.y * camera.zoom + camera.y).toFixed(1)}px`;
+    el.style.setProperty('--r', `${r.toFixed(1)}px`);
+  }
+  for (const [key, el] of marks) if (!seen.has(key)) { el.remove(); marks.delete(key); }
+}
+
+/** The legend in the Layers menu: shown while runs are on the map, saying in words what each mark is */
+export function paintLegend() {
+  const el = typeof document !== 'undefined' ? document.getElementById('runs-legend') : null;
+  if (!el) return;
+  el.hidden = !(state.runsMap && (state.runsMap.flight.size || state.runsMap.collide.size));
+}
+
+/** For tests: forget the page */
+export function resetRunsMapForTests() {
+  clearMarks();
+  state.runsMap = null;
+  reduce = null;
+}