scenescout 3.2.0 → 3.3.0

package/dist/engine/live-page.js

@@ -58,6 +58,10 @@ export const LIVE_PAGE = `<!doctype html>
     color: #fff; background: var(--accent); border-radius: 6px; }
   main { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 320px), 1fr)); gap: 12px; padding: 16px; }
   .card { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; overflow: hidden; display: flex; flex-direction: column; }
+  /* Every rule here that sets display beats the browser's own [hidden] rule,
+     so a hidden card stayed on screen with the "nothing matches" notice above
+     it. Say it once, for everything. */
+  [hidden] { display: none !important; }
   .card.stuck { border-color: var(--stuck); }
   .top { display: flex; align-items: center; gap: 8px; padding: 10px 12px 6px; }
   .name { font-weight: 650; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
@@ -118,6 +122,10 @@ export const LIVE_PAGE = `<!doctype html>
   .doing { padding: 0 12px 4px; font-size: 12px; color: var(--text); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
   .doing::before { content: "▸ "; color: var(--accent); }
   .doing.unset { color: var(--stuck); }
+  .pace { padding: 0 12px 4px; font-size: 11px; color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .pace .bad { color: var(--stuck); }
+  header input#filter { font: inherit; font-size: 12px; padding: 4px 8px; border: 1px solid var(--line); border-radius: 6px; background: var(--bg); color: var(--text); min-width: 150px; }
+  #no-match { padding: 16px; color: var(--muted); }
   #focus .feed .a { color: #e6e9ee; }
   #focus .feed .t, #focus .feed .d, #focus .feed .none { color: #98a2b3; }
   #focus .feed .bad { color: #fca5a5; }
@@ -188,12 +196,14 @@ export const LIVE_PAGE = `<!doctype html>
   <span class="spacer"></span>
   <span class="meta" id="counts" data-testid="live-session-counts"></span>
   <span class="actions">
+    <input type="search" id="filter" placeholder="Filter sessions" aria-label="Filter sessions by name, role, objective, task or page" data-testid="live-filter" />
     <button type="button" id="report-open" data-testid="live-report-toggle">Report</button>
     <button type="button" id="all" aria-pressed="false" data-testid="live-all-toggle">Stream all</button>
   </span>
 </header>
 <div id="banner" role="alert" data-testid="live-unreachable-banner">The engine is not answering. It may have exited; this page will pick up again if it comes back.</div>
 <div id="empty" data-testid="live-empty-state">No session is attached yet. Cards appear here as soon as one attaches.</div>
+<div id="no-match" data-testid="live-no-match" hidden></div>
 <div id="finished" data-testid="live-finished-state">
   <h2>The run has finished</h2>
   <p>Its browsers are closed, so there is nothing left to watch. What it found is in the report.</p>
@@ -240,6 +250,8 @@ export const LIVE_PAGE = `<!doctype html>
   var THUMB_EVERY_MS = 3000;
   var cards = {};
   var streamAll = false;
+  /** The header filter, lower-cased. Hides cards; never stops a session running. */
+  var filter = '';
   var focused = null;
   var skew = 0;
   var latest = {};
@@ -364,6 +376,14 @@ export const LIVE_PAGE = `<!doctype html>
     task.setAttribute('data-testid', 'live-card-objective-' + name);
     var doing = el('div', 'doing');
     doing.setAttribute('data-testid', 'live-card-task-' + name);
+    // How long it has been on this task, and how many of its recent steps went
+    // wrong. Both were already in the status payload and reached nobody: the
+    // first only inside the close-up, the second only as a red word in a feed
+    // somebody had to read. On a board of eleven cards, "which one is stuck on
+    // the same thing, and which one is having trouble" is the question being
+    // asked, and it was the one thing the board could not answer.
+    var pace = el('div', 'pace');
+    pace.setAttribute('data-testid', 'live-card-pace-' + name);
     var tool = el('div', 'line');
     var url = el('div', 'line');
     var shot = el('button', 'shot');
@@ -386,9 +406,9 @@ export const LIVE_PAGE = `<!doctype html>
     toggle.setAttribute('data-testid', 'live-card-toggle-' + name);
     var spec = el('span', 'spec');
     foot.appendChild(toggle); foot.appendChild(spec);
-    root.appendChild(top); root.appendChild(task); root.appendChild(doing); root.appendChild(tool); root.appendChild(url); root.appendChild(shot); root.appendChild(feed); root.appendChild(foot);
+    root.appendChild(top); root.appendChild(task); root.appendChild(doing); root.appendChild(pace); root.appendChild(tool); root.appendChild(url); root.appendChild(shot); root.appendChild(feed); root.appendChild(foot);
 
-    var card = { name: name, root: root, role: role, badge: badge, task: task, doing: doing, tool: tool, url: url, shot: shot, img: img, feed: feed, toggle: toggle, spec: spec, live: false };
+    var card = { name: name, root: root, role: role, badge: badge, task: task, doing: doing, pace: pace, tool: tool, url: url, shot: shot, img: img, feed: feed, toggle: toggle, spec: spec, live: false };
     toggle.addEventListener('click', function () { setLive(card, !card.live); });
     shot.addEventListener('click', function () { openFocus(name); });
     img.src = shotUrl(name);
@@ -735,9 +755,31 @@ export const LIVE_PAGE = `<!doctype html>
     card.url.textContent = s.url || '(no page yet)';
     card.url.title = s.url || '';
     card.spec.textContent = [s.mode, s.browser, s.headed ? 'headed' : 'headless'].filter(Boolean).join(' · ');
+    paintPace(card, s);
     renderFeed(card.feed, s.feed);
   }
 
+  /** Steps in the visible feed whose result reads as trouble. */
+  function troubled(feed) {
+    var n = 0;
+    (feed || []).forEach(function (line) { if (BAD_RESULT.test(line.result || '')) n += 1; });
+    return n;
+  }
+
+  function paintPace(card, s) {
+    var on = s.task && s.taskSince ? 'on this for ' + held(Date.now() + skew - Date.parse(s.taskSince)) : '';
+    var bad = troubled(s.feed);
+    card.pace.textContent = '';
+    if (on) card.pace.appendChild(el('span', '', on));
+    if (bad > 0) {
+      if (on) card.pace.appendChild(el('span', '', ' · '));
+      // Only the trouble is red. Reddening the whole line made "on this for
+      // 9s" look like the complaint.
+      card.pace.appendChild(el('span', 'bad', bad + ' of the last ' + s.feed.length + ' steps went wrong'));
+    }
+    card.pace.hidden = !on && bad === 0;
+  }
+
   function openFocus(name) {
     focused = name;
     scrubbed = null;
@@ -827,6 +869,32 @@ export const LIVE_PAGE = `<!doctype html>
     focusTick += 1;
   }
 
+  /**
+   * Whether a session survives the header's filter. Matched against everything
+   * the card already shows, because on a board of eleven the reader is looking
+   * for "the one on the orders register" as often as for a session by name.
+   * Filtering hides cards; it never stops them being polled or streamed, so a
+   * hidden session is still running and still counted in the header.
+   */
+  function matches(s) {
+    if (!filter) return true;
+    var hay = [s.session, s.role, s.objective, s.task, s.url, s.tool].join(' ').toLowerCase();
+    return hay.indexOf(filter) !== -1;
+  }
+
+  function applyFilter() {
+    var shown = 0;
+    Object.keys(cards).forEach(function (name) {
+      var s = latest[name];
+      var keep = !s || matches(s);
+      cards[name].root.hidden = !keep;
+      if (keep) shown += 1;
+    });
+    var none = document.getElementById('no-match');
+    none.hidden = !filter || shown > 0 || Object.keys(cards).length === 0;
+    none.textContent = 'No session matches ' + JSON.stringify(filter) + '.';
+  }
+
   function apply(snap) {
     skew = Date.parse(snap.at) - Date.now();
     var grid = document.getElementById('grid');
@@ -884,6 +952,7 @@ export const LIVE_PAGE = `<!doctype html>
     document.getElementById('engine').textContent = 'engine pid ' + snap.pid + ' · v' + snap.version;
     document.getElementById('counts').textContent = snap.sessions.length + ' session' + (snap.sessions.length === 1 ? '' : 's') +
       ' · ' + counts.running + ' running · ' + counts.idle + ' idle' + (counts.stuck ? ' · ' + counts.stuck + ' stuck' : '');
+    applyFilter();
     paintFocus();
   }
 
@@ -927,7 +996,37 @@ export const LIVE_PAGE = `<!doctype html>
     e.returnValue = '';
   });
   document.getElementById('report-close').addEventListener('click', closeReport);
+  document.getElementById('filter').addEventListener('input', function (e) {
+    filter = String(e.target.value || '').trim().toLowerCase();
+    applyFilter();
+  });
+
+  /**
+   * Step through the timeline from the keyboard.
+   *
+   * Scrubbing a long run by clicking 16px ticks is the kind of thing a mouse
+   * is bad at, and the run being examined is usually the one with hundreds of
+   * steps. Arrow keys move one step, Home and End jump to the ends, and Space
+   * returns to the live picture — only while the close-up is open, and never
+   * while the reader is typing in the filter.
+   */
+  function stepBy(delta) {
+    if (timelineLines.length === 0) return;
+    var at = scrubbed
+      ? timelineLines.findIndex(function (l) { return l.at === scrubbed.at && l.action === scrubbed.action; })
+      : timelineLines.length - 1;
+    var next = Math.max(0, Math.min(timelineLines.length - 1, (at === -1 ? timelineLines.length - 1 : at) + delta));
+    showStep(timelineLines[next]);
+  }
+
   document.addEventListener('keydown', function (e) {
+    if (focused && !reportOpen && e.target !== document.getElementById('filter')) {
+      if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') { e.preventDefault(); stepBy(e.key === 'ArrowLeft' ? -1 : 1); return; }
+      if (e.key === 'Home' || e.key === 'End') { e.preventDefault(); stepBy(e.key === 'Home' ? -1e9 : 1e9); return; }
+      // Back to what the session is showing NOW, which is otherwise a click
+      // on a button the reader has to find.
+      if (e.key === ' ' && scrubbed) { e.preventDefault(); backToLive(); return; }
+    }
     if (e.key !== 'Escape') return;
     if (reportOpen) closeReport();
     else if (focused) closeFocus();

package/dist/engine/live.js

@@ -30,6 +30,10 @@ import { LIVE_PAGE } from "./live-page.js";
 import { JOURNEY_END, JOURNEY_START, TASK_SET } from "./memory.js";
 /** Holds the live view's token, next to status.json. Written owner-only; removed when the engine shuts down. */
 export const LIVE_TOKEN_FILE = "live-token";
+/** This engine's own token file. Shares the directory with other engines, so it carries the pid. */
+export function liveTokenFileName(pid) {
+    return `${LIVE_TOKEN_FILE}.${pid}`;
+}
 /** `SCENESCOUT_LIVE=off` keeps the engine from opening the live view's port at all. */
 export const LIVE_ENV = "SCENESCOUT_LIVE";
 /**
@@ -178,12 +182,68 @@ const statusWrites = new Map();
  * longer one after it (which is what overlapping `writeFile`s produced).
  * Best-effort: a failed write is dropped and the next one lands.
  */
+/**
+ * Whether a process is still there. EPERM means it EXISTS but belongs to
+ * another user; only ESRCH means no such process, and treating both as dead
+ * reported a live engine as stale.
+ */
+export function pidAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err?.code === "EPERM";
+    }
+}
+export function statusFileName(pid) {
+    return `status.${pid}.json`;
+}
+/**
+ * Every engine that has written a status file here, newest first, one entry
+ * per pid. Two engines on one project used to overwrite each other in a single
+ * status.json, so `watch` could only ever find whichever attached last and the
+ * other run was reachable only from the transcript that started it.
+ * status.json is still written for readers from before this, and is used only
+ * when no per-pid file exists.
+ */
+export function liveEngines(dir, isAlive) {
+    let names = [];
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const perPid = names.filter((n) => /^status\.\d+\.json$/.test(n));
+    const out = [];
+    for (const name of perPid.length > 0 ? perPid : names.filter((n) => n === "status.json")) {
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const pid = typeof parsed.pid === "number" ? parsed.pid : NaN;
+        if (!Number.isInteger(pid) || !isAlive(pid))
+            continue;
+        out.push({ pid, status: parsed, file: name });
+    }
+    return out.sort((a, b) => (b.status.at ?? "").localeCompare(a.status.at ?? ""));
+}
 export function writeStatusFile(dir, body) {
     const file = path.join(dir, "status.json");
     const tmp = `${file}.${process.pid}.tmp`;
+    // Both: status.json for readers from before per-pid files, and one named for
+    // this process so a second engine on the same project does not erase it.
+    const mine = path.join(dir, statusFileName(process.pid));
     const next = (statusWrites.get(dir) ?? Promise.resolve())
         .then(() => fs.promises.writeFile(tmp, body))
         .then(() => fs.promises.rename(tmp, file))
+        .then(() => fs.promises.writeFile(mine, body))
         .catch(() => fs.promises.rm(tmp, { force: true }).catch(() => { }));
     statusWrites.set(dir, next);
     return next;

package/dist/engine/memory.js

@@ -25,6 +25,47 @@ export const FINDING_CATEGORIES = [
     "missing-testid",
     "other",
 ];
+/**
+ * Most states a route may keep. A route accumulates one state per distinct
+ * element set, so a register with filters, tabs and paging produces dozens;
+ * one project reached 6,075 states across 48 routes, a 36 MB history parsed
+ * and re-serialised on every save. Coverage is asked per ROUTE, so keeping the
+ * most recent states of each route preserves every answer the gap ledger
+ * needs while dropping the long tail nothing will ask about again.
+ */
+export const MAX_STATES_PER_ROUTE = 40;
+/**
+ * The states to keep. Never drops one a finding points at — a finding's repro
+ * trace and its route identity are read back from it — and never drops the
+ * newest of a route, so a route that was visited stays visited.
+ *
+ * Returns the pruned map rather than mutating, so the rule can be table-tested.
+ */
+export function pruneStates(states, findings, perRoute = MAX_STATES_PER_ROUTE) {
+    const pinned = new Set(findings.map((f) => f.state));
+    const byRoute = new Map();
+    for (const entry of Object.entries(states)) {
+        const route = entry[1].route;
+        const list = byRoute.get(route);
+        if (list)
+            list.push(entry);
+        else
+            byRoute.set(route, [entry]);
+    }
+    const kept = {};
+    let dropped = 0;
+    for (const list of byRoute.values()) {
+        // Newest first, so the survivors are the ones a next run will meet again.
+        list.sort((a, b) => (b[1].lastSeen ?? b[1].firstSeen).localeCompare(a[1].lastSeen ?? a[1].firstSeen));
+        list.forEach(([fp, rec], index) => {
+            if (index < perRoute || pinned.has(fp))
+                kept[fp] = rec;
+            else
+                dropped += 1;
+        });
+    }
+    return { kept, dropped };
+}
 /** An element class must appear on this many routes at minimum before it can count as shared chrome. */
 const CHROME_MIN_ROUTES = 4;
 /** …and on at least this share of all visited routes (a majority — "it's on every page"). */
@@ -684,9 +725,34 @@ export class MemoryStore {
             constraints: "Constraints — rules discovered the hard way (gates, preconditions, limits)",
             risks: "Risks & watchpoints — fragile areas worth re-testing every run",
             glossary: "Glossary — domain terms and what they mean here",
+            setup: "Setup — how to get this app into a testable state (how a login state is regenerated, what has to be running)",
         };
         return `## ${titles[section] ?? section}`;
     }
+    /**
+     * What earlier runs recorded about getting this app testable, if anything.
+     *
+     * Read back by the auth-failure message. A storage state expires on a timer
+     * nobody remembers, and "regenerate it" is advice the reader already had;
+     * the command that worked last time is the part worth keeping, and it is
+     * exactly the kind of thing a run pays to find out and then forgets.
+     */
+    setupRecipe() {
+        if (!fs.existsSync(this.assumptionsPath))
+            return [];
+        const text = fs.readFileSync(this.assumptionsPath, "utf8");
+        const heading = MemoryStore.sectionHeading("setup");
+        const start = text.indexOf(heading);
+        if (start === -1)
+            return [];
+        const rest = text.slice(start + heading.length);
+        const end = rest.indexOf("\n## ");
+        return (end === -1 ? rest : rest.slice(0, end))
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.startsWith("- "))
+            .map((l) => l.slice(2).trim());
+    }
     readAssumptions() {
         if (!fs.existsSync(this.assumptionsPath))
             return "(no ASSUMPTIONS.md yet — record what you learn with scout_note as you explore)";
@@ -725,13 +791,43 @@ export class MemoryStore {
         this.flush();
         return f;
     }
+    /**
+     * Record what a re-test of this finding found. "gone" resolves it; the other
+     * two leave it open and stamp the confirmation, which is what lets the report
+     * stop describing a finding somebody checked yesterday as unverified.
+     */
+    verifyFinding(id, verdict, note) {
+        const f = this.data.findings.find((x) => x.id === id);
+        if (!f)
+            return null;
+        f.verdict = verdict;
+        f.verifiedAt = new Date().toISOString();
+        if (note)
+            f.verifyNote = redactSecrets(note).slice(0, 500);
+        else
+            delete f.verifyNote;
+        if (verdict === "gone")
+            f.status = "resolved";
+        this.flush();
+        return f;
+    }
     load() {
         if (!fs.existsSync(this.memoryPath))
             return structuredClone(EMPTY);
         try {
             const raw = JSON.parse(fs.readFileSync(this.memoryPath, "utf8"));
-            if (raw.version === 1)
+            if (raw.version === 1) {
+                // Prune once, on open: the long tail of per-route states is what makes
+                // an old history slow to parse and re-serialise, and it answers no
+                // question the gap ledger asks. Findings and the newest states of
+                // every route are kept, so coverage does not regress.
+                const { kept, dropped } = pruneStates(raw.states ?? {}, raw.findings ?? []);
+                if (dropped > 0) {
+                    raw.states = kept;
+                    this.prunedStates = dropped;
+                }
                 return raw;
+            }
             this.loadWarning = `memory.json has unknown version ${String(raw.version)} — starting fresh.`;
         }
         catch (err) {
@@ -783,6 +879,8 @@ export class MemoryStore {
         // Deliberately NOT unref'd: a pending coverage write briefly holds the
         // process open so an exit without scout_close still lands the last save.
     }
+    /** How many states the last open pruned. Reported once, so a shrinking history is never silent. */
+    prunedStates = 0;
     /** Set when a debounced background write failed — cleared on the next successful write. Surfaced by scout_coverage/scout_close so a broken persistence path is never silently invisible. */
     lastSaveError = null;
     /**
@@ -907,6 +1005,7 @@ export class MemoryStore {
             this.data.states[fingerprint] = rec;
         }
         rec.visits += 1;
+        rec.lastSeen = new Date().toISOString();
         const present = new Set(elementKeys);
         for (const key of elementKeys) {
             if (!rec.elements[key])

package/dist/engine/oracles.js

@@ -137,6 +137,15 @@ export class OracleMonitor {
     noteInjection(detail, url) {
         this.record({ kind: "dom_injection", severity: "high", detail, url });
     }
+    /**
+     * The page contradicted a request that was refused during the same action:
+     * a refused list rendered as an empty state, or a refused save reported as a
+     * success. Found by the engine's DOM scan (claims.ts), like injections, so
+     * it is reported through here rather than by a page event.
+     */
+    noteContradiction(c, url) {
+        this.record({ kind: c.kind, severity: "high", detail: c.detail, url });
+    }
     record(v) {
         if (isPolicyInduced(v, this.lastPolicyBlockAt === null ? null : Date.now() - this.lastPolicyBlockAt)) {
             this.policyAttributed += 1;

package/dist/engine/pace.js

@@ -0,0 +1,112 @@
+/**
+ * Log entries that are not actions: a stated task, an attach, the note that a
+ * resource was created. They carry no browser work and take no time, so
+ * counting them inflates the action count and drags the median gap toward
+ * zero. One real run logged 325 entries of which 107 were stated tasks.
+ */
+const MARKER_ACTIONS = new Set(["task", "attach", "created-resource", "journey:start", "journey:end", "record:full", "record:failed"]);
+/** Whether a log entry represents work the browser actually did. */
+export function isActing(action) {
+    return !MARKER_ACTIONS.has(action);
+}
+/** A gap longer than this is the agent thinking, not the browser working. */
+export const IDLE_GAP_MS = 30_000;
+/** A session with no action for this long is probably forgotten, and is holding a browser for nothing. */
+export const STALE_SESSION_MS = 5 * 60_000;
+function median(sorted) {
+    if (sorted.length === 0)
+        return 0;
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
+}
+/**
+ * The pace of each session in the log, and of the run as a whole. `nowMs` is
+ * passed rather than read so the numbers are the same every time they are
+ * computed from the same log.
+ */
+export function measurePace(log, nowMs, attached = []) {
+    const stillOpen = new Set(attached);
+    const bySession = new Map();
+    for (const entry of log) {
+        if (!isActing(entry.action))
+            continue;
+        const name = entry.session ?? "default";
+        const list = bySession.get(name);
+        if (list)
+            list.push(entry);
+        else
+            bySession.set(name, [entry]);
+    }
+    const sessions = [];
+    let first = Number.POSITIVE_INFINITY;
+    let last = 0;
+    for (const [session, entries] of bySession) {
+        const times = entries.map((e) => Date.parse(e.at)).filter((t) => Number.isFinite(t));
+        if (times.length === 0)
+            continue;
+        times.sort((a, b) => a - b);
+        first = Math.min(first, times[0]);
+        last = Math.max(last, times[times.length - 1]);
+        const gaps = [];
+        for (let i = 1; i < times.length; i += 1)
+            gaps.push(times[i] - times[i - 1]);
+        const spanMs = times[times.length - 1] - times[0];
+        const idleMs = gaps.filter((g) => g > IDLE_GAP_MS).reduce((sum, g) => sum + g, 0);
+        sessions.push({
+            session,
+            actions: entries.length,
+            spanMs,
+            medianGapMs: median([...gaps].sort((a, b) => a - b)),
+            maxGapMs: gaps.length > 0 ? Math.max(...gaps) : 0,
+            idleShare: spanMs > 0 ? idleMs / spanMs : 0,
+            quietMs: Math.max(0, nowMs - times[times.length - 1]),
+            framed: entries.filter((e) => e.frame).length,
+        });
+    }
+    sessions.sort((a, b) => b.actions - a.actions);
+    return {
+        sessions,
+        spanMs: sessions.length > 0 ? last - first : 0,
+        actions: sessions.reduce((sum, x) => sum + x.actions, 0),
+        // Only a session that is STILL ATTACHED can be holding a browser. A lane
+        // that finished and closed is quiet because it is gone, and warning about
+        // it told the reader to close something that no longer exists — which is
+        // what the first run of this report did for six of its eleven sessions.
+        quiet: sessions.filter((s) => s.quietMs > STALE_SESSION_MS && stillOpen.has(s.session)).map((s) => s.session),
+    };
+}
+/** Milliseconds as a person says them: 45s, 4m12s, 1h03m. */
+export function sayDuration(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    if (total < 60)
+        return `${total}s`;
+    const minutes = Math.floor(total / 60);
+    if (minutes < 60)
+        return `${minutes}m${String(total % 60).padStart(2, "0")}s`;
+    return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`;
+}
+/**
+ * The run's pace as report lines. Says what the numbers mean, because "idle
+ * 84%" reads as a fault in the engine when it is a description of how the
+ * agent paced itself.
+ */
+export function formatPace(pace) {
+    if (pace.sessions.length === 0)
+        return [];
+    const lines = [
+        `## How the run was paced`,
+        ``,
+        `${pace.actions} action(s) over ${sayDuration(pace.spanMs)}. Stated tasks and attaches are not counted: they take no time. Idle share is time the browser stood still waiting for the agent, not time the engine spent working.`,
+        ``,
+        `| Session | Actions | Span | Median gap | Longest gap | Idle | Frames |`,
+        `|---|---:|---:|---:|---:|---:|---:|`,
+    ];
+    for (const s of pace.sessions) {
+        lines.push(`| ${s.session} | ${s.actions} | ${sayDuration(s.spanMs)} | ${sayDuration(s.medianGapMs)} | ${sayDuration(s.maxGapMs)} | ${Math.round(s.idleShare * 100)}% | ${s.framed} |`);
+    }
+    lines.push(``);
+    if (pace.quiet.length > 0) {
+        lines.push(`⚠ Held a browser with nothing to do for over ${sayDuration(STALE_SESSION_MS)}: ${pace.quiet.join(", ")}. A session waiting for its turn should be closed and re-attached when it is needed.`, ``);
+    }
+    return lines;
+}

package/dist/engine/report.js

@@ -1,8 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { SHARED_CHROME_ROUTE } from "./memory.js";
+import { sayVerification } from "./verify.js";
 import { feedForSession } from "./live.js";
 import { buildReplayHtml, evidenceFor } from "./replay.js";
+import { formatPace, measurePace } from "./pace.js";
 function playwrightSkeleton(f) {
     const routeClass = f.state.split("#")[0].split("?")[0];
     let gotoPath = routeClass;
@@ -68,6 +70,24 @@ function projectName(dir) {
     const parent = path.dirname(dir);
     return path.basename(parent) || path.basename(dir) || "project";
 }
+/**
+ * How long ago a finding was last seen, for the historical index. A finding
+ * nobody has re-confirmed in four months is a different thing from one seen
+ * last week, and the report should not make a reader open both to find out.
+ */
+export function describeAge(foundAt, nowMs) {
+    const seen = Date.parse(foundAt);
+    if (!Number.isFinite(seen))
+        return "?";
+    const days = Math.floor((nowMs - seen) / 86_400_000);
+    if (days <= 0)
+        return "today";
+    if (days === 1)
+        return "1 day";
+    if (days < 60)
+        return `${days} days`;
+    return `${Math.floor(days / 30)} months`;
+}
 /** Every session that did anything, with its steps in order — what the HTML replays. */
 function replaySessions(memory) {
     const names = [...new Set(memory.actionLog.map((e) => e.session ?? "default"))];
@@ -378,6 +398,7 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
     const lines = [];
     const resolved = findings.filter((f) => f.status === "resolved");
     const open = findings.filter((f) => f.status !== "resolved");
+    const now = Date.now();
     const current = open.filter((f) => f.foundAt >= memory.sessionStart);
     const historical = open.filter((f) => f.foundAt < memory.sessionStart);
     lines.push(`# SceneScout Report`);
@@ -496,6 +517,11 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
             lines.push(`- **Evidence:** \`${f.evidence}\``);
         lines.push(`- **Where:** \`${f.state}\` (${f.url})`);
         lines.push(`- **Seen in runs:** ${f.runs}`);
+        // Only printed once somebody has re-tested it. A finding nobody has looked
+        // at again says nothing here, which is the honest thing for it to say.
+        if (f.verdict && f.verifiedAt) {
+            lines.push(`- **Re-tested:**${sayVerification(f).replace(/^ · /, " ")}${f.verifyNote ? ` — ${f.verifyNote}` : ""}`);
+        }
         lines.push(``);
         lines.push(f.detail);
         lines.push(``);
@@ -521,18 +547,47 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
     if (historical.length > 0) {
         lines.push(`## Historical findings — not re-verified this session (${historical.length})`);
         lines.push(``);
-        lines.push(`Recorded in earlier runs and not re-confirmed. Re-test before acting; resolve fixed ones with \`scout_resolve <id>\`.`);
-        lines.push(``);
-        for (const f of historical)
-            renderFinding(f);
+        if (extras?.history === "full") {
+            lines.push(`Recorded in earlier runs and not re-confirmed. Re-test before acting; \`scout_verify\` hands them back in re-test order and records what each re-test found.`);
+            lines.push(``);
+            for (const f of historical)
+                renderFinding(f);
+        }
+        else {
+            // An index, not the findings themselves. One project reached 412
+            // historical findings and printing each in full made the report 1.75 MB
+            // — a document nobody opens, in which the eleven findings the run
+            // actually made were buried. Each row carries what decides whether to
+            // re-test it; the detail is one scout_report {history:"full"} away.
+            lines.push(`Recorded in earlier runs and NOT re-confirmed by this one, so none of it is evidence about the build under test. Listed as an index: ` +
+                `work it down with \`scout_verify\`, which hands back these findings in re-test order and records what each re-test found, ` +
+                `and pass \`history: "full"\` to scout_report for the full text.`, ``, `| Sev | Id | Age | Runs | Re-tested | Title |`, `|---|---|---:|---:|---|---|`);
+            for (const f of historical) {
+                const retested = f.verdict && f.verifiedAt ? `${f.verdict} ${f.verifiedAt.slice(0, 10)}` : "never";
+                lines.push(`| ${SEVERITY_ICON[f.severity]} | \`${f.id}\` | ${describeAge(f.foundAt, now)} | ${f.runs} | ${retested} | ${escapeTableCell(f.title)} |`);
+            }
+            lines.push(``);
+        }
     }
     if (resolved.length > 0) {
         lines.push(`## ✅ Resolved (${resolved.length})`);
         lines.push(``);
         lines.push(`Fixed and verified (or confirmed no longer reproducing). A resolved finding that is re-found reopens automatically and is flagged as a regression above.`);
         lines.push(``);
-        for (const f of resolved)
-            renderFinding(f, true);
+        if (extras?.history === "full") {
+            for (const f of resolved)
+                renderFinding(f, true);
+        }
+        else {
+            // The least actionable content in the document: these are fixed. On one
+            // project they were 314 findings and 783 KB — nearly half the report,
+            // none of it anything to do. The index keeps the record without the bulk.
+            lines.push(`| Sev | Id | Fixed | Title |`, `|---|---|---:|---|`);
+            for (const f of resolved) {
+                lines.push(`| ${SEVERITY_ICON[f.severity]} | \`${f.id}\` | ${describeAge(f.foundAt, now)} ago | ${escapeTableCell(f.title)} |`);
+            }
+            lines.push(``);
+        }
     }
     if (extras?.createdResources && extras.createdResources.length > 0) {
         lines.push(`## Data created by this session (cleanup list)`);
@@ -552,6 +607,15 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
         }
         lines.push(``);
     }
+    // How the run was paced. A reader who sees a session that did four actions
+    // in an hour learns more from that than from another coverage percentage.
+    // Omitted where the report is compared byte for byte, since it is timing.
+    // The sessions still attached, so the stale-browser warning names only the
+    // ones that could act on it. A lane that finished and closed is quiet
+    // because it is gone.
+    if (extras?.pace !== false) {
+        lines.push(...formatPace(measurePace(memory.actionLog, Date.now(), extras?.attachedSessions ?? [])));
+    }
     const markdown = lines.join("\n");
     const outPath = path.join(memory.dir, "report.md");
     const htmlPath = path.join(memory.dir, "report.html");