scenescout 3.2.0 → 3.3.0

package/dist/engine/browser.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { elementKey, fingerprintState, isNonPageRoute, normalizePath } from "./fingerprint.js";
 import { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore, TASK_SET } from "./memory.js";
 import { normalizeTask } from "./task.js";
+import { CLAIM_SCAN_SCRIPT, findContradictions } from "./claims.js";
 import { describeInjection, newInjections, probeQueries, probeScript, probeShape, rememberProbe } from "./injection.js";
 import { AuthLossTracker } from "./authloss.js";
 import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, } from "./collector.js";
@@ -11,6 +12,8 @@ import { OracleMonitor, formatViolations } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
 import { framePath, RECORD_MAX_FRAMES } from "./replay.js";
+import { keepWatchingUrl, normalizePace, SETTLE_TICK_MS, shouldKeepWaiting } from "./settle.js";
+import { buildRequestScript, formatReplay, replaySignature, requestHeaders, resolveMethod, resolveRequestUrl, toReplayResult } from "./request.js";
 import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, screencastSupport, serviceWorkerPolicy, sharedWorkersAllowed, } from "../browsers.js";
 import { revealedLines } from "./hover.js";
 import { explainLaunchFailure, isMissingBrowser } from "./launch.js";
@@ -220,6 +223,69 @@ export class BrowserEngine {
     framesKept = 0;
     /** How many frames could not be written. The first one says so in the log; the rest are counted. */
     framesFailed = 0;
+    /**
+     * The Authorization header the app itself last sent, replayed by
+     * scout_request so a call with the UI bypassed carries the same credential
+     * as a click. Nothing here parses it: whatever scheme the app uses is
+     * whatever gets replayed.
+     */
+    lastAuthHeader = null;
+    rememberAuthHeader(headers) {
+        const value = headers["authorization"] ?? headers["Authorization"];
+        if (value && value.trim())
+            this.lastAuthHeader = value;
+    }
+    /**
+     * Call the app's own API as this session, with the UI bypassed.
+     *
+     * The fetch runs IN the page, so it passes through the same interception the
+     * write policy is enforced on: a safe-write session cannot reach past the
+     * policy by calling an endpoint instead of clicking it. The refusal comes
+     * back as the policy's own error, exactly as it would for a click.
+     */
+    async apiRequest(input) {
+        const page = this.requirePage();
+        const method = resolveMethod(input.method);
+        if ("problem" in method)
+            return `REFUSED: ${method.problem}`;
+        const target = resolveRequestUrl(this.baseUrl, input.path);
+        if ("problem" in target)
+            return `REFUSED: ${target.problem}`;
+        const script = buildRequestScript({
+            url: target.url,
+            method: method.method,
+            body: input.body,
+            headers: requestHeaders({ given: input.headers, auth: this.lastAuthHeader, body: input.body }),
+        });
+        let raw;
+        try {
+            raw = (await page.evaluate(script));
+        }
+        catch (err) {
+            // A blocked request rejects the fetch inside the page. That is the write
+            // policy doing its job, not an app fault, and it is reported as such.
+            const message = err instanceof Error ? err.message : String(err);
+            this.logAction({ action: "request", target: `${method.method} ${input.path}`, url: page.url(), result: `blocked: ${message.split("\n")[0]}` });
+            return `${method.method} ${input.path} — the request did not complete: ${message.split("\n")[0]}\nIn a write-limited mode this is usually the policy refusing it, which is the engine's safety net and not a finding about the app.`;
+        }
+        const result = toReplayResult(raw);
+        this.logAction({
+            action: "request",
+            target: `${method.method} ${input.path}`,
+            url: page.url(),
+            result: replaySignature(method.method, result.url, result.status),
+        });
+        return formatReplay(method.method, result);
+    }
+    /**
+     * The frame field for a log entry, or nothing. Spread into logAction so a
+     * caller that is not going through afterAction can still record what the
+     * page looked like: `...(await this.frameFor("crawl"))`.
+     */
+    async frameFor(action) {
+        const frame = await this.recordFrame(action);
+        return frame ? { frame } : {};
+    }
     /**
      * The frame for the step just taken, as a path relative to the memory
      * directory, or undefined when this run is not recorded. Failing to write
@@ -266,16 +332,26 @@ export class BrowserEngine {
      * until it is replaced — a batch costs a few words, not one per click.
      */
     currentTask = null;
-    /** Set what this session is doing now. An empty value clears it. */
-    setTask(text) {
+    /**
+     * Set what this session is doing now. An empty value clears it.
+     *
+     * `stated` is false for the placeholder attach puts up so a fresh card is
+     * not blank. It shows on the board but does NOT satisfy the requirement that
+     * an agent say what it is doing before it acts — otherwise every session
+     * would run for an hour under "Attaching and taking stock", which is the
+     * guard's whole purpose defeated by its own convenience.
+     */
+    setTask(text, stated = true) {
         const clean = normalizeTask(text);
         if (!clean) {
             this.currentTask = null;
             return;
         }
-        if (this.currentTask?.text === clean)
+        if (this.currentTask?.text === clean && this.currentTask.stated === stated)
+            return;
+        this.currentTask = { text: clean, since: Date.now(), stated };
+        if (!stated)
             return;
-        this.currentTask = { text: clean, since: Date.now() };
         // Logged so the feed can group the actions that follow under it, the way
         // it groups a journey's — the trail is where a watcher reads what
         // happened, and an ungrouped one says nothing about why.
@@ -283,7 +359,7 @@ export class BrowserEngine {
     }
     /** Whether anything is standing that the live view could show as the task. */
     get hasTask() {
-        return this.journey !== null || this.currentTask !== null;
+        return this.journey !== null || (this.currentTask?.stated ?? false);
     }
     /**
      * Begin measuring a user JOURNEY — the interaction cost of completing one
@@ -333,6 +409,15 @@ export class BrowserEngine {
     engineName = "chromium";
     /** Non-GET requests fired since the last action — surfaces silent state mutation in read-only runs (timestamped for attribution). */
     mutationRequests = [];
+    /**
+     * Every request answered since the last action, with its status. The HTTP
+     * oracle sees each 4xx as it happens and reports it on its own; this ledger
+     * exists so the contradiction rules can ask the DIFFERENT question of whether
+     * the page then agreed with the refusal. Capped, because a page that polls
+     * would otherwise grow it without bound.
+     */
+    watchedResponses = [];
+    static MAX_WATCHED_RESPONSES = 60;
     /**
      * Requests the write policy aborted, by identity. The request event fires for
      * every non-GET the page ATTEMPTS, before the route handler decides its fate,
@@ -374,6 +459,52 @@ export class BrowserEngine {
      * element on the current page? Runs wherever violations are drained, so the
      * finding reaches the agent in the result of the action that revealed it.
      */
+    /** Record one answered request for the contradiction rules. Policy-aborted ones are marked, never dropped: the rules need to know they were ours. */
+    watchResponse(req, status) {
+        if (this.watchedResponses.length >= BrowserEngine.MAX_WATCHED_RESPONSES)
+            return;
+        this.watchedResponses.push({
+            method: req.method(),
+            url: req.url(),
+            status,
+            resourceType: req.resourceType(),
+            blockedByPolicy: this.abortedByPolicy.has(req),
+        });
+    }
+    /**
+     * Did the page agree with what the network just did? Runs in the same slot
+     * as the injection scan, so it sees the DOM the action settled on.
+     *
+     * The ledger is cleared whether or not anything is found: these are facts
+     * about ONE action, and carrying a refusal forward would blame the next
+     * action's page for the previous action's request.
+     */
+    async scanForContradictions() {
+        const requests = this.watchedResponses;
+        this.watchedResponses = [];
+        const page = this.page;
+        if (!page || page.isClosed() || requests.length === 0)
+            return;
+        if (!requests.some((r) => r.status === null || r.status >= 400))
+            return;
+        const url = page.url();
+        let state;
+        try {
+            state = (await page.evaluate(CLAIM_SCAN_SCRIPT));
+        }
+        catch {
+            // A page mid-navigation has no DOM to ask.
+            return;
+        }
+        for (const found of findContradictions(requests, state)) {
+            if (this.contradictionsReported.has(found.evidence))
+                continue;
+            this.contradictionsReported.add(found.evidence);
+            this.oracles.noteContradiction(found, url);
+        }
+    }
+    /** Contradiction signatures already reported this session — the same refused endpoint on every page must not flood the run. */
+    contradictionsReported = new Set();
     async scanForInjections() {
         const page = this.page;
         if (!page || page.isClosed() || this.probes.length === 0)
@@ -406,6 +537,9 @@ export class BrowserEngine {
         }
         this.mode = opts.mode ?? "read-only";
         this.sessionObjective = (opts.objective ?? "").trim().replace(/\s+/g, " ").slice(0, 300);
+        // An agent-supplied task counts as stated; the placeholder does not.
+        this.setTask(opts.task ?? "Attaching and taking stock", opts.task !== undefined);
+        this.setPace(opts.paceMs);
         this.recording = opts.record === true;
         // A re-attached engine starts a new recording: numbering from where the
         // last one stopped would run into the cap with frames it never took.
@@ -413,6 +547,8 @@ export class BrowserEngine {
         this.framesFailed = 0;
         this.headed = opts.headed ?? false;
         this.blockedRequests = [];
+        this.watchedResponses = [];
+        this.contradictionsReported = new Set();
         this.pendingCreations = new Set();
         this.baseUrl = opts.url.replace(/\/$/, "");
         // Ownership (ownedIds/createdResources) deliberately NOT reset here: it
@@ -476,7 +612,19 @@ export class BrowserEngine {
         if (this.page)
             watchSockets(this.page);
         this.context.on("page", watchSockets);
+        this.context.on("requestfinished", () => {
+            this.inFlight = Math.max(0, this.inFlight - 1);
+        });
+        this.context.on("requestfailed", (req) => {
+            this.inFlight = Math.max(0, this.inFlight - 1);
+            this.watchResponse(req, null);
+        });
+        this.context.on("response", (res) => {
+            this.watchResponse(res.request(), res.status());
+        });
         this.context.on("request", (req) => {
+            this.inFlight += 1;
+            this.lastRequestStart = Date.now();
             const type = req.resourceType();
             if (type === "xhr" || type === "fetch")
                 this.xhrCount += 1;
@@ -522,6 +670,7 @@ export class BrowserEngine {
                     return route.continue();
                 const url = req.url();
                 const pathname = pathnameOf(url);
+                this.rememberAuthHeader(req.headers());
                 const destructiveWire = isDestructiveWire(pathname, req.postData());
                 // Auth/session flows must work in every mode — but never a destructive
                 // one, and in observe only the requests a login itself needs.
@@ -615,17 +764,30 @@ export class BrowserEngine {
         // is all this used to do — reads as success and names the very file that
         // just failed, so a run would proceed for hundreds of calls against a
         // logged-out browser. The file existing was the only thing ever checked.
-        const authFailed = Boolean(opts.storageStatePath) && this.authLoss.isLoginRedirect(normalizePath(opts.url), this.page.url(), this.baseUrl);
+        // Whether a bounce verdict can matter later: only a session carrying
+        // credentials has any to lose, and only it pays for watching the URL on
+        // every navigation. An anonymous crawl keeps its full speed.
+        this.watchesForBounce = Boolean(opts.storageStatePath);
+        const landed = await this.stableUrl();
+        const authFailed = Boolean(opts.storageStatePath) && this.authLoss.isLoginRedirect(normalizePath(opts.url), landed, this.baseUrl);
+        // An earlier run may have written down how this app's login state is
+        // regenerated. "Regenerate it" is advice the reader already had; the
+        // command that worked last time is the part worth keeping.
+        const recipe = authFailed ? this.memory.setupRecipe() : [];
         const authWarning = authFailed
             ? `\n⚠ AUTH FAILED — the storage state at ${opts.storageStatePath} did not produce a signed-in session: ` +
-                `attaching landed on ${this.page.url()}, a login page. Regenerate it (its token has most likely expired) and re-attach. ` +
-                `Continuing now tests a logged-out app.`
+                `attaching landed on ${landed}, a login page. Regenerate it (its token has most likely expired) and re-attach. ` +
+                `Continuing now tests a logged-out app.` +
+                (recipe.length > 0
+                    ? `\n  Recorded by an earlier run under setup:\n${recipe.map((line) => `    · ${line}`).join("\n")}`
+                    : `\n  Nothing is recorded about how this app's login state is made. Once the user tells you, write it down with scout_note { section: "setup" } so the next run is told instead of asking.`)
             : "";
         return (`Attached to ${this.page.url()} (mode=${this.mode}` +
             `${this.engineName === "chromium" ? "" : `, browser=${this.engineName}, service workers blocked because their requests cannot be intercepted here`}` +
             `${focusAdvanceKey(this.engineName, process.platform) === "Tab" ? "" : `, keyboard: Tab stops only at text fields in this browser — press Alt+Tab to reach buttons and links`}` +
             `${opts.storageStatePath ? `, auth=${opts.storageStatePath}` : ""}). ` +
             `Memory: ${this.memory.dir}.${this.memory.loadWarning ? ` WARNING: ${this.memory.loadWarning}` : ""}` +
+            (this.memory.prunedStates > 0 ? ` Trimmed ${this.memory.prunedStates} old page state(s) from the history; coverage is unchanged.` : "") +
             `${this.memory.legacyDirNote ? ` ${this.memory.legacyDirNote}` : ""}` +
             `${this.memory.gitIgnoreNote ? ` ${this.memory.gitIgnoreNote}` : ""} Call scout_snapshot to see the current state.` +
             authWarning);
@@ -651,11 +813,80 @@ export class BrowserEngine {
     async settle() {
         const page = this.requirePage();
         await page.waitForLoadState("domcontentloaded").catch(() => { });
-        // A fixed floor, deliberately: waitForLoadState("networkidle") is latched
-        // once reached and resolves instantly forever after, so it cannot be used
-        // to wait out in-flight requests here — and draining oracles before a
-        // just-fired request lands would misattribute its violations.
-        await page.waitForTimeout(SETTLE_MS);
+        // Wait on what is actually in flight rather than a flat sleep. The rule is
+        // in settle.ts so it can be table-tested; the reasoning for not using
+        // networkidle is there too.
+        const started = Date.now();
+        for (;;) {
+            const state = {
+                inFlight: this.inFlight,
+                sinceLastStartMs: Date.now() - this.lastRequestStart,
+                elapsedMs: Date.now() - started,
+                paceMs: this.paceMs,
+            };
+            if (!shouldKeepWaiting(state))
+                return;
+            await page.waitForTimeout(SETTLE_TICK_MS).catch(() => { });
+            if (this.page !== page)
+                return;
+        }
+    }
+    /**
+     * The URL once it has stopped changing.
+     *
+     * Only called where a bounce verdict is about to be made. A client-side auth
+     * guard redirects on a timer and issues no request until it does, so the
+     * request-based settle has nothing to wait on and the page is read while it
+     * is still, briefly, the page it was asked for.
+     */
+    async stableUrl() {
+        const page = this.page;
+        if (!page || page.isClosed())
+            return page ? page.url() : "";
+        const started = Date.now();
+        let url = page.url();
+        let changedAt = started;
+        for (;;) {
+            if (!keepWatchingUrl({ sinceChangeMs: Date.now() - changedAt, elapsedMs: Date.now() - started }))
+                return url;
+            await page.waitForTimeout(SETTLE_TICK_MS).catch(() => { });
+            if (this.page !== page || page.isClosed())
+                return url;
+            const now = page.url();
+            if (now !== url) {
+                url = now;
+                changedAt = Date.now();
+            }
+        }
+    }
+    /**
+     * Where a navigation landed. Watched for a late client-side guard only when
+     * this session has credentials to lose. The page is passed in rather than
+     * read off the engine so a session torn down mid-navigation still reports
+     * the last URL it was on, which is what the outcome is recorded against.
+     */
+    async landedUrl(page) {
+        return this.watchesForBounce ? await this.stableUrl() : page.url();
+    }
+    /** Set at attach: this session was given credentials, so a bounce to a login page is a verdict worth waiting for. */
+    watchesForBounce = false;
+    /** Requests started and not yet finished or failed, from the context's own events. */
+    inFlight = 0;
+    /** When the most recent request started, so a page that fires one late is not read too early. */
+    lastRequestStart = 0;
+    /**
+     * A floor between actions this session was asked for, so a person watching
+     * can follow along. Zero means as fast as the page allows, which is the
+     * default and what every run wants unless somebody is reading it live.
+     */
+    paceMs = 0;
+    /** Set the deliberate pace. Returns what it became, clamped. */
+    setPace(paceMs) {
+        this.paceMs = normalizePace(paceMs);
+        return this.paceMs;
+    }
+    get pace() {
+        return this.paceMs;
     }
     /** Collect the current page's interactables into SnapshotElements with stable refs. */
     async collect() {
@@ -788,8 +1019,13 @@ export class BrowserEngine {
         this.currentFingerprint = fp;
         const isNew = memory.visitState(fp, url, route, elements.map((el) => el.key));
         memory.recordRoleAccess(this.role, route, "reached");
-        this.logAction({ action: "snapshot", url, result: fp });
+        // A snapshot is what an agent takes when it wants to LOOK at something, so
+        // it is the frame a reader most wants beside the step. Recording only the
+        // actions that go through afterAction kept 9 frames out of 67 in a real
+        // run, and none of them from the routes a crawl had just swept.
+        this.logAction({ action: "snapshot", url, result: fp, ...(await this.frameFor("snapshot")) });
         await this.scanForInjections();
+        await this.scanForContradictions();
         const line = (el) => {
             const dup = el.key.match(/~(\d+)$/);
             const flags = [
@@ -949,6 +1185,7 @@ export class BrowserEngine {
         const frame = await this.recordFrame(action);
         this.logAction({ action, target, url, ...(frame ? { frame } : {}) });
         await this.scanForInjections();
+        await this.scanForContradictions();
         const violations = this.oracles.drain();
         const mutations = this.drainMutations() + this.drainBlocked() + this.drainCreated();
         const navigated = this.snapshotUrl !== "" && url !== this.snapshotUrl;
@@ -1639,14 +1876,14 @@ export class BrowserEngine {
             settled = await this.afterAction("navigate", url);
         }
         catch (err) {
-            this.recordNavigationOutcome(url, page.url());
+            this.recordNavigationOutcome(url, await this.landedUrl(page));
             const notice = this.authLoss.take();
             if (!notice)
                 throw err;
             const msg = err instanceof Error ? err.message : String(err);
             throw new Error(`${notice}${msg}`);
         }
-        this.recordNavigationOutcome(url, page.url());
+        this.recordNavigationOutcome(url, await this.landedUrl(page));
         return this.authLoss.take() + settled;
     }
     /** Where did we ASK to go, where did we END UP, and does that count as coverage? */
@@ -1767,8 +2004,9 @@ export class BrowserEngine {
             // an attempt with the status satisfies the contract.
             if (typeof status === "number" && status >= 400)
                 memory.markAttempted(requestedRoute, `status:${status}`, this.role);
-            this.logAction({ action: "crawl", target: path, url: finalUrl });
+            this.logAction({ action: "crawl", target: path, url: finalUrl, ...(await this.frameFor("crawl")) });
             await this.scanForInjections();
+            await this.scanForContradictions();
             const violations = this.oracles.drain();
             const deadEnd = elements.length === 0;
             const unnamed = elements.filter((el) => !el.name).length;
@@ -1940,7 +2178,11 @@ export class BrowserEngine {
                     }
                 }
                 await this.settle();
-                this.logAction({ action: `plan:${step.action}`, target: step.target ?? step.value, url: page.url() });
+                // A plan is the RECOMMENDED way to run a mechanical sequence, so its
+                // steps are where most of a recorded run actually happens. Leaving
+                // them unframed reproduced, inside run_plan, the same hole that crawl
+                // had: a form filled and submitted with no picture of any of it.
+                this.logAction({ action: `plan:${step.action}`, target: step.target ?? step.value, url: page.url(), ...(await this.frameFor(`plan-${step.action}`)) });
                 // Plans must feed coverage like ref-based actions do: record the
                 // state and mark the acted-on element class as exercised.
                 // Hover is deliberately excluded: a hover is a look, not an
@@ -1985,6 +2227,7 @@ export class BrowserEngine {
                     }
                 }
                 await this.scanForInjections();
+                await this.scanForContradictions();
                 const violations = this.oracles.drain();
                 const mutations = this.drainMutations() + this.drainBlocked() + this.drainCreated();
                 // Abort only on NEW violations: a known-failing endpoint repeating on
@@ -2048,7 +2291,7 @@ export class BrowserEngine {
             this.memory?.setPageScore(route, { ...score, at: new Date().toISOString(), url: page.url() });
             this.memory?.markRouteFact(route, { audited: true });
         }
-        this.logAction({ action: "design-audit", url: page.url(), result: score ? `score:${score.overall}` : undefined });
+        this.logAction({ action: "design-audit", url: page.url(), result: score ? `score:${score.overall}` : undefined, ...(await this.frameFor("design-audit")) });
         return `URL: ${page.url()}\n` + report;
     }
     /**

package/dist/engine/claims.js

@@ -0,0 +1,194 @@
+/**
+ * What the page says about itself, checked against what actually happened.
+ *
+ * Two of the most expensive bugs a web app ships are invisible to every oracle
+ * that watches only one side of the wire:
+ *
+ *   - A list request is refused (401, 403, 500) and the page renders its empty
+ *     state. The user is told they have nothing, when the truth is that nothing
+ *     could be loaded. Nobody files a bug, because the screen looks fine — it
+ *     is the single most common way a permission regression reaches production
+ *     without anyone noticing.
+ *   - A save is refused and the page says "Saved". The user walks away
+ *     believing their work is stored.
+ *
+ * Neither is a crash, so `console_error` and `http_error` miss the harm: the
+ * HTTP oracle sees the 403 and reports it as a medium, indistinguishable from
+ * the dozens of expected 401s an auth probe produces. The defect is not the
+ * refusal. It is the page CONTRADICTING the refusal.
+ *
+ * The rules pair a precise half with a fuzzy one. The request half is exact —
+ * a status code either is an error or is not. The page half only has to be
+ * roughly right, because it is never enough on its own: no contradiction is
+ * reported unless a request was genuinely refused during the same action. That
+ * asymmetry is what keeps the false-positive rate low enough to be worth
+ * reporting at high severity.
+ *
+ * Everything here is pure so it can be table-tested; the DOM read lives in
+ * browser.ts.
+ */
+import { VISIBLE_SRC } from "./collector.js";
+/**
+ * Methods whose refusal a success message would be lying about. A refused GET
+ * is the empty-state rule's business; a refused POST is this one's.
+ */
+const WRITING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/**
+ * Resource types worth correlating. A failed image, font or analytics beacon
+ * says nothing about whether the list on screen is real, and correlating them
+ * would fire on every page with a broken logo.
+ */
+const DATA_RESOURCES = new Set(["xhr", "fetch", "document"]);
+/** Whether this request is one whose refusal the page should be admitting to. */
+export function isRefused(req) {
+    if (req.blockedByPolicy)
+        return false;
+    if (!DATA_RESOURCES.has(req.resourceType))
+        return false;
+    if (req.status === null)
+        return true;
+    return req.status >= 400;
+}
+/**
+ * Phrases that assert there is nothing to show.
+ *
+ * Deliberately narrow: these are the stock empty-state sentences, not any
+ * sentence containing "no". "No results", "Nothing to show", "You have no
+ * orders" match; "No changes were saved since yesterday" does not, because the
+ * assertion has to be about the absence of the things themselves.
+ */
+const EMPTY_RE = /\b(?:no (?:results?|items?|records?|rows?|data|entries|matches)\b|nothing (?:to (?:show|display)|here|found)\b|(?:there are|you have|we found) no\b|(?:0|zero) (?:results?|items?|records?|rows?|matches)\b|no [a-z]{3,20}s (?:found|yet|to show)\b|empty\b)/i;
+/**
+ * Phrases that assert something worked. A page that says one of these while
+ * the write that produced it was refused is telling the user a falsehood.
+ */
+const SUCCESS_RE = /\b(?:success(?:fully)?|saved|created|updated|deleted|removed|submitted|sent|published|approved|completed|added|changes? saved|done)\b/i;
+/**
+ * Phrases that admit something went wrong. Their presence is what makes a page
+ * INNOCENT: an app that refuses a request and says so has behaved correctly,
+ * whatever else is on the screen, and must not be reported.
+ */
+const ERROR_RE = /\b(?:error|failed|failure|could ?n[o']?t|unable to|went wrong|try again|retry|denied|forbidden|unauthori[sz]ed|not allowed|no permission|timed out|unavailable|problem loading)\b/i;
+/** Longest piece of text judged. An empty state is a sentence; a paragraph that happens to contain one of these words is not a claim. */
+export const CLAIM_TEXT_MAX = 120;
+/**
+ * What one piece of visible page text asserts, or nothing when it asserts none
+ * of these. An admission of error outranks the others: a banner reading
+ * "Couldn't load orders — no results to show" is the app being honest.
+ */
+export function classify(text) {
+    const trimmed = text.trim();
+    if (!trimmed || trimmed.length > CLAIM_TEXT_MAX)
+        return null;
+    if (ERROR_RE.test(trimmed))
+        return "error";
+    if (SUCCESS_RE.test(trimmed))
+        return "success";
+    if (EMPTY_RE.test(trimmed))
+        return "empty";
+    return null;
+}
+function shortUrl(url) {
+    try {
+        const u = new URL(url);
+        return u.pathname + u.search;
+    }
+    catch {
+        return url.slice(0, 120);
+    }
+}
+function say(req) {
+    return `${req.method} ${shortUrl(req.url)} ${req.status === null ? "failed" : req.status}`;
+}
+/**
+ * The contradictions this action produced, if any.
+ *
+ * Both rules are silent whenever the page admits the failure, and both require
+ * a genuinely refused request — the page half never fires alone.
+ */
+export function findContradictions(requests, page) {
+    const refused = requests.filter(isRefused);
+    if (refused.length === 0)
+        return [];
+    const claims = page.texts.map(classify);
+    // An app that says what went wrong has behaved correctly, and nothing below
+    // applies. This is checked before anything else so that a page carrying both
+    // an error banner and a stale empty state is not reported.
+    if (claims.includes("error"))
+        return [];
+    const out = [];
+    const reads = refused.filter((r) => !WRITING_METHODS.has(r.method.toUpperCase()));
+    const saysEmpty = claims.includes("empty") || page.emptyLists > 0;
+    if (reads.length > 0 && saysEmpty) {
+        const worst = reads[0];
+        const how = claims.includes("empty") ? "an empty state" : `an empty list (${page.emptyLists})`;
+        out.push({
+            kind: "refused_empty",
+            detail: `${say(worst)} was refused, and the page shows ${how} with no error. ` +
+                `The user is told there is nothing to see when the truth is that nothing could be loaded.`,
+            evidence: `refused-empty ${say(worst)}`,
+        });
+    }
+    const writes = refused.filter((r) => WRITING_METHODS.has(r.method.toUpperCase()));
+    if (writes.length > 0 && claims.includes("success")) {
+        const worst = writes[0];
+        const message = page.texts[claims.indexOf("success")];
+        out.push({
+            kind: "false_success",
+            detail: `${say(worst)} was refused, and the page says ${JSON.stringify(message.trim().slice(0, 80))}. The user is told their change was kept when the server rejected it.`,
+            evidence: `false-success ${say(worst)}`,
+        });
+    }
+    return out;
+}
+/** Most pieces of text read from one page. A page with more than this has nothing useful to say in the extra ones. */
+export const MAX_CLAIM_TEXTS = 120;
+/**
+ * Page-side reader for the two signals `findContradictions` needs. Shipped as
+ * a STRING expression for the same reason the collector is: loader transforms
+ * inject a `__name` helper that does not exist in the browser, and a
+ * serialized function carrying a call to it fails there.
+ *
+ * Text is taken as each element's OWN text nodes, not its subtree, so a
+ * sentence is read once rather than again for every ancestor that contains it.
+ *
+ * The empty-list count is structural on purpose: most apps write no
+ * empty-state sentence at all, and the ones that do write it in the user's
+ * language. A container that renders its header and no rows says the same
+ * thing in every language and in every design system.
+ */
+export const CLAIM_SCAN_SCRIPT = `(() => {
+  const visible = ${VISIBLE_SRC};
+  const texts = [];
+  const seen = new Set();
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);
+  let el = document.body;
+  while (el && texts.length < ${MAX_CLAIM_TEXTS}) {
+    let own = "";
+    for (const node of el.childNodes) if (node.nodeType === 3) own += node.nodeValue;
+    own = own.replace(/\\s+/g, " ").trim();
+    if (own && own.length <= ${CLAIM_TEXT_MAX} && !seen.has(own) && visible(el)) {
+      seen.add(own);
+      texts.push(own);
+    }
+    el = walker.nextNode();
+  }
+
+  // A list or table that renders its container but no rows. Hidden ones are
+  // templates and dropdown shells, not empty states.
+  let emptyLists = 0;
+  for (const list of document.querySelectorAll("table, ul, ol, [role='table'], [role='grid'], [role='list']")) {
+    if (!visible(list)) continue;
+    const tag = list.tagName.toLowerCase();
+    if (tag === "table") {
+      const body = list.tBodies[0];
+      // No header means it is a layout table, not a record list.
+      if (!list.querySelector("th, thead")) continue;
+      if (body && body.rows.length === 0) emptyLists += 1;
+      continue;
+    }
+    const rows = list.querySelectorAll(":scope > li, :scope > [role='row'], :scope > [role='listitem']");
+    if (rows.length === 0) emptyLists += 1;
+  }
+  return { texts, emptyLists };
+})()`;