scenescout 3.1.1 → 3.3.0

package/dist/engine/lane.js

@@ -0,0 +1,169 @@
+/**
+ * The lane report: what an agent exploring one area in parallel hands back to
+ * the agent that split the work, as typed decisions rather than prose.
+ *
+ * A parallel run has one planning agent and several lanes, each driving its
+ * own browser. A lane used to come back with a page of markdown, which the
+ * planner then had to read, re-judge and re-type into findings: a model pass
+ * over every lane's output, with nothing stopping a lane from inventing a
+ * category or writing "Low-Medium" as a severity.
+ *
+ * This module is the alternative, borrowed from decision-only models: every
+ * answer is a value from a closed set, carries a calibrated confidence, and
+ * is checked by a schema on arrival. The planner folds a report with a
+ * function call, not a reading.
+ *
+ * Both halves are reached through the scout_lane_report tool: with no reply
+ * it returns the instruction the planner puts in a lane's prompt, with one it
+ * parses it. The instruction is generated from the same constants the parser
+ * checks, and a table test asserts every value and every cap the parser
+ * enforces is in the text, because a limit the lane is not told refuses good
+ * replies: three of the first ten real replies were lost that way.
+ *
+ * Pure logic, no browser, so every rule here is table-tested.
+ */
+import { z } from "zod";
+import { FINDING_CATEGORIES } from "./memory.js";
+/** Upper bound on the decisions and routes arrays, so a report is always small enough to hold whole. */
+export const LANE_MAX_ITEMS = 255;
+/** A signature such as "GET /api/things 500", not a sentence. */
+export const LANE_EVIDENCE_MAX = 160;
+/** A lane names its own observations, and a name that says what was seen needs more than forty characters. */
+export const LANE_OBSERVATION_MAX = 64;
+/** One line saying what blocked the lane; the detail belongs in a finding. */
+export const LANE_BLOCKED_BY_MAX = 200;
+/** The planner chooses the lane name, so this cap is on the planner's side; it is stated all the same. */
+export const LANE_NAME_MAX = 40;
+/** A route as the lane saw it, query string included. */
+export const LANE_ROUTE_MAX = 200;
+export const LANE_SEVERITIES = ["high", "medium", "low"];
+/** The same set scout_finding accepts, so a lane can report every finding it filed. */
+export const LANE_CATEGORIES = FINDING_CATEGORIES;
+export const LANE_VERDICTS = ["defect", "not_a_defect", "unsure"];
+export const LANE_STATUSES = ["complete", "partial", "blocked"];
+const Confidence = z.number().min(0).max(1);
+/**
+ * One observation judged: is it a defect, how bad, of what kind, and how sure
+ * the lane is. A non-defect may still carry a category and a signature: an
+ * "unsure" with a tentative category tells the planner where to look.
+ */
+export const LaneDecision = z
+    .object({
+    /** A short id the lane assigns, unique within the report, so a decision can be traced back to what the lane saw. */
+    observation: z.string().min(1).max(LANE_OBSERVATION_MAX),
+    verdict: z.enum(LANE_VERDICTS),
+    severity: z.enum(LANE_SEVERITIES).nullable(),
+    category: z.enum(LANE_CATEGORIES).nullable(),
+    confidence: Confidence,
+    /** The same machine signature scout_finding takes as its cross-run dedup key. */
+    evidence: z.string().min(1).max(LANE_EVIDENCE_MAX).nullable(),
+})
+    .strict()
+    .superRefine((d, ctx) => {
+    if (d.verdict === "defect" && (d.severity === null || d.category === null)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a defect needs a severity and a category" });
+    }
+});
+export const LaneReport = z
+    .object({
+    lane: z.string().min(1).max(LANE_NAME_MAX),
+    status: z.enum(LANE_STATUSES),
+    decisions: z.array(LaneDecision).max(LANE_MAX_ITEMS),
+    /** The routes the lane covered, as it saw them; the planner normalises when it compares them with the split. */
+    routes: z.array(z.string().min(1).max(LANE_ROUTE_MAX)).max(LANE_MAX_ITEMS),
+    /** Required when the status is "blocked"; a "partial" lane may use it to say what cut it short; a "complete" one has nothing to put there. */
+    blocked_by: z.string().min(1).max(LANE_BLOCKED_BY_MAX).nullable(),
+})
+    .strict()
+    .superRefine((r, ctx) => {
+    if (r.status === "blocked" && r.blocked_by === null) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a blocked lane must say what blocked it", path: ["blocked_by"] });
+    }
+    if (r.status === "complete" && r.blocked_by !== null) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a complete lane cannot also have been blocked", path: ["blocked_by"] });
+    }
+    const seen = new Set();
+    r.decisions.forEach((d, i) => {
+        if (seen.has(d.observation)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `observation "${d.observation}" is judged twice`, path: ["decisions", i, "observation"] });
+        }
+        seen.add(d.observation);
+    });
+});
+const FENCE_OPEN = /^```[a-z]*\s*\n/i;
+const FENCE_CLOSE = /\n?```\s*$/;
+/**
+ * The reply is one JSON object and nothing else. A fenced block around it is
+ * tolerated, because every model has been trained to add one; text before or
+ * after it is not, because the point is that no one has to read the reply.
+ * The reason names what was wrong, since the planner relays it to the lane.
+ *
+ * With `expectedLane`, a report that names another lane is refused: the
+ * planner joins reports to the split by name, and a reply that carries the
+ * wrong one would be folded into the wrong lane.
+ */
+export function parseLaneReport(text, expectedLane) {
+    let body = text.trim();
+    if (FENCE_OPEN.test(body)) {
+        if (!FENCE_CLOSE.test(body))
+            return { ok: false, reason: "the closing ``` must end the reply, with no text after it" };
+        body = body.replace(FENCE_OPEN, "").replace(FENCE_CLOSE, "").trim();
+    }
+    if (!body.startsWith("{"))
+        return { ok: false, reason: "the reply must be one JSON object, with no text before it" };
+    let raw;
+    try {
+        raw = JSON.parse(body);
+    }
+    catch (e) {
+        const message = e.message;
+        const trailing = /after JSON|Unexpected non-whitespace/i.test(message);
+        return { ok: false, reason: trailing ? "the reply must be one JSON object, with no text after it" : `not valid JSON: ${message}` };
+    }
+    const result = LaneReport.safeParse(raw);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const at = issue.path.length ? ` at ${issue.path.join(".")}` : "";
+        return { ok: false, reason: `${issue.message}${at}` };
+    }
+    if (expectedLane !== undefined && result.data.lane !== expectedLane) {
+        return { ok: false, reason: `the report names lane "${result.data.lane}", but this reply was asked of lane "${expectedLane}"` };
+    }
+    return { ok: true, report: result.data };
+}
+/**
+ * The paragraph the planner puts in every lane's prompt. It is generated from
+ * the same constants the parser checks, so it can never list a value the
+ * parser would refuse, and it states every cap the parser enforces.
+ */
+export function laneReportInstruction(lane) {
+    return [
+        "Reply with ONE JSON object and nothing else — no prose before or after it, no explanation, no headings. A fenced ```json block is fine.",
+        `Shape: {"lane":${JSON.stringify(lane)},"status":<${quoteAll(LANE_STATUSES)}>,"decisions":[…],"routes":[…],"blocked_by":<string or null>}.`,
+        `Each decision: {"observation":<a short id for what was observed, unique in the report, at most ${LANE_OBSERVATION_MAX} characters>,"verdict":<${quoteAll(LANE_VERDICTS)}>,"severity":<${quoteAll(LANE_SEVERITIES)} or null>,"category":<${quoteAll(LANE_CATEGORIES)} or null>,"confidence":<0..1>,"evidence":<machine signature such as "GET /api/things 500", or null>}.`,
+        `A "defect" must carry a severity and a category. "evidence" is a signature, not a sentence: at most ${LANE_EVIDENCE_MAX} characters. "confidence" is how sure you are of the verdict, calibrated: 0.5 means a coin flip, 0.95 means you would bet on it.`,
+        `"routes" lists the routes you covered, each at most ${LANE_ROUTE_MAX} characters. "blocked_by" is one line of at most ${LANE_BLOCKED_BY_MAX} characters saying what stopped you: required when the status is "blocked", allowed with "partial", null with "complete"; the detail belongs in a finding. The lane name is at most ${LANE_NAME_MAX} characters. At most ${LANE_MAX_ITEMS} decisions and ${LANE_MAX_ITEMS} routes. Unknown keys are refused.`,
+        "The object IS your final report: whatever hands it back must hand back the object verbatim, not a summary of it.",
+    ].join(" ");
+}
+function quoteAll(values) {
+    return values.map((v) => `"${v}"`).join("|");
+}
+/** The planner's fold: one line per lane, with the numbers it decides on. */
+export function summarizeLaneReport(r) {
+    const defects = r.decisions.filter((d) => d.verdict === "defect");
+    const high = defects.filter((d) => d.severity === "high").length;
+    const unsure = r.decisions.filter((d) => d.verdict === "unsure").length;
+    const mean = r.decisions.length ? r.decisions.reduce((s, d) => s + d.confidence, 0) / r.decisions.length : 0;
+    const parts = [
+        r.status,
+        `${r.decisions.length} judged`,
+        `${defects.length} defects (${high} high)`,
+        `${unsure} unsure`,
+        `mean confidence ${mean.toFixed(2)}`,
+        `${r.routes.length} routes`,
+    ];
+    if (r.blocked_by)
+        parts.push(`blocked by ${r.blocked_by}`);
+    return `${r.lane}: ${parts.join(", ")}`;
+}

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

@@ -1,6 +1,71 @@
 import fs from "node:fs";
 import path from "node:path";
 import { normalizePath, shortHash } from "./fingerprint.js";
+/**
+ * The kinds a finding can be. One list: scout_finding's input schema, the lane
+ * report a parallel agent hands back, and the skill text all read it from
+ * here, so a category cannot exist in one and be refused by another.
+ */
+export const FINDING_CATEGORIES = [
+    "console-error",
+    "page-error",
+    "http-error",
+    "network",
+    "dead-end",
+    "ux-confusing",
+    "ux-polish",
+    "visual",
+    "a11y",
+    "permission-leak",
+    "data-inconsistency",
+    "stale-state",
+    "data-loss",
+    "performance",
+    "security",
+    "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"). */
@@ -660,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)";
@@ -701,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) {
@@ -759,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;
     /**
@@ -883,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;