scenescout 3.11.0 → 3.12.0

package/dist/engine/memory.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { normalizePath, shortHash } from "./fingerprint.js";
+import { laneRoutePaths, normalizePath, shortHash, stripRouteQuery } from "./fingerprint.js";
 import { isFormBookkeeping } from "./forms.js";
 /**
  * The kinds a finding can be. One list: scout_finding's input schema, the lane
@@ -26,6 +26,32 @@ export const FINDING_CATEGORIES = [
     "missing-testid",
     "other",
 ];
+/**
+ * Whether a finding is in the "worth a look" tier. Anything else a file holds
+ * reads as a defect: a finding is never taken out of the defect count on a
+ * value this version does not know.
+ */
+export function isWorthALook(f) {
+    return f.tier === "worth_a_look";
+}
+/**
+ * The tier a finding keeps when it is found again. A defect wins: a finding
+ * someone filed as a defect is a decision about the project's convention, and
+ * a later "worth a look" for the same thing does not undo it. A worth-a-look
+ * filed again as a defect is promoted, and loses its convention. Two
+ * worth-a-looks keep the first convention unless it had none.
+ */
+/** Drops a finding's tier and convention in place, so a merged tier can be assigned onto it. */
+function withoutTier(f) {
+    delete f.tier;
+    delete f.convention;
+    return f;
+}
+export function mergeTier(existing, incoming) {
+    if (!isWorthALook(existing) || !isWorthALook(incoming))
+        return {};
+    return { tier: "worth_a_look", convention: existing.convention || incoming.convention };
+}
 /**
  * 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;
@@ -213,12 +239,19 @@ export function mergeMemory(mine, theirs) {
         // the other side did not go on to re-find it as a regression.
         const newer = f.foundAt >= other.foundAt ? f : other;
         const older = newer === f ? other : f;
-        byId.set(f.id, {
+        const merged = {
             ...newer,
             runs: Math.max(f.runs, other.runs),
             evidence: newer.evidence ?? older.evidence,
             regressedAt: newer.regressedAt ?? older.regressedAt,
-        });
+        };
+        // The tier is not "later knowledge wins": a defect on either side is a decision
+        // about the convention, and a store still holding the worth-a-look must not undo it.
+        const tier = mergeTier(older, newer);
+        Object.assign(withoutTier(merged), tier);
+        if (!isWorthALook(merged) && isWorthALook(newer))
+            merged.severity = older.severity;
+        byId.set(f.id, merged);
     }
     out.findings = [...byId.values()];
     const unionRecord = (a, b) => (a || b ? { ...(b ?? {}), ...(a ?? {}) } : undefined);
@@ -264,8 +297,34 @@ export function mergeMemory(mine, theirs) {
     out.laneDecisions = [...byDecision.values()].sort((a, b) => a.at.localeCompare(b.at)).slice(-MAX_LANE_DECISIONS);
     if (out.laneDecisions.length === 0)
         delete out.laneDecisions;
+    // The same reason as decisions: each lane folds in its own process. A set
+    // union per lane, so merging the same document twice changes nothing.
+    out.laneRoutes = { ...(theirs.laneRoutes ?? {}) };
+    for (const [lane, routes] of Object.entries(mine.laneRoutes ?? {})) {
+        out.laneRoutes[lane] = unionRoutes(out.laneRoutes[lane] ?? [], routes);
+    }
+    if (Object.keys(out.laneRoutes).length === 0)
+        delete out.laneRoutes;
     return out;
 }
+/** Most routes kept per lane. A lane report carries at most a few hundred; this keeps a long-lived project's file small. */
+export const MAX_LANE_ROUTES = 255;
+/**
+ * `b` added to `a`. Two routes naming the same page(s) are one — the later
+ * wording wins — and past the cap the NEWEST are kept: a long-lived project
+ * reuses lane names, and what a lane covers now is what a new verdict is
+ * judged against.
+ */
+function unionRoutes(a, b) {
+    const byPage = new Map();
+    for (const r of [...a, ...b]) {
+        const paths = laneRoutePaths(r);
+        const id = paths.length ? paths.sort().join(" ") : `text:${r}`;
+        byPage.delete(id);
+        byPage.set(id, r);
+    }
+    return [...byPage.values()].slice(-MAX_LANE_ROUTES);
+}
 /**
  * What makes two stored decisions the same judgement.
  *
@@ -451,6 +510,14 @@ export function requestsDisagree(a, b) {
  * refused save is data-loss to one and data-inconsistency to another. Across
  * families — a layout defect and a data defect — a shared quoted string names
  * a place on the page, not a bug.
+ *
+ * The presentation kinds are each a family of their own. They are not
+ * alternative labels for one observation: one element is routinely wrong in
+ * several independent ways at once — clipped out of view (visual), styled like
+ * body text (ux-polish), unnamed to a screen reader (a11y), missing its test id
+ * — and the findings about it quote the same control name and name the same
+ * test id. As one family, a link "styled like body text" was merged into the
+ * finding that the same link was clipped, and the second finding was lost.
  */
 const CATEGORY_FAMILY = {
     "data-inconsistency": "data",
@@ -460,10 +527,10 @@ const CATEGORY_FAMILY = {
     network: "failure",
     "console-error": "failure",
     "page-error": "failure",
-    visual: "presentation",
-    "ux-polish": "presentation",
-    a11y: "presentation",
-    "missing-testid": "presentation",
+    visual: "visual",
+    "ux-polish": "ux-polish",
+    a11y: "a11y",
+    "missing-testid": "missing-testid",
     "ux-confusing": "flow",
     "dead-end": "flow",
     security: "security",
@@ -485,7 +552,30 @@ export function sameFamily(a, b) {
     const fa = CATEGORY_FAMILY[a];
     return fa !== undefined && fa === CATEGORY_FAMILY[b];
 }
+/**
+ * Whether two findings may be one defect by KIND — what is wrong, as opposed
+ * to where. The same category, or two categories of one family. Every
+ * route-scoped rule below asks this first: evidence, a quoted literal and a
+ * title all say where a defect is as often as what it is, so none of them may
+ * merge a finding of one kind into a finding of another.
+ */
+function sameKind(a, b) {
+    return (!!a && a === b) || sameFamily(a, b);
+}
+/**
+ * The categories a finding of `category` can merge with, in list order —
+ * so scout_finding can tell a lane whose filing was merged which kinds would
+ * have been kept apart. An unknown category merges only with itself.
+ */
+export function mergeableCategories(category) {
+    const known = FINDING_CATEGORIES.filter((c) => sameKind(category, c));
+    return known.length > 0 ? known : [category];
+}
 function sameFinding(a, b) {
+    // What is wrong before where: two kinds of defect are two findings, however
+    // alike their evidence, quoted text or titles.
+    if (!sameKind(a.category, b.category))
+        return false;
     const aEv = a.evidence?.toLowerCase().replace(/\s+/g, " ").trim();
     const bEv = b.evidence?.toLowerCase().replace(/\s+/g, " ").trim();
     if (aEv && bEv && aEv === bEv)
@@ -506,7 +596,9 @@ function sameFinding(a, b) {
     // literal with the data defect describing what the button does — in its
     // detail or its own title. Merged, the layout defect was filed and then lost
     // from the report on most runs of a benchmark. Within a family, one bug
-    // filed twice under neighbouring categories still merges.
+    // filed twice under neighbouring categories still merges. Stricter than the
+    // kind check above in one way: an unknown category read from an older file
+    // is never merged on a quoted string, even with itself.
     //
     // And never when both findings' evidence names requests with no endpoint in
     // common. A quoted control name bridges two findings about that control
@@ -847,6 +939,11 @@ export class MemoryStore {
                     dupOf.evidence = f.evidence;
                 if (f.status === "resolved")
                     dupOf.status = "resolved";
+                const promoted = isWorthALook(dupOf) && !isWorthALook(f);
+                const tier = mergeTier(dupOf, f);
+                Object.assign(withoutTier(dupOf), tier);
+                if (promoted)
+                    dupOf.severity = f.severity;
                 merged += 1;
             }
             else {
@@ -1087,6 +1184,27 @@ export class MemoryStore {
         // every call after the first reported nothing kept — while storing fine.
         return Math.min(added, MAX_LANE_DECISIONS);
     }
+    /** The routes each lane's report said it covered. Empty on a project that has never run one. */
+    get laneRoutes() {
+        return this.data.laneRoutes ?? {};
+    }
+    /**
+     * Record the routes a lane's accepted report listed, added to any it listed
+     * before. Redacted like every other string a lane writes, with query
+     * strings and fragments removed. Returns how many were new.
+     */
+    addLaneRoutes(lane, routes) {
+        const before = this.data.laneRoutes?.[lane] ?? [];
+        // No query string or fragment is stored: a route is copied from the
+        // address bar, and an address can carry a token.
+        const after = unionRoutes(before, routes.map((r) => redactSecrets(stripRouteQuery(r))).filter((r) => r.length > 0));
+        const added = after.filter((r) => !before.includes(r)).length;
+        if (after.length === before.length && after.every((r, i) => r === before[i]))
+            return 0;
+        this.data.laneRoutes = { ...(this.data.laneRoutes ?? {}), [lane]: after };
+        this.flush();
+        return added;
+    }
     /** Mark a finding resolved; returns it or null. */
     resolveFinding(id) {
         const f = this.data.findings.find((x) => x.id === id);
@@ -1356,6 +1474,7 @@ export class MemoryStore {
      *    across sessions rarely reuses the exact words — Jaccard catches it).
      * Returns [finding, isNew].
      */
+    /** Returns the finding, whether it is new, and whether an existing worth-a-look was just promoted to a defect by it. */
     addFinding(input) {
         // Redact BEFORE the id is derived, so a re-found finding whose quoted
         // secret differs by a character still hashes to the same id.
@@ -1376,6 +1495,12 @@ export class MemoryStore {
             existing.foundAt = new Date().toISOString();
             if (!existing.evidence && f.evidence)
                 existing.evidence = f.evidence;
+            // A worth-a-look filed again as a defect is promoted, at the severity the defect was filed at.
+            const promoted = isWorthALook(existing) && !isWorthALook(f);
+            const tier = mergeTier(existing, f);
+            Object.assign(withoutTier(existing), tier);
+            if (promoted)
+                existing.severity = f.severity;
             // Re-finding a RESOLVED finding is a regression — reopen it loudly
             // rather than letting it hide in the report's completed section. But a
             // FUZZY match must never resurrect a fixed bug: telling someone a
@@ -1392,7 +1517,7 @@ export class MemoryStore {
                 existing.regressedAt = existing.foundAt;
             }
             this.flush();
-            return [existing, false];
+            return [existing, false, promoted];
         }
         // Repro trace scoped to the finding's route: everything since the action
         // that landed there, not 12 lines of unrelated cross-module noise.
@@ -1429,7 +1554,7 @@ export class MemoryStore {
         };
         this.data.findings.push(finding);
         this.flush();
-        return [finding, true];
+        return [finding, true, false];
     }
     get findings() {
         return this.data.findings;

package/dist/engine/report.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { SHARED_CHROME_ROUTE, isEmbedKey } from "./memory.js";
+import { SHARED_CHROME_ROUTE, isEmbedKey, isWorthALook } from "./memory.js";
 import { sayVerification } from "./verify.js";
 import { feedForSession } from "./live.js";
 import { buildReplayHtml, evidenceFor } from "./replay.js";
@@ -103,6 +103,34 @@ function projectName(dir) {
     const parent = path.dirname(dir);
     return path.basename(parent) || path.basename(dir) || "project";
 }
+/**
+ * The "Worth a look" section: observations that are real and are defects only
+ * under a convention of the project the run cannot see. Each says what was
+ * seen and what would confirm it. Listed below the findings and never in their
+ * totals, because SceneScout does not decide a project's conventions; nothing
+ * when there are none. The first bullet names the id, as a finding's does, so
+ * the live view hangs the frames recorded around it under the entry.
+ */
+export function formatWorthALook(items, sessionStart) {
+    if (items.length === 0)
+        return [];
+    const lines = [
+        `## Worth a look (${items.length})`,
+        ``,
+        `Real observations that are defects only under a convention of your project that the run cannot see. They are not counted as findings above; each says what would make it one.`,
+        ``,
+    ];
+    for (const f of items) {
+        lines.push(`### ${f.title}`, ``);
+        lines.push(`- **Id:** \`${f.id}\` · **Category:** ${f.category}${f.foundAt >= sessionStart ? "" : " · seen in an earlier run"}`);
+        lines.push(`- **A defect only if** your project uses ${f.convention ?? "a convention the finding does not name"}`);
+        if (f.evidence)
+            lines.push(`- **Seen:** \`${f.evidence}\``);
+        lines.push(`- **Where:** \`${f.state}\` (${f.url})`);
+        lines.push(``, f.detail, ``);
+    }
+    return lines;
+}
 /**
  * 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
@@ -447,7 +475,10 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
     const findings = [...memory.findings].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
     const lines = [];
     const resolved = findings.filter((f) => f.status === "resolved");
-    const open = findings.filter((f) => f.status !== "resolved");
+    // Worth a look is listed below the findings and counted nowhere a defect is:
+    // "open", "current" and "historical" hold defects only.
+    const worthALook = findings.filter((f) => f.status !== "resolved" && isWorthALook(f));
+    const open = findings.filter((f) => f.status !== "resolved" && !isWorthALook(f));
     const now = Date.now();
     const current = open.filter((f) => f.foundAt >= memory.sessionStart);
     const historical = open.filter((f) => f.foundAt < memory.sessionStart);
@@ -460,6 +491,8 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
     lines.push(`| Metric | Value |`);
     lines.push(`|---|---|`);
     lines.push(`| Open findings | ${open.length} (${open.filter((f) => f.severity === "high").length} high) — ${current.length} seen this session, ${historical.length} historical${resolved.length ? `, ${resolved.length} resolved (listed at the bottom)` : ""} |`);
+    if (worthALook.length > 0)
+        lines.push(`| Worth a look (not counted as defects) | ${worthALook.length} |`);
     if (extras && extras.routesTotal > 0)
         lines.push(`| Route coverage | ${extras.routesVisited}/${extras.routesTotal} |`);
     lines.push(`| States explored | ${cov.states} |`);
@@ -620,6 +653,7 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
             lines.push(``);
         }
     }
+    lines.push(...formatWorthALook(worthALook, memory.sessionStart));
     if (resolved.length > 0) {
         lines.push(`## ✅ Resolved (${resolved.length})`);
         lines.push(``);
@@ -750,6 +784,7 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
         `Top open findings:`,
         ...open.slice(0, 10).map((f) => `  ${SEVERITY_ICON[f.severity]} [${f.severity}] ${f.title} (${f.id})`),
         ...(open.length > 10 ? [`  … +${open.length - 10} more in the report`] : []),
+        ...(worthALook.length > 0 ? [`Worth a look (defects only under a project convention; not counted above): ${worthALook.length}`] : []),
         ``,
         `Gap ledger${gaps.length === 0 ? ": EMPTY — nothing known left untested" : ` (${gaps.length}):`}`,
         ...gaps.map((g) => `  ⚠ ${g}`),

package/dist/engine/unload.js

@@ -0,0 +1,201 @@
+/**
+ * Writes the context's route handler never sees, and how the engine judges
+ * them anyway.
+ *
+ * In Chromium, a request a page sends while it is being left (a
+ * `navigator.sendBeacon` or a `fetch(..., { keepalive: true })` on
+ * `pagehide`, `visibilitychange` or `unload`, or one still leaving as a page
+ * is closed) is never handed to the context's route handler: it arrives with
+ * no network id, or after the page's own DevTools session has gone, and the
+ * driver lets it through unseen. Left alone it reached the server in every
+ * mode, observe included. The engine therefore also intercepts at the
+ * browser level (the DevTools Fetch domain on the browser target, which does
+ * pause these requests) and judges there every write the route handler did
+ * not already judge, by the same rules (ADR 2). Which engines need this is
+ * `unloadWriteInterception` in `browsers.ts`.
+ *
+ * Everything here is pure, so the rules are table-tested in policy-test; the
+ * wiring to the browser lives in `browser.ts`.
+ */
+import { createHash } from "node:crypto";
+import { allowsForeignWriteOnSignIn, allowsWrite, foreignWrite, isAuthExempt, offAppPageWrite, trustsForeignWrite } from "./policy.js";
+/** Whether a method sends nothing the write policy judges. */
+export function isReadMethod(method) {
+    return method === "GET" || method === "HEAD" || method === "OPTIONS";
+}
+/**
+ * Who sent a write the route handler never saw, as far as its headers tell:
+ * the embed it is charged to (`foreign`) and the off-app page it came from
+ * (`offApp`), the two inputs `judgeUnseenWrite` takes from the sender.
+ *
+ * The sending frame may be gone, so its URL is not known. The page it was
+ * sent from is its Referer; where there is none, the page the session drives
+ * stands in for `offApp` only.
+ *
+ * - `foreign`: policy.ts `foreignWrite` with no frame chain, so a write out of
+ *   the app whose Origin header names another site is that site's embed's. A
+ *   sign-in provider's page reached as the whole page, beaconing to itself as
+ *   it is left, is therefore refused outside destructive; the route handler,
+ *   which knows the frame, would let it through. The cautious direction. An
+ *   `Origin: null` write out of the app is taken to be an embed's too, whether
+ *   or not the page embeds anything, since the page can no longer be asked.
+ * - The sign-in exception (a captcha on the app's own sign-in page) is judged
+ *   against the Referer, the page the request was sent from, never against
+ *   whatever page the session has moved to by the time the request is seen.
+ *   With no Referer it does not apply.
+ * - Trusted embeds (safe-write only) are judged by the Origin header alone.
+ */
+export function unseenWriteSource(input) {
+    const { appUrl, mode, url, originHeader, referer } = input;
+    let foreign = foreignWrite(appUrl, { url, frameChain: [], frameUrl: null, originHeader, pageHasForeignFrame: true });
+    if (foreign && referer && allowsForeignWriteOnSignIn(mode, referer, appUrl))
+        foreign = null;
+    if (foreign && trustsForeignWrite(mode, input.trustedEmbeds, appUrl, { frameChain: [], originHeader, unadoptedPageUrl: null }))
+        foreign = null;
+    const offApp = offAppPageWrite(appUrl, referer ?? input.currentPageUrl, url, input.movedByEmbed);
+    return { foreign, offApp };
+}
+/**
+ * The route handler's verdict on a write, from what a browser-level
+ * interception can know about it. Same rules in the same order: a write
+ * another site's frame sends outside the app is refused; so is one sent from
+ * a page an embed moved off the app, a sign-in excepted; a sign-in passes;
+ * then the mode decides. `foreign` and `offApp` come from
+ * `unseenWriteSource`, since the sending frame may no longer exist.
+ * The one step it does not take is safe-write's short wait for a creation
+ * still in flight: a page being left has nothing more to wait for.
+ */
+export function judgeUnseenWrite(input) {
+    const { mode, method, pathname, destructiveWire } = input;
+    if (mode === "destructive" || isReadMethod(method))
+        return { allow: true };
+    if (input.foreign)
+        return { allow: false, why: `sent from a frame of ${input.foreign}` };
+    const authExempt = isAuthExempt(mode, method, pathname, destructiveWire);
+    if (input.offApp && !authExempt)
+        return { allow: false, why: `sent from a page of ${input.offApp}, outside the app` };
+    if (authExempt)
+        return { allow: true };
+    return allowsWrite(mode, method, destructiveWire, input.owned) ? { allow: true } : { allow: false };
+}
+/**
+ * How long a write the route handler let through stays on the ledger. The
+ * browser-level pause follows the route handler's `continue` within
+ * milliseconds; an entry that outlives this is a request that never reached
+ * the network (answered by a service worker, cancelled by the page).
+ */
+export const ROUTED_WRITE_TTL_MS = 5000;
+/** Entries past this many are dropped oldest first: a page that posts in a loop cannot grow the ledger without bound. */
+const MAX_ROUTED_WRITES = 200;
+/** A request body's identity for the ledger: the SHA-256 of its bytes, or "" for no body. */
+export function bodyDigest(body) {
+    return body && body.length > 0 ? createHash("sha256").update(body).digest("hex") : "";
+}
+/**
+ * The writes the route handler has already judged and let through, so the
+ * browser-level interception, which sees them again, lets them pass without
+ * judging them twice. The key is the mode, the method, the URL and the body's
+ * digest (`bodyDigest`), so a write let through can only excuse the very same
+ * request: never one with another body to the same URL, such as a delete
+ * command sent where a harmless save was allowed a moment before, and never
+ * one sent after a flow switched to a stricter rule. A write is claimed once:
+ * two identical requests, one routed and one not, leave the second to be
+ * judged. Requests the route handler refused never reach the browser level,
+ * so they are not recorded.
+ */
+export class RoutedWrites {
+    ttlMs;
+    entries = [];
+    constructor(ttlMs = ROUTED_WRITE_TTL_MS) {
+        this.ttlMs = ttlMs;
+    }
+    static key(mode, method, url, digest) {
+        return `${mode} ${method} ${url.split("#")[0]} ${digest}`;
+    }
+    prune(now) {
+        this.entries = this.entries.filter((e) => now - e.at <= this.ttlMs);
+        if (this.entries.length > MAX_ROUTED_WRITES)
+            this.entries = this.entries.slice(-MAX_ROUTED_WRITES);
+    }
+    note(mode, method, url, digest, now = Date.now()) {
+        this.prune(now);
+        this.entries.push({ key: RoutedWrites.key(mode, method, url, digest), at: now });
+    }
+    /** Whether the route handler let this write through a moment ago; each note is claimed at most once. */
+    claim(mode, method, url, digest, now = Date.now()) {
+        this.prune(now);
+        const key = RoutedWrites.key(mode, method, url, digest);
+        const i = this.entries.findIndex((e) => e.key === key);
+        if (i < 0)
+            return false;
+        this.entries.splice(i, 1);
+        return true;
+    }
+    clear() {
+        this.entries = [];
+    }
+}
+/** How long a write refused at the browser level stays recognisable to the driver's request events. */
+export const UNSEEN_REFUSAL_TTL_MS = 10000;
+/**
+ * Writes refused at the browser level, which the driver may still report as
+ * requests of its own: a 307 or 308 hop is a request Playwright knows, and it
+ * then sees it fail (ERR_BLOCKED_BY_CLIENT). Without this the refusal was also
+ * filed as the app's failed request and listed as a possible mutation. Keyed
+ * by method and URL (fragment dropped), since the driver's request object is
+ * not the paused one; kept briefly, and not consumed, since several listeners
+ * ask about the same request.
+ */
+export class UnseenRefusals {
+    ttlMs;
+    entries = [];
+    constructor(ttlMs = UNSEEN_REFUSAL_TTL_MS) {
+        this.ttlMs = ttlMs;
+    }
+    static key(method, url) {
+        return `${method} ${url.split("#")[0]}`;
+    }
+    prune(now) {
+        this.entries = this.entries.filter((e) => now - e.at <= this.ttlMs);
+        if (this.entries.length > MAX_ROUTED_WRITES)
+            this.entries = this.entries.slice(-MAX_ROUTED_WRITES);
+    }
+    note(method, url, now = Date.now()) {
+        this.prune(now);
+        this.entries.push({ key: UnseenRefusals.key(method, url), at: now });
+    }
+    has(method, url, now = Date.now()) {
+        this.prune(now);
+        const key = UnseenRefusals.key(method, url);
+        return this.entries.some((e) => e.key === key);
+    }
+    clear() {
+        this.entries = [];
+    }
+}
+/**
+ * The body of a request paused by the DevTools Fetch domain, as bytes: the
+ * base64 entries decoded and joined, else the plain `postData`. Undefined when
+ * the protocol sent neither (a body too large to include). Its digest then
+ * matches no routed write, so the request is judged, on its URL alone.
+ */
+export function pausedRequestBytes(request) {
+    const entries = request.postDataEntries?.filter((e) => typeof e.bytes === "string");
+    if (entries && entries.length > 0)
+        return Buffer.concat(entries.map((e) => Buffer.from(e.bytes, "base64")));
+    return request.postData === undefined ? undefined : Buffer.from(request.postData, "utf8");
+}
+/** The same body as text, for the policy's body rules. */
+export function pausedRequestBody(request) {
+    return pausedRequestBytes(request)?.toString("utf8");
+}
+/** A header's value from a DevTools header map, whose names keep the case they were sent with. */
+export function headerOf(headers, name) {
+    if (!headers)
+        return undefined;
+    const wanted = name.toLowerCase();
+    for (const [k, v] of Object.entries(headers))
+        if (k.toLowerCase() === wanted)
+            return v;
+    return undefined;
+}

package/dist/engine/verify.js

@@ -23,7 +23,7 @@
  * Pure, so the ordering and the wording can be table-tested.
  */
 import { normalizePath } from "./fingerprint.js";
-import { failingSignatures } from "./memory.js";
+import { failingSignatures, isWorthALook } from "./memory.js";
 /** What a re-test found. */
 export const VERDICTS = ["gone", "present", "changed"];
 export const VERDICT_MEANING = {
@@ -230,10 +230,11 @@ export function retestResults(candidates, pages) {
 /**
  * The findings a check re-tests: the open ones it can reproduce by loading a
  * page, in the campaign's order and within its cap, plus how many open
- * findings there are in all, so the report can say how many it left to a run.
+ * findings (defects, not worth-a-look) there are in all, so the report can say how many it left to a run.
  */
 export function checkRetestPlan(findings) {
-    const open = findings.filter((f) => (f.status ?? "open") !== "resolved");
+    // A worth-a-look is not a defect, so a check never re-tests it and it can never gate.
+    const open = findings.filter((f) => (f.status ?? "open") !== "resolved" && !isWorthALook(f));
     const eligible = open.filter((f) => loadRetest(item(f)) !== null);
     const candidates = verifyWorklist(eligible)
         .map(loadRetest)

package/dist/mcp-server.js

@@ -34,8 +34,8 @@ import { ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, McpError }
 import { z } from "zod";
 import { BrowserEngine } from "./engine/browser.js";
 import { reapOrphanBrowsers } from "./engine/reaper.js";
-import { FINDING_CATEGORIES, MemoryStore, redactSecrets } from "./engine/memory.js";
-import { decodedEntitiesNote, LANE_NAME_MAX, LaneLedger, laneCloseGuard, laneReportInstruction, parseLaneReport, summarizeLaneReport } from "./engine/lane.js";
+import { FINDING_CATEGORIES, isWorthALook, MemoryStore, mergeableCategories, redactSecrets } from "./engine/memory.js";
+import { decodedEntitiesNote, ignoredConventionsNote, LANE_CONVENTION_MAX, LANE_NAME_MAX, LaneLedger, laneCloseGuard, laneReportInstruction, parseLaneReport, summarizeLaneReport, } from "./engine/lane.js";
 import { MAX_UNFILED_NAMED, unfiledDefects } from "./engine/calibration.js";
 import { SessionQueue, withWatchdog } from "./engine/dispatch.js";
 import { FIXTURE_KINDS } from "./engine/fixtures.js";
@@ -562,6 +562,9 @@ server.registerTool("scout_lane_report", {
         const kept = owner
             ? owner.addLaneDecisions(lane, parsed.report.decisions.map((d) => ({ ...d, lane, at })))
             : 0;
+        // And the routes it covered, so the benchmark can tell a lane's remark
+        // about another lane's page from a verdict on its own.
+        owner?.addLaneRoutes(lane, parsed.report.routes);
         // Say when nothing was kept. Every lane closing its session before the
         // planner folds its report is the order the method describes, and it
         // leaves no memory to write to — reporting a bare "accepted" while the
@@ -586,7 +589,7 @@ server.registerTool("scout_lane_report", {
             : "";
         laneLedger.fold(lane, engines.get(lane)?.attached === true);
         const around = parsed.aroundIgnored ? `\n(The text around the report's JSON block was discarded unread.)` : "";
-        const decoded = decodedEntitiesNote(parsed.entitiesDecoded);
+        const decoded = decodedEntitiesNote(parsed.entitiesDecoded) + ignoredConventionsNote(parsed.conventionsIgnored);
         return {
             content: [{ type: "text", text: `Lane report accepted — ${summarizeLaneReport(parsed.report)}${note}${around}${decoded}${followUp}` }],
         };
@@ -1147,28 +1150,39 @@ server.registerTool("scout_finding", {
             .string()
             .optional()
             .describe("Canonical machine signature for dedup, e.g. 'GET /api/reports/dashboard 403' or 'widget dashboard-summary-widget shows 0'. Same bug re-found later should produce the same string."),
+        convention: z
+            .string()
+            .min(1)
+            .max(LANE_CONVENTION_MAX)
+            .optional()
+            .describe("Only for a WORTH-A-LOOK finding: the observation is real, and it is a defect only under a convention of this project you cannot see. Name that convention, e.g. 'a 4px spacing scale' or 'test ids on every control'. The report lists it under \"Worth a look\", apart from the defects, and does not count it as one. Not for \"I could not tell\": leave that unfiled or look closer. Omit for a defect."),
         session: sessionParam,
     },
-}, serializedPerSession("scout_finding", async ({ severity, category, title, detail, evidence, }, session) => {
+}, serializedPerSession("scout_finding", async ({ severity, category, title, detail, evidence, convention, }, session) => {
     try {
         const eng = engineFor(session);
         if (!eng.memory)
             throw new Error("Not attached — findings need an active session.");
-        const [finding, isNew] = eng.memory.addFinding({
+        const [finding, isNew, promoted] = eng.memory.addFinding({
             severity,
             category: category,
             title,
             detail,
             evidence,
+            ...(convention ? { tier: "worth_a_look", convention } : {}),
             url: eng.currentUrl,
             state: eng.currentState || "(unknown)",
             session: eng.sessionKey,
         });
         return text(isNew
-            ? `Finding recorded: [${finding.severity}] ${finding.title} (id ${finding.id})`
-            : finding.regressedAt
-                ? `⟳ REOPENED as a REGRESSION: finding ${finding.id} was previously resolved but the evidence reproduces again (seen in ${finding.runs} runs). Worth calling out to the user.`
-                : `Not recorded as new: merged into existing finding ${finding.id} — [${finding.severity}] ${finding.title}${finding.evidence ? ` (evidence: ${finding.evidence.slice(0, 160)})` : " (no evidence)"}, seen in ${finding.runs} runs. If yours is a different bug, file it again with evidence naming the request that failed for you (method and path): two findings are kept apart when both name requests and none is shared.`, session);
+            ? isWorthALook(finding)
+                ? `Recorded as worth a look (not a defect in the report's totals): ${finding.title} (id ${finding.id}) — a defect only if your project uses ${finding.convention}`
+                : `Finding recorded: [${finding.severity}] ${finding.title} (id ${finding.id})`
+            : promoted
+                ? `Merged into finding ${finding.id}, which was worth a look, and promoted to a defect: [${finding.severity}] ${finding.title}. It now counts among the report's findings.`
+                : finding.regressedAt
+                    ? `⟳ REOPENED as a REGRESSION: finding ${finding.id} was previously resolved but the evidence reproduces again (seen in ${finding.runs} runs). Worth calling out to the user.`
+                    : `Not recorded as new: merged into existing finding ${finding.id} — [${finding.severity}] ${finding.title}${finding.evidence ? ` (evidence: ${finding.evidence.slice(0, 160)})` : " (no evidence)"}, filed as ${finding.category}, seen in ${finding.runs} runs. If yours is a different bug, file it again: under the category that says what is wrong if it is another kind of defect (a finding filed as ${category} merges only with one filed as ${mergeableCategories(category).join(" or ")}), or with evidence naming the request that failed for you (method and path) — two findings are kept apart when both name requests and none is shared.`, session);
     }
     catch (err) {
         return errorText(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "SceneScout — exploratory UI testing for AI coding agents. An MCP server that gives any agent (Claude Code, Cursor, VS Code Copilot, Codex, Gemini CLI and others) a structured view of a running web app, always-on oracles, a network-level write policy, memory across runs and a gap-checked report.",
   "license": "MIT",
   "author": "brunoboto96",