scenescout 3.19.1 → 3.20.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # scenescout
 
+## 3.20.0
+
+### Minor Changes
+
+- eb79ce8: `scenescout check --record` (or `SCENESCOUT_RECORD=on`) keeps a frame after each route visit and each saved-flow step and writes `replay.html` beside the report: each role, each journey with a pass or fail badge, each step with its caption, result and frame, the first failing step highlighted, and the run's version, times, origin and commit in the header. `--video` records a WebM of each saved flow, each on a page of its own, and the replay page plays it beside the journey's steps. The GitHub Action gains `record` and `video` inputs and a `replay` output, and keeps the page, its frames and its videos in the uploaded artifact.
+
+## 3.19.2
+
+### Patch Changes
+
+- 3b953a7: `refused-empty` now pairs an empty-state sentence with the refused read it is about (#413). A sentence that names what is missing ("No comments yet", "There are no orders") is reported at high when a refused read's path names the same thing, and not at all when a successful data read on the page fetched that thing instead: it is a genuinely empty section beside an unrelated refusal. A named sentence that matches neither is still reported, at medium, so `scenescout check` no longer fails a `--fail-on high` gate on it. Sentences that name nothing in particular ("No results", "Nothing to show") and empty rendered lists pair with any refused read at high, as before, and the finding names the refused read the sentence points at. Existing `refused-empty` fingerprints can change once on upgrade, because the evidence may now name a different read.
+
 ## 3.19.1
 
 ### Patch Changes

package/README.md

@@ -277,7 +277,9 @@ Use SceneScout to test http://localhost:3000, record the run
 ```
 
 or, on the tool directly, `scout_attach {record: true}`. `SCENESCOUT_RECORD=on` in
-the server's environment records every run.
+the server's environment records every run. A CI gate records too:
+`scenescout check --record` writes `replay.html`, every journey step by step with
+its frames ([recording a check](docs/ci.md#recording-a-check)).
 
 Then `scout_report` writes two files side by side in `.scenescout/`:
 `report.md` as always, and `report.html` — the whole run as one self-contained
@@ -454,6 +456,7 @@ With the default settings its saved flows send no HTTP write (they replay under
 - `--on-refused-step report|stop` (default `report`): `report` marks a flow whose step was refused "could not run", keeps every other verdict and exits 2; `stop` exits 2 at that step with no results.
 - `--gate-retests never|high|all` (default `high`): which still-reproducing re-tested findings fail the gate.
 - `--baseline off|compare|update` (default `off`), with `--baselines <dir>` and `--baseline-threshold <percent>` (default `0.1`, so small anti-aliasing noise between machines passes): visual baselines, below.
+- `--record` (or `SCENESCOUT_RECORD=on`; the action's `record: on`) keeps a frame after each route visit and each saved-flow step and writes `replay.html` beside the report: each role, each journey with a pass or fail badge, each step with its caption, result and frame, the first failing step highlighted. `--video` (the action's `video: on`) adds a WebM of each journey, played on that page beside its steps. Both off by default. [docs/ci.md](docs/ci.md#recording-a-check) covers size, privacy and publishing it.
 
 The defaults are what an unconfigured check does, for a first try or an AI agent running it unattended: its flows send no HTTP write and it never silently hides a result. Each setting is a choice for the project; the report and `check.json` print the values a check ran with.
 

package/dist/check-run.js

@@ -19,6 +19,7 @@ import { decodePng, encodePng } from "./engine/png.js";
 import { firstLineOf } from "./engine/limits.js";
 import { isNonPageResource } from "./engine/crawl.js";
 import { checkRetestPlan, retestResults, wellFormedFindings } from "./engine/verify.js";
+import { capFrames, isReplayFrameFile, journeyOf, journeyVideoPath, isJourneyVideoFile, redactReplay, REPLAY_VIDEOS_DIRNAME, replayVideos, REPLAY_FILE, REPLAY_FRAMES_DIRNAME, replayFramePath, replayFrames, replaySessionKey, visitOf, } from "./engine/check-replay.js";
 /** The baselines folder a check uses: the one --baselines names, else the project's own. */
 export function baselinesDirOf(options) {
     return options.baselinesDir ?? defaultBaselinesDir(options.projectDir);
@@ -99,6 +100,21 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
     const engine = new BrowserEngine();
     /** One browser per role a flow runs as, each attached once, on first use, and closed with the check's own. */
     const roleEngines = new Map();
+    // --record: every browser keeps a frame after each step, under its own session name, in its own memory folder.
+    const record = options.record === true;
+    const startedAt = new Date().toISOString();
+    const store = new MemoryStore(scratch);
+    if (record)
+        engine.sessionKey = replaySessionKey();
+    // --video: each browser records every page into its own scratch folder, and each flow's own page is saved beside the report.
+    const video = options.video === true;
+    const outDir = options.outDir ?? defaultCheckDir(options.projectDir);
+    // The default folder is inside .scenescout/, which ignores itself; its .gitignore goes first, so no frame or video is ever unignored.
+    if ((record || video) && !options.outDir) {
+        const scenescoutDir = path.join(options.projectDir, MEMORY_DIRNAME);
+        fs.mkdirSync(scenescoutDir, { recursive: true });
+        writeSelfIgnore(scenescoutDir);
+    }
     const start = new URL(options.url);
     // From the start of the run, browser launch included: the budget is wall-clock time a person waits.
     const deadline = options.timeBudgetMs !== undefined ? Date.now() + options.timeBudgetMs : undefined;
@@ -109,9 +125,11 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
         const attached = await engine.attach({
             url: start.origin,
             projectDir: options.projectDir,
-            memoryStore: new MemoryStore(scratch),
+            memoryStore: store,
             mode: options.mode,
             storageStatePath: options.storageStatePath,
+            ...(record ? { record: true } : {}),
+            ...(video ? { videoDir: path.join(scratch, "video") } : {}),
             ...(options.browser ? { browser: options.browser } : {}),
             actionTimeoutMs: options.actionTimeoutMs,
             navTimeoutMs: options.navTimeoutMs,
@@ -178,6 +196,8 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
                 return known;
             const roleEngine = new BrowserEngine();
             roleEngines.set(role, roleEngine);
+            if (record)
+                roleEngine.sessionKey = replaySessionKey(role);
             const roleDir = path.join(scratch, `role-${role}`);
             fs.mkdirSync(roleDir, { recursive: true });
             const attachedAs = await roleEngine.attach({
@@ -186,6 +206,8 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
                 memoryStore: new MemoryStore(roleDir),
                 mode: options.mode,
                 role,
+                ...(record ? { record: true } : {}),
+                ...(video ? { videoDir: path.join(roleDir, "video") } : {}),
                 ...(options.browser ? { browser: options.browser } : {}),
                 actionTimeoutMs: options.actionTimeoutMs,
                 navTimeoutMs: options.navTimeoutMs,
@@ -197,10 +219,29 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
                 throw new Error(`the saved sign-in for role "${role}" no longer signs in: ${lost.replace(/ Continuing now tests a logged-out app\.$/, "")}`);
             return roleEngine;
         };
+        /** On a recorded check, the frames each flow's steps left, beside the flow. */
+        const flowFrames = [];
+        /** On a check with --video, each flow's video beside the report (relative to it), or null where none was saved. */
+        const flowVideos = [];
         for (const flow of runFlows) {
             const runner = await engineFor(flow.role);
             // --flow-writes never: observe's rule, whatever --mode lets the crawl do.
-            const replay = await runner.replayFlow(flow.steps, options.flowWrites === "never" ? "observe" : options.mode);
+            const walk = () => runner.replayFlow(flow.steps, options.flowWrites === "never" ? "observe" : options.mode);
+            let walked;
+            if (video) {
+                // A page of its own, so the video is this journey's alone; the context, and so the sign-in, is the role's.
+                const rel = journeyVideoPath(flowRuns.length + 1, flow.file);
+                const own = await runner.onOwnPage(walk, path.join(outDir, ...rel.split("/")));
+                walked = own.value;
+                flowVideos.push(own.video ? rel : null);
+                if (own.videoError)
+                    log(`  flow ${flow.name}: its video could not be saved (${own.videoError})`);
+            }
+            else {
+                walked = await walk();
+            }
+            const { frames, ...replay } = walked;
+            flowFrames.push(frames ?? []);
             flowRuns.push({ name: flow.name, file: flow.file, steps: flow.steps.length, ...(flow.role === undefined ? {} : { role: flow.role }), ...replay });
             log(`  flow ${flow.name}${flow.role === undefined ? "" : ` (as ${flow.role})`}: ${replay.outcome.status}${replay.outcome.status === "passed" ? "" : ` at step ${replay.outcome.step}`}`);
             // --on-refused-step stop: nothing after a refused step runs, and the check ends without a verdict.
@@ -222,6 +263,22 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
                 }))),
             }
             : null;
+        const replay = record || video
+            ? recordReplay({
+                options,
+                startedAt,
+                ownRole: engine.role,
+                log: store.actionLog,
+                visited: [...routes, ...retestPages],
+                flows: runFlows
+                    .slice(0, flowRuns.length)
+                    .map((flow, i) => ({ flow, outcome: flowRuns[i].outcome, frames: flowFrames[i], video: flowVideos[i] ?? null })),
+                scratch,
+                say: log,
+            })
+            : null;
+        if (replay)
+            log(`  kept ${replayFrames(replay).length} frame(s) and ${replayVideos(replay).length} video(s) for ${REPLAY_FILE}`);
         const { pages: measured, resources } = splitResources(redactRoutes(routes.map(withoutOwnResponse)));
         const flows = redactFlowRuns(flowRuns);
         const pictured = baselines ? redactBaselineRun(baselines) : null;
@@ -248,6 +305,7 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
             retest,
             settings: settingsOf(options),
             baselines: pictured,
+            ...(replay ? { replay } : {}),
         };
         // A value taken from the environment (a code, a password) is never written, wherever the page echoed it.
         return envValues.size > 0 ? JSON.parse(maskEnvValues(JSON.stringify(result), envValues)) : result;
@@ -403,3 +461,118 @@ async function takeBaselines(engine, options, mode, targets, log) {
     }
     return { mode, engine: engineName, threshold: options.baselineThreshold, dir: shownDir(dir, options.projectDir), results };
 }
+/**
+ * Remove what an earlier recorded check left beside the report: replay.html,
+ * the frames under replay-frames/ and the journey videos under replay-videos/
+ * that a check names as it names them (isReplayFrameFile, isJourneyVideoFile),
+ * then any folder that leaves empty. Run before every
+ * check, recorded or not, so a page from an earlier run is never read, or
+ * uploaded, as this one's; whatever else the folder holds stays.
+ */
+export function clearReplayOutput(outDir) {
+    fs.rmSync(path.join(outDir, REPLAY_FILE), { force: true });
+    const videos = path.join(outDir, REPLAY_VIDEOS_DIRNAME);
+    if (fs.existsSync(videos)) {
+        for (const file of fs.readdirSync(videos, { withFileTypes: true }))
+            if (file.isFile() && isJourneyVideoFile(file.name))
+                fs.rmSync(path.join(videos, file.name));
+        if (fs.readdirSync(videos).length === 0)
+            fs.rmdirSync(videos);
+    }
+    const root = path.join(outDir, REPLAY_FRAMES_DIRNAME);
+    let folders;
+    try {
+        folders = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+    for (const folder of folders.filter((f) => f.isDirectory())) {
+        const dir = path.join(root, folder.name);
+        for (const file of fs.readdirSync(dir, { withFileTypes: true }))
+            if (file.isFile() && isReplayFrameFile(file.name))
+                fs.rmSync(path.join(dir, file.name));
+        if (fs.readdirSync(dir).length === 0)
+            fs.rmdirSync(dir);
+    }
+    if (fs.readdirSync(root).length === 0)
+        fs.rmdirSync(root);
+}
+/**
+ * The replay page's model for a recorded check, with its frames copied from
+ * the browsers' scratch folders to replay-frames/ beside the report: routes
+ * visited in the check's own session, then each flow under the role it ran
+ * as. Capped and redacted here, so what is copied is exactly what the page shows.
+ */
+function recordReplay(o) {
+    const outDir = o.options.outDir ?? defaultCheckDir(o.options.projectDir);
+    /** Where each frame the page names is copied from. */
+    const sources = new Map();
+    const beside = (recorded, memoryDir) => {
+        const to = recorded ? replayFramePath(recorded) : null;
+        if (to && recorded)
+            sources.set(to, path.join(memoryDir, ...recorded.split("/")));
+        return to;
+    };
+    // The crawl's frames, by the path each visit asked for, in the order they were taken.
+    const own = replaySessionKey();
+    const crawled = new Map();
+    for (const e of o.log) {
+        if (e.action !== "crawl" || !e.frame || e.target === undefined || (e.session ?? own) !== own)
+            continue;
+        crawled.set(e.target, [...(crawled.get(e.target) ?? []), e.frame]);
+    }
+    const ownSession = {
+        role: o.ownRole,
+        own: true,
+        // A MemoryStore keeps its files, frames included, in the .scenescout folder of the directory it is given.
+        visits: o.visited.map((route) => visitOf(route, beside(crawled.get(route.path)?.shift(), path.join(o.scratch, MEMORY_DIRNAME)) ?? undefined)),
+        journeys: [],
+    };
+    const roles = [ownSession];
+    for (const { flow, outcome, frames, video } of o.flows) {
+        const memoryDir = path.join(flow.role === undefined ? o.scratch : path.join(o.scratch, `role-${flow.role}`), MEMORY_DIRNAME);
+        const journey = journeyOf(flow, outcome, frames.map((f) => beside(f, memoryDir)));
+        if (video)
+            journey.video = video;
+        let role = flow.role === undefined ? ownSession : roles.find((r) => !r.own && r.role === flow.role);
+        if (!role) {
+            role = { role: flow.role, own: false, visits: [], journeys: [] };
+            roles.push(role);
+        }
+        role.journeys.push(journey);
+    }
+    const replay = redactReplay(capFrames({ startedAt: o.startedAt, roles, framesLeftOut: 0 }));
+    // A frame that cannot be copied is left off the page rather than shown broken.
+    const copied = new Set();
+    let failed = false;
+    for (const rel of replayFrames(replay)) {
+        const from = sources.get(rel);
+        if (!from)
+            continue;
+        try {
+            const to = path.join(outDir, ...rel.split("/"));
+            fs.mkdirSync(path.dirname(to), { recursive: true });
+            fs.copyFileSync(from, to);
+            copied.add(rel);
+        }
+        catch (err) {
+            // Said once: a folder that refuses one frame usually refuses them all.
+            if (!failed)
+                o.say(`  could not copy a recorded frame to ${outDir}: ${firstLineOf(err)}; frames that could not be copied are left off ${REPLAY_FILE}`);
+            failed = true;
+        }
+    }
+    const keep = (item) => {
+        if (!item.frame || copied.has(item.frame))
+            return item;
+        const { frame: _gone, ...rest } = item;
+        return rest;
+    };
+    return {
+        ...replay,
+        roles: replay.roles.map((r) => ({ ...r, visits: r.visits.map(keep), journeys: r.journeys.map((j) => ({ ...j, steps: j.steps.map(keep) })) })),
+    };
+}

package/dist/cli.js

@@ -21,7 +21,9 @@ import { APPROX_DISK_MB, defaultAttachNote, defaultEngine, launchTarget, parseBr
 import { CLIENT_LABELS, firstMessageHint, manualFor, parseClients, registerWithClient, vscodeBinary } from "./clients.js";
 import { CLAUDE_CODE_NOT_NEEDED, CLI_NAME, desktopExtensionRoots, diagnose, doctorAllGood, findDesktopExtension, installClosing, ensureCommand, findOnUserPath, installSkill, isEphemeralRoot, launchCommand, manualRegisterCommand, planCommand, registerMcp, resolveClaudeDir, spawnRunner, } from "./installer.js";
 import { downloadBrowsers, presentBrowsers } from "./installer.js";
-import { baselinesDirOf, defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
+import { baselinesDirOf, clearReplayOutput, defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
+import { buildCheckReplayHtml, commitOf, REPLAY_FILE, replayFrames, replayVideos } from "./engine/check-replay.js";
+import { recordChoice } from "./engine/capture.js";
 import { httpClient, httpJudgeAsk, runCi } from "./ci-run.js";
 import { runExport } from "./export-run.js";
 import { runLogin, runScriptedLogin, savedLine } from "./login-run.js";
@@ -29,7 +31,7 @@ import { credentialRedactor, LOGIN_ENV, readScriptedLogin } from "./engine/scrip
 import { parseLoginArgs } from "./engine/profiles.js";
 import { detectProvider, EXIT_CI, judgeEffort, KEY_ENV, parseCiArgs, redactKeys, secretValues } from "./engine/ci.js";
 import { VISUAL_DIRNAME } from "./engine/baseline.js";
-import { EXIT, exitCodeOf, formatCheck, parseCheckArgs, refusedFlowReason, toSarif, toSummaryJson, unmeasuredReason, } from "./engine/check.js";
+import { EXIT, exitCodeOf, formatCheck, parseCheckArgs, refusedFlowReason, summarise, toSarif, toSummaryJson, unmeasuredReason, } from "./engine/check.js";
 import { downloadLine, EXIT_FIRST_RUN, FIRST_RUN_DIRNAME, firstRunCheckOptions, firstRunDownloads, firstRunSummary, formatFirstRun, modeSentence, parseFirstRunArgs, reportFolderProblem, unreachableReason, writeFirstRunReport, } from "./first-run.js";
 import { credentialSecrets, EXIT_EXPORT, parseExportArgs } from "./engine/export.js";
 import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME, writeSelfIgnore } from "./engine/memory.js";
@@ -105,7 +107,13 @@ Usage:
                                       passes; 0 counts every changed pixel);
                                      --sarif-file-anchor path: the repository file a SARIF result points at when
                                       no saved flow raised it (default: the running workflow's file on GitHub
-                                      Actions, else package.json, else README.md))
+                                      Actions, else package.json, else README.md);
+                                     --record [on|off]: keep a frame after each route visit and each flow step
+                                      and write replay.html beside the report, role → journey → step (default:
+                                      SCENESCOUT_RECORD, else off; the frames go in replay-frames/);
+                                     --video [on|off]: record a WebM of each saved flow, each on a page of its
+                                      own, into replay-videos/, linked from replay.html beside its steps
+                                      (default off))
                                     Exit code: 0 passed, 1 failed the gate, 2 could not run.
   scenescout ci <url>               An exploratory run with no person present: a model reached through its API
                                     drives the tools by the SceneScout method and the run ends in the report.
@@ -570,10 +578,14 @@ async function check(args) {
         console.error(`scenescout check: ${parsed.error}`);
         process.exit(EXIT.error);
     }
-    const options = parsed.options;
+    let options = parsed.options;
     const outDir = options.outDir ?? defaultCheckDir(options.projectDir);
     let inputs;
     try {
+        // --record, else SCENESCOUT_RECORD, else off.
+        options = { ...options, record: recordChoice(options.record, process.env) };
+        // A replay page an earlier run left must never be read, or uploaded, as this run's.
+        clearReplayOutput(outDir);
         inputs = readCheckInputs(options);
     }
     catch (err) {
@@ -618,6 +630,19 @@ async function check(args) {
             console.error(`scenescout check: ${sarifFiles.warning}`);
         fs.writeFileSync(path.join(outDir, "check.sarif"), JSON.stringify(toSarif(result, version, sarifFiles), null, 2) + "\n");
         fs.writeFileSync(path.join(outDir, "check.json"), JSON.stringify(toSummaryJson(result, version), null, 2) + "\n");
+        if (result.replay) {
+            const { passed, couldNotRun } = summarise(result);
+            const html = buildCheckReplayHtml(result.replay, {
+                version,
+                origin: new URL(result.url).origin,
+                startedAt: result.replay.startedAt,
+                endedAt: result.generatedAt,
+                commit: commitOf(process.env),
+                passed,
+                couldNotRun,
+            });
+            fs.writeFileSync(path.join(outDir, REPLAY_FILE), html);
+        }
         // On GitHub Actions the verdict also goes on the run's summary page.
         if (process.env.GITHUB_STEP_SUMMARY)
             fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, markdown);
@@ -629,6 +654,8 @@ async function check(args) {
     }
     console.log("\n" + markdown);
     console.log(`Wrote report.md, check.sarif and check.json to ${outDir}`);
+    if (result.replay)
+        console.log(`Wrote ${REPLAY_FILE} to ${outDir}, with ${replayFrames(result.replay).length} frame(s) and ${replayVideos(result.replay).length} journey video(s) beside it: open it in a browser to see each step`);
     const pictured = result.baselines?.results.filter((r) => r.files).length ?? 0;
     if (pictured > 0)
         console.log(`Wrote the pictures of ${pictured} changed baseline(s) under ${path.join(outDir, VISUAL_DIRNAME)}`);

package/dist/engine/browser.js

@@ -935,9 +935,13 @@ export class BrowserEngine {
             }
         }
         for (const found of findContradictions(requests, state, before, acted && actedNow ? { before: acted.before, after: actedNow } : null)) {
-            if (this.contradictionsReported.has(found.evidence))
+            // Once per refused request a session, except that a high reading of it
+            // replaces an earlier medium one (#413).
+            const severity = found.severity ?? "high";
+            const earlier = this.contradictionsReported.get(found.evidence);
+            if (earlier === "high" || earlier === severity)
                 continue;
-            this.contradictionsReported.add(found.evidence);
+            this.contradictionsReported.set(found.evidence, severity);
             this.oracles.noteContradiction(found, url);
         }
     }
@@ -974,7 +978,7 @@ export class BrowserEngine {
         }
     }
     /** Contradiction signatures already reported this session — the same refused endpoint on every page must not flood the run. */
-    contradictionsReported = new Set();
+    contradictionsReported = new Map();
     async scanForInjections() {
         const page = this.page;
         // One copy for the whole scan: the list is shared with every lane, and
@@ -1109,7 +1113,7 @@ export class BrowserEngine {
         this.blockNotices.reset();
         this.dialogsSeen = [];
         this.watchedResponses = [];
-        this.contradictionsReported = new Set();
+        this.contradictionsReported = new Map();
         this.tokenPostsReported = new Set();
         this.pendingCreations = new Set();
         this.baseUrl = opts.url.replace(/\/$/, "");
@@ -1180,6 +1184,7 @@ export class BrowserEngine {
                 viewport: opts.viewport ?? { width: 1280, height: 900 },
                 ...(opts.deviceScaleFactor !== undefined ? { deviceScaleFactor: opts.deviceScaleFactor } : {}),
                 serviceWorkers: serviceWorkerPolicy(this.engineName),
+                ...(opts.videoDir ? { recordVideo: { dir: opts.videoDir } } : {}),
             });
             const restoreSession = sessionStorageInitScript(profile?.sessionStorage ?? []);
             if (restoreSession)
@@ -1505,6 +1510,9 @@ export class BrowserEngine {
         // oracles attached); close foreign-origin popups so exploration cannot
         // silently escape the app under test.
         this.context.on("page", (newPage) => {
+            // A page the engine opened for itself (onOwnPage) is not a popup to adopt or close.
+            if (this.openingOwnPage)
+                return;
             newPage
                 .waitForLoadState("domcontentloaded", { timeout: this.limits.backNavMs })
                 .then(() => {
@@ -1667,6 +1675,66 @@ export class BrowserEngine {
     nativeDialogAt = 0;
     /** When a native dialog that asks something (confirm, prompt, a leave confirmation) last opened; an alert only tells. */
     nativeQuestionAt = 0;
+    /** True while onOwnPage opens its page, so the popup handler leaves it alone. */
+    openingOwnPage = false;
+    /** Open a page in this session's context and drive it from now on, wired as attach wires its first page. */
+    async driveNewPage() {
+        const context = this.context;
+        if (!context)
+            throw new Error("Not attached. Call scout_attach first with the app URL and project path.");
+        this.openingOwnPage = true;
+        let page;
+        try {
+            page = await context.newPage();
+        }
+        finally {
+            this.openingOwnPage = false;
+        }
+        this.oracles.attach(page);
+        this.wireDialogHandler(page);
+        this.wireEmbedMoves(page);
+        this.page = page;
+        this.refs.clear();
+        this.snapshotUrl = "";
+        this.forgetSnapshots();
+        return page;
+    }
+    /**
+     * Run `work` on a page of its own in this session's context, then close it.
+     * The context is the session's, so its cookies and storage carry over; on a
+     * session attached with `videoDir`, the page's video is this run's alone,
+     * and is saved to `videoTo`. Every page the work left open is closed with
+     * it, and a fresh page is driven afterwards. The video is null when the
+     * session records none or it could not be saved (`videoError` says why).
+     */
+    async onOwnPage(work, videoTo) {
+        const own = await this.driveNewPage();
+        let value;
+        try {
+            value = await work();
+        }
+        finally {
+            const context = this.context;
+            // The work may have adopted a popup, or been left on its own page: everything open now is the work's.
+            if (context)
+                await BrowserEngine.settleWithin(Promise.allSettled(context.pages().map((p) => p.close().catch(() => { }))), 10_000);
+            this.page = null;
+            if (context)
+                await this.driveNewPage();
+        }
+        const recording = own.video();
+        if (!recording || !videoTo)
+            return { value, video: null };
+        try {
+            await fs.promises.mkdir(path.dirname(videoTo), { recursive: true });
+            // saveAs waits until the page is closed and the video written.
+            await recording.saveAs(videoTo);
+            return { value, video: videoTo };
+        }
+        catch (err) {
+            return { value, video: null, videoError: err instanceof Error ? err.message.split("\n")[0] : String(err) };
+        }
+    }
     requirePage() {
         if (!this.page || !this.memory) {
             throw new Error("Not attached. Call scout_attach first with the app URL and project path.");
@@ -5081,7 +5149,15 @@ export class BrowserEngine {
                     refusedBackground.push(sig);
             return charged;
         };
-        const done = (outcome) => ({ outcome, violations, refusedBackground, websockets: [...websockets] });
+        /** On a recorded session, the frame after each step that ran (null where none was kept), for the check's replay page. */
+        const frames = [];
+        const done = (outcome) => ({
+            outcome,
+            violations,
+            refusedBackground,
+            websockets: [...websockets],
+            ...(this.recording ? { frames } : {}),
+        });
         // Nothing from the crawl before this flow is charged to it.
         this.oracles.drain(false);
         this.blockedRequests = [];
@@ -5265,6 +5341,9 @@ export class BrowserEngine {
                 const n = i + 1;
                 const did = describeStep(step);
                 const { failure, refusal } = step.action === "repeat" ? await runRepeat(step) : await runStep(step);
+                // Taken whatever the step's result: the frame of a step that broke is the evidence of how it broke.
+                if (this.recording)
+                    frames.push((await this.recordFrame(`flow-${step.action}`)) ?? null);
                 if (refusal)
                     return done({ status: "refused", step: n, did, reason: refusal.split("\n")[0], path: here() });
                 if (failure)

package/dist/engine/check-replay.js

@@ -0,0 +1,287 @@
+/**
+ * The replay page of a recorded `scenescout check` (`--record`): what each
+ * role did, journey by journey and step by step, with the frame the page
+ * showed after each step, so a green run leaves evidence of what passed and a
+ * red one shows where it broke.
+ *
+ * A journey is a saved flow (flow.ts); a role is the session it ran in, the
+ * check's own or the one its `role` names. The check's own session also lists
+ * the routes it visited, one frame each.
+ *
+ * Everything here is pure: the mapping of steps to captions and results, the
+ * frame cap, the redaction and the page itself are table-tested. check-run.ts
+ * gathers the frames from the browser and copies them beside the page.
+ */
+import { redactRoute } from "./memory.js";
+import { describeStep } from "./flow.js";
+import { escapeHtml, plainSegment, RECORD_MAX_FRAMES } from "./replay.js";
+/** The file the page is written to, beside report.md. */
+export const REPLAY_FILE = "replay.html";
+/** The folder beside it that holds the frames the page shows. */
+export const REPLAY_FRAMES_DIRNAME = "replay-frames";
+/** The folder beside it that holds one video per journey (--video). */
+export const REPLAY_VIDEOS_DIRNAME = "replay-videos";
+/**
+ * Each step of a replayed flow with its caption, its result and its frame.
+ * The replay stops at the first step that breaks, so every step before it
+ * passed, it is the failing one, and those after it never ran (and have no
+ * frame). `frames` holds one entry per executed step, null where none was kept.
+ */
+export function journeySteps(steps, outcome, frames = []) {
+    const broke = outcome.status === "passed" ? null : outcome.step;
+    return steps.map((step, i) => {
+        const n = i + 1;
+        const frame = broke === null || n <= broke ? (frames[i] ?? undefined) : undefined;
+        const base = { n, caption: describeStep(step), ...(frame ? { frame } : {}) };
+        if (broke === null || n < broke)
+            return { ...base, result: "passed" };
+        if (n > broke)
+            return { n, caption: base.caption, result: "not-run" };
+        // `broke` is set only when the outcome is not "passed".
+        const failed = outcome;
+        return { ...base, result: failed.status, reason: failed.reason, path: failed.path };
+    });
+}
+/** One journey of the page, from a flow and how its replay went. */
+export function journeyOf(flow, outcome, frames) {
+    return {
+        name: flow.name,
+        file: flow.file,
+        status: outcome.status,
+        steps: journeySteps(flow.steps, outcome, frames),
+        ...(outcome.status === "passed" ? {} : { firstFailing: outcome.step }),
+    };
+}
+/** One visited route, from what the crawl measured. */
+export function visitOf(route, frame) {
+    const result = route.loadError !== undefined ? "not-loaded" : route.loginRedirect ? "sign-in" : route.status !== null && route.status >= 400 ? "http-error" : "loaded";
+    return {
+        path: route.path,
+        status: route.status,
+        result,
+        ...(route.loadError !== undefined ? { reason: route.loadError } : {}),
+        ...(frame ? { frame } : {}),
+    };
+}
+/**
+ * At most `max` frames per role, the first ones kept: the same cap a recorded
+ * session keeps (RECORD_MAX_FRAMES), held here too so the page never shows
+ * more than the run was allowed to take, whatever it is handed.
+ */
+export function capFrames(replay, max = RECORD_MAX_FRAMES) {
+    let leftOut = replay.framesLeftOut;
+    const roles = replay.roles.map((role) => {
+        let kept = 0;
+        const take = (item) => {
+            if (!item.frame)
+                return item;
+            if (kept < max) {
+                kept += 1;
+                return item;
+            }
+            leftOut += 1;
+            const { frame: _dropped, ...rest } = item;
+            return rest;
+        };
+        return {
+            ...role,
+            visits: role.visits.map(take),
+            journeys: role.journeys.map((j) => ({ ...j, steps: j.steps.map(take) })),
+        };
+    });
+    return { ...replay, roles, framesLeftOut: leftOut };
+}
+/** The report's redaction (memory.ts redactRoute) on every path, caption and reason the page shows. */
+export function redactReplay(replay) {
+    return {
+        ...replay,
+        roles: replay.roles.map((role) => ({
+            ...role,
+            visits: role.visits.map((v) => ({ ...v, path: redactRoute(v.path), ...(v.reason !== undefined ? { reason: redactRoute(v.reason) } : {}) })),
+            journeys: role.journeys.map((j) => ({
+                ...j,
+                steps: j.steps.map((s) => ({
+                    ...s,
+                    caption: redactRoute(s.caption),
+                    ...(s.reason !== undefined ? { reason: redactRoute(s.reason) } : {}),
+                    ...(s.path !== undefined ? { path: redactRoute(s.path) } : {}),
+                })),
+            })),
+        })),
+    };
+}
+/**
+ * Where the video of the n-th journey run (1-based) goes beside the page. The
+ * flow's file name is reduced to a plain segment, so it decides nothing about
+ * where the file is written; the number keeps two flows' videos apart.
+ */
+export function journeyVideoPath(n, file) {
+    return `${REPLAY_VIDEOS_DIRNAME}/journey-${String(n).padStart(2, "0")}-${plainSegment(file.replace(/\.json$/i, ""), "flow")}.webm`;
+}
+/** Whether a file under replay-videos/ is a video a check wrote, and so one an earlier run's clean-up may remove. */
+export function isJourneyVideoFile(name) {
+    return /^journey-\d{2,}-[a-z0-9._-]+\.webm$/i.test(name);
+}
+/** Every journey video the page links, in page order. */
+export function replayVideos(replay) {
+    return replay.roles.flatMap((r) => r.journeys.flatMap((j) => (j.video ? [j.video] : [])));
+}
+/** Every frame the page shows, in page order. */
+export function replayFrames(replay) {
+    return replay.roles.flatMap((r) => [
+        ...r.visits.flatMap((v) => (v.frame ? [v.frame] : [])),
+        ...r.journeys.flatMap((j) => j.steps.flatMap((s) => (s.frame ? [s.frame] : []))),
+    ]);
+}
+const RECORDED_FRAME = /^recordings\/([a-z0-9._-]+)\/(\d{4}-[a-z0-9._-]+\.jpg)$/i;
+/**
+ * Where a frame a session recorded (replay.ts framePath) goes beside the
+ * page, or null for anything that is not one: the path is used to write a
+ * file, so nothing else is let through.
+ */
+export function replayFramePath(recorded) {
+    const m = RECORDED_FRAME.exec(recorded);
+    return m ? `${REPLAY_FRAMES_DIRNAME}/${m[1]}/${m[2]}` : null;
+}
+/** Whether a file in a session folder under replay-frames/ is a frame a check wrote, and so one an earlier run's clean-up may remove. */
+export function isReplayFrameFile(name) {
+    return /^\d{4}-[a-z0-9._-]+\.jpg$/i.test(name);
+}
+/** The session name a check's own browser records its frames under, and one for each role's. Distinct, so their frames never share a folder. */
+export function replaySessionKey(role) {
+    return role === undefined ? "check" : `role-${plainSegment(role, "role")}`;
+}
+/** A commit to name in the page's header: GITHUB_SHA when it is one, else none. */
+export function commitOf(env) {
+    const sha = (env.GITHUB_SHA ?? "").trim();
+    return /^[0-9a-f]{7,64}$/i.test(sha) ? sha.toLowerCase() : undefined;
+}
+const RESULT_WORD = { passed: "passed", failed: "failed", refused: "refused", "not-run": "not run" };
+const VISIT_WORD = {
+    loaded: "loaded",
+    "http-error": "HTTP error",
+    "sign-in": "sent to sign-in",
+    "not-loaded": "did not load",
+};
+/** A UTC time as the page shows it: the reader's own clock is not this page's to assume. */
+function stamp(iso) {
+    return iso.length >= 19 ? `${iso.slice(0, 10)} ${iso.slice(11, 19)} UTC` : iso;
+}
+const GONE = `onerror="this.parentNode.classList.add('gone')"`;
+function frameHtml(frame, alt) {
+    if (!frame)
+        return `<p class="noframe">No frame</p>`;
+    const src = escapeHtml(frame);
+    return (`<a class="frame" href="${src}" target="_blank" rel="noreferrer" data-testid="replay-frame-open"><img loading="lazy" ${GONE} src="${src}" alt="${escapeHtml(alt)}">` +
+        `<span class="gone-note">This frame is not beside this file. Frames live in the <code>${REPLAY_FRAMES_DIRNAME}/</code> folder, which travels with it.</span></a>`);
+}
+function stepHtml(s, anchor) {
+    const first = s.result === "failed" || s.result === "refused";
+    const detail = [s.reason, s.path ? `on ${s.path}` : ""].filter(Boolean).join(" ");
+    return (`<li class="step ${s.result}${first ? " first-failing" : ""}"${first ? ` id="${anchor}"` : ""} data-result="${s.result}">` +
+        `<div class="caption"><span class="n">${s.n}</span> <span class="what">${escapeHtml(s.caption)}</span> <span class="result r-${s.result}">${RESULT_WORD[s.result]}</span></div>` +
+        (detail ? `<p class="why">${escapeHtml(detail)}</p>` : "") +
+        (s.result === "not-run" ? "" : frameHtml(s.frame, `The page after step ${s.n}: ${s.caption}`)) +
+        `</li>`);
+}
+function journeyHtml(j, id) {
+    const ok = j.status === "passed";
+    const anchor = `${id}-first-failing`;
+    const badge = ok ? `<span class="badge pass">passed</span>` : `<span class="badge fail">${j.status}</span>`;
+    const jump = j.firstFailing !== undefined
+        ? `<a class="jump" href="#${anchor}" data-testid="replay-first-failing-link">Step ${j.firstFailing} ${j.status}</a>`
+        : `<span class="count">${j.steps.length} step${j.steps.length === 1 ? "" : "s"}</span>`;
+    return (`<details class="journey ${ok ? "pass" : "fail"}"${ok ? "" : " open"} data-status="${j.status}"><summary data-testid="replay-journey-toggle">${badge} <b>${escapeHtml(j.name)}</b> <span class="file">${escapeHtml(j.file)}</span> ${jump}</summary>` +
+        (j.video
+            ? `<figure class="video"><video controls preload="metadata" src="${escapeHtml(j.video)}" data-testid="replay-journey-video"></video>` +
+                `<figcaption>The whole journey as it ran. <a href="${escapeHtml(j.video)}" target="_blank" rel="noreferrer" data-testid="replay-video-open">Open the video</a></figcaption></figure>`
+            : "") +
+        `<ol class="steps">${j.steps.map((s) => stepHtml(s, anchor)).join("")}</ol></details>`);
+}
+function visitsHtml(visits) {
+    if (visits.length === 0)
+        return "";
+    const items = visits
+        .map((v) => `<li class="visit ${v.result}"><div class="caption"><span class="what">visit ${escapeHtml(v.path)}</span> <span class="result v-${v.result}">${v.status ?? "—"} · ${VISIT_WORD[v.result]}</span></div>` +
+        (v.reason ? `<p class="why">${escapeHtml(v.reason)}</p>` : "") +
+        frameHtml(v.frame, `The page at ${v.path}`) +
+        `</li>`)
+        .join("");
+    return `<details class="visits"><summary data-testid="replay-visits-toggle">Routes visited <span class="count">${visits.length}</span></summary><ol class="steps">${items}</ol></details>`;
+}
+function roleHtml(r, i) {
+    const failing = r.journeys.filter((j) => j.status !== "passed").length;
+    const tally = `${r.journeys.length} journey${r.journeys.length === 1 ? "" : "s"}${failing ? `, ${failing} not passed` : ""}`;
+    return (`<section class="role" id="role-${i}"><h2>${escapeHtml(r.role)} <span class="count">${r.own ? "the check's own session · " : ""}${tally}</span></h2>` +
+        visitsHtml(r.visits) +
+        (r.journeys.length > 0 ? r.journeys.map((j, k) => journeyHtml(j, `role-${i}-journey-${k}`)).join("") : `<p class="none">No journey ran as this role.</p>`) +
+        `</section>`);
+}
+const STYLE = `
+:root { color-scheme: light dark; --bg:#f6f7f9; --panel:#fff; --line:#d9dde3; --text:#15181d; --muted:#5d6673; --accent:#2563eb; --pass:#047857; --pass-bg:#d1fae5; --fail:#b91c1c; --fail-bg:#fee2e2; }
+@media (prefers-color-scheme: dark) { :root { --bg:#0e1116; --panel:#161a21; --line:#2a303a; --text:#e6e9ee; --muted:#98a2b3; --accent:#7aa2ff; --pass:#6ee7b7; --pass-bg:#063b2c; --fail:#fca5a5; --fail-bg:#3f1010; } }
+* { box-sizing:border-box; }
+body { margin:0; background:var(--bg); color:var(--text); font:15px/1.55 system-ui,-apple-system,"Segoe UI",sans-serif; }
+header { padding:14px 20px; background:var(--panel); border-bottom:1px solid var(--line); }
+header h1 { margin:0 0 4px; font-size:18px; display:flex; gap:10px; align-items:center; flex-wrap:wrap; }
+header dl { display:flex; flex-wrap:wrap; gap:4px 18px; margin:0; font-size:13px; color:var(--muted); }
+header dt { font-weight:600; } header dd { margin:0 0 0 4px; overflow-wrap:anywhere; }
+header .pair { display:flex; }
+main { max-width:1000px; margin:0 auto; padding:20px 16px 64px; }
+h2 { font-size:19px; margin:28px 0 10px; }
+.count, .file { color:var(--muted); font-size:13px; font-weight:400; }
+.badge { display:inline-block; padding:1px 8px; border-radius:999px; font-size:12px; font-weight:700; text-transform:uppercase; letter-spacing:.03em; }
+.badge.pass { color:var(--pass); background:var(--pass-bg); } .badge.fail { color:var(--fail); background:var(--fail-bg); }
+details.journey, details.visits { background:var(--panel); border:1px solid var(--line); border-radius:8px; margin:10px 0; padding:10px 14px; }
+details.journey.fail { border-color:var(--fail); }
+summary { cursor:pointer; }
+.jump { color:var(--fail); font-size:13px; margin-left:6px; }
+ol.steps { list-style:none; margin:10px 0 0; padding:0; }
+.step, .visit { border-left:3px solid var(--line); padding:6px 10px; margin:0 0 10px; }
+.step.passed, .visit.loaded { border-color:var(--pass); }
+.step.failed, .step.refused, .visit.http-error, .visit.not-loaded, .visit.sign-in { border-color:var(--fail); }
+.step.first-failing { background:var(--fail-bg); border-left-width:6px; }
+.step.not-run { opacity:.6; }
+.caption { display:flex; flex-wrap:wrap; gap:6px 10px; align-items:baseline; }
+.caption .n { font-weight:700; color:var(--muted); min-width:1.5em; }
+.caption .what { font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
+.result { margin-left:auto; font-size:12px; font-weight:700; }
+.r-passed, .v-loaded { color:var(--pass); } .r-failed, .r-refused, .v-http-error, .v-not-loaded, .v-sign-in { color:var(--fail); } .r-not-run { color:var(--muted); }
+.why { margin:4px 0; font-size:13px; overflow-wrap:anywhere; }
+a.frame { display:block; margin:6px 0 2px; max-width:min(100%,720px); }
+a.frame img { max-width:100%; max-height:400px; object-fit:cover; object-position:top; border:1px solid var(--line); border-radius:6px; display:block; }
+.gone-note { display:none; padding:12px; border:1px dashed var(--line); border-radius:6px; color:var(--muted); font-size:12px; }
+a.frame.gone img { display:none; } a.frame.gone .gone-note { display:block; }
+.noframe, .none { color:var(--muted); font-size:12px; font-style:italic; margin:4px 0; }
+.note { color:var(--muted); font-size:13px; }
+figure.video { margin:10px 0; max-width:min(100%,720px); }
+figure.video video { width:100%; border:1px solid var(--line); border-radius:6px; display:block; background:#000; }
+figure.video figcaption { color:var(--muted); font-size:12px; margin-top:4px; }
+`;
+/** The whole page: one HTML file with no external assets or scripts; its frames sit beside it in replay-frames/. */
+export function buildCheckReplayHtml(replay, meta) {
+    const verdict = meta.couldNotRun > 0 ? "could not run every flow" : meta.passed ? "passed" : "failed";
+    const badge = `<span class="badge ${meta.passed && meta.couldNotRun === 0 ? "pass" : "fail"}" data-testid="replay-verdict">${verdict}</span>`;
+    const pair = (term, value) => `<div class="pair"><dt>${term}</dt><dd>${escapeHtml(value)}</dd></div>`;
+    const frames = replayFrames(replay).length;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SceneScout check replay — ${escapeHtml(meta.origin)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header>
+  <h1>SceneScout check replay ${badge}</h1>
+  <dl>${pair("App", meta.origin)}${pair("Started", stamp(meta.startedAt))}${pair("Ended", stamp(meta.endedAt))}${meta.commit ? pair("Commit", meta.commit) : ""}${pair("SceneScout", `v${meta.version}`)}${pair("Frames", String(frames))}${replayVideos(replay).length > 0 ? pair("Videos", String(replayVideos(replay).length)) : ""}</dl>
+</header>
+<main>
+<p class="note">Each role, then each journey it walked, step by step, with the page as it was after the step${frames === 0 ? " when the check was recorded (--record)" : ""}. Typed values are never shown, and secrets in addresses are redacted as in the report.${replay.framesLeftOut > 0 ? ` ${replay.framesLeftOut} frame(s) past the cap of ${RECORD_MAX_FRAMES} per role are not kept; those steps show no frame.` : ""}</p>
+${replay.roles.map(roleHtml).join("\n") || '<p class="none">Nothing was recorded.</p>'}
+</main>
+</body>
+</html>
+`;
+}

package/dist/engine/check.js

@@ -169,6 +169,14 @@ function stripRefs(line) {
 function withoutOrigin(text, origin) {
     return origin ? text.split(origin).join("") : text;
 }
+/**
+ * A violation's own severity where it is lower than its rule's: a refused read
+ * beside an empty state that may be about another section is medium (#413).
+ * Every other violation takes its rule's severity.
+ */
+function violationSeverity(v) {
+    return v.kind === "refused_empty" && v.severity === "medium" ? "medium" : undefined;
+}
 function violationRule(v) {
     switch (v.kind) {
         case "page_error":
@@ -309,7 +317,7 @@ export function checkFindings(routes, origin, ignore = [], flows = [], baselines
         else if (r.elements === 0 && (r.status === null || r.status < 400))
             add("dead-end", `${route}: 0 controls`, route);
         for (const v of r.violations)
-            add(violationRule(v), v.detail, route, { embed: v.embed });
+            add(violationRule(v), v.detail, route, { embed: v.embed, severity: violationSeverity(v) });
         for (const line of r.geometry) {
             const rule = geometryRule(line);
             if (rule)
@@ -327,7 +335,7 @@ export function checkFindings(routes, origin, ignore = [], flows = [], baselines
     }
     for (const f of flows) {
         for (const { path, violation } of f.violations)
-            add(violationRule(violation), violation.detail, path, { embed: violation.embed, flow: f.file });
+            add(violationRule(violation), violation.detail, path, { embed: violation.embed, flow: f.file, severity: violationSeverity(violation) });
         // A refused step is not the app's defect: the check reports it as "could not run" (refusedFlowReason).
         if (f.outcome.status === "failed")
             add("flow-step-failed", flowStepEvidence(f), f.outcome.path, { flow: f.file });
@@ -493,7 +501,13 @@ export const CHECK_OPTION_NAMES = [
     "baselines",
     "baseline-threshold",
     "sarif-file-anchor",
+    "record",
+    "video",
 ];
+/** Options that may be given alone, meaning on: `--record`, as well as `--record on` and `--record=off`. */
+const SWITCH_OPTIONS = new Set(["record", "video"]);
+const SWITCH_ON = ["on", "true", "1"];
+const SWITCH_OFF = ["off", "false", "0"];
 export const MAX_CHECK_ROUTES = 150;
 /** Link discovery rounds: each crawl reveals the routes its pages link to. Past a few, a site is paginating rather than revealing. */
 export const MAX_DISCOVERY_ROUNDS = 6;
@@ -514,6 +528,14 @@ export function parseCheckArgs(args, cwd) {
         }
         const eq = a.indexOf("=");
         const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+        // A switch takes the next argument only when it is on or off: `--record http://…` records, and checks that URL.
+        if (eq < 0 && SWITCH_OPTIONS.has(name)) {
+            const next = args[i + 1]?.toLowerCase();
+            if (next !== undefined && [...SWITCH_ON, ...SWITCH_OFF].includes(next))
+                i += 1;
+            flags.set(name, next !== undefined && [...SWITCH_ON, ...SWITCH_OFF].includes(next) ? next : "on");
+            continue;
+        }
         const value = eq > 0 ? a.slice(eq + 1) : args[i + 1];
         if (value === undefined || (eq < 0 && value.startsWith("--")))
             return { ok: false, error: `--${name} needs a value` };
@@ -655,6 +677,14 @@ export function parseCheckArgs(args, cwd) {
     const anchor = flags.has("sarif-file-anchor") ? checkSarifAnchor(flags.get("sarif-file-anchor")) : undefined;
     if (anchor && !anchor.ok)
         return anchor;
+    const recordRaw = flags.get("record")?.trim().toLowerCase();
+    if (recordRaw !== undefined && !SWITCH_ON.includes(recordRaw) && !SWITCH_OFF.includes(recordRaw)) {
+        return { ok: false, error: "--record is on or off, or given alone for on" };
+    }
+    const videoRaw = flags.get("video")?.trim().toLowerCase();
+    if (videoRaw !== undefined && !SWITCH_ON.includes(videoRaw) && !SWITCH_OFF.includes(videoRaw)) {
+        return { ok: false, error: "--video is on or off, or given alone for on" };
+    }
     const resolve = (p) => resolveArgPath(cwd, p);
     return {
         ok: true,
@@ -681,6 +711,8 @@ export function parseCheckArgs(args, cwd) {
             ...(baselinesDir !== undefined ? { baselinesDir: resolve(baselinesDir) } : {}),
             baselineThreshold: threshold.value,
             ...(anchor ? { sarifFileAnchor: anchor.value } : {}),
+            ...(recordRaw !== undefined ? { record: SWITCH_ON.includes(recordRaw) } : {}),
+            ...(videoRaw !== undefined && SWITCH_ON.includes(videoRaw) ? { video: true } : {}),
         },
     };
 }

package/dist/engine/claims.js

@@ -145,6 +145,154 @@ export function classify(text) {
         return "empty";
     return null;
 }
+/**
+ * Words in an empty-state sentence that name nothing in particular: the
+ * generic nouns for "the things", the verbs that follow them ("No results
+ * found", "No entries recorded yet") and the adjectives in front of them ("No
+ * new items", "No matching records"). Stemmed, as `stem` leaves them.
+ */
+const GENERIC_EMPTY_WORDS = new Set([
+    "result",
+    "item",
+    "record",
+    "row",
+    "data",
+    "entry",
+    "match",
+    "thing",
+    "one",
+    "yet",
+    "found",
+    "show",
+    "display",
+    "here",
+    "recorded",
+    "added",
+    "created",
+    "saved",
+    "available",
+    "been",
+    "matching",
+    "more",
+    "new",
+    "recent",
+    "upcoming",
+    "open",
+    "pending",
+    "other",
+    "further",
+    "api",
+    "v1",
+    "v2",
+    "v3",
+]);
+/** Words that end the subject of an empty-state sentence: "No results | for your search". */
+const SUBJECT_STOP_WORDS = new Set([
+    "for",
+    "your",
+    "you",
+    "to",
+    "in",
+    "on",
+    "of",
+    "at",
+    "by",
+    "with",
+    "that",
+    "this",
+    "which",
+    "from",
+    "match",
+    "matches",
+    "yet",
+    "found",
+    "here",
+    "available",
+    "left",
+    "anymore",
+    "have",
+    "has",
+    "had",
+    "been",
+    "was",
+    "were",
+    "is",
+    "are",
+    "such",
+]);
+/** Crude singular form, enough to match "comments" to "/comment/" and "entries" to "/entry". */
+function stem(word) {
+    const w = word.toLowerCase();
+    if (w.endsWith("ies") && w.length > 4)
+        return `${w.slice(0, -3)}y`;
+    if (w.endsWith("yses"))
+        return `${w.slice(0, -4)}ysis`;
+    if (w.endsWith("uses"))
+        return w.slice(0, -2);
+    if (w.endsWith("es") && /(?:ss|x|ch|sh)es$/.test(w))
+        return w.slice(0, -2);
+    if (w.endsWith("s") && !/(?:ss|us|is)$/.test(w) && w.length > 3)
+        return w.slice(0, -1);
+    return w;
+}
+/** A word or a path segment as stems, split on hyphens and underscores the same way on both sides. */
+function stems(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean)
+        .map(stem);
+}
+/**
+ * The words naming what an empty-state sentence says is missing: "comment"
+ * for "No comments yet", "corrective action" for "No corrective actions
+ * recorded yet", "order" for "There are no orders". Empty for sentences that
+ * name nothing in particular ("No results for your search", "Nothing to show",
+ * "This list is empty"). Read from where the empty-state phrase starts, so a
+ * "no" earlier in the text ("No longer available. No results.") is not taken.
+ */
+export function emptyStateSubject(text) {
+    const at = EMPTY_RE.exec(text)?.index ?? 0;
+    const m = /\bno\s+((?:[a-z][a-z-]*\s+){0,3}[a-z][a-z-]*)/i.exec(text.slice(at));
+    if (!m)
+        return [];
+    const words = [];
+    for (const word of m[1].split(/\s+/)) {
+        if (SUBJECT_STOP_WORDS.has(word.toLowerCase()))
+            break;
+        words.push(...stems(word));
+    }
+    return words.filter((w) => w.length > 2 && !GENERIC_EMPTY_WORDS.has(w));
+}
+/** Whether a request's path names one of these subject words. */
+function pathNames(req, subject) {
+    let path;
+    try {
+        path = new URL(req.url).pathname;
+    }
+    catch {
+        path = req.url;
+    }
+    const segments = new Set(stems(path));
+    return subject.some((w) => segments.has(w));
+}
+/**
+ * Pairs one empty-state sentence with the refused reads it could be about.
+ * `loaded` are the page's reads that succeeded: positive evidence that a
+ * sentence naming what they fetched is a genuinely empty section rather than
+ * a refusal hidden behind an empty state.
+ */
+export function pairEmptyState(text, refusedReads, loaded) {
+    const subject = emptyStateSubject(text);
+    if (subject.length === 0)
+        return { certain: true, read: refusedReads[0] };
+    const named = refusedReads.find((r) => pathNames(r, subject));
+    if (named)
+        return { certain: true, read: named };
+    if (loaded.some((r) => pathNames(r, subject)))
+        return { unrelated: true };
+    return { certain: false, read: refusedReads[0], subject };
+}
 /** What counts as an open dialog: a native one or an ARIA one. */
 const DIALOG_SEL = 'dialog[open], [role="dialog"], [role="alertdialog"]';
 /** Page-side count of the open dialogs alone, for a caller that needs nothing else the claim scan reads. */
@@ -211,17 +359,40 @@ export function findContradictions(requests, page, before, acted) {
         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.` +
-                standIn(worst),
-            evidence: `refused-empty ${say(worst)}`,
-        });
+    if (reads.length > 0) {
+        // An empty-state sentence that names what is missing is evidence about
+        // requests for that thing (#413). "No comments yet" beside a refused
+        // history read, with the comments read loaded fine, is a genuinely empty
+        // comments section, not a refusal shown as an empty state.
+        // Positive evidence only: a data read the page made that succeeded. The
+        // page's own document, its images and scripts, and redirects say nothing
+        // about which section of it is empty.
+        const loaded = requests.filter((r) => (r.resourceType === "xhr" || r.resourceType === "fetch") &&
+            r.status !== null &&
+            r.status >= 200 &&
+            r.status < 300 &&
+            !WRITING_METHODS.has(r.method.toUpperCase()));
+        const pairings = page.texts.filter((_, i) => claims[i] === "empty").map((t) => ({ text: t, pairing: pairEmptyState(t, reads, loaded) }));
+        // A sentence naming what a refused read fetched points at that read; a generic one points at none in particular.
+        const certain = pairings.find((p) => "certain" in p.pairing && p.pairing.certain && emptyStateSubject(p.text).length > 0) ??
+            pairings.find((p) => "certain" in p.pairing && p.pairing.certain);
+        const possible = pairings.find((p) => "certain" in p.pairing && !p.pairing.certain);
+        const hit = certain ?? (page.emptyLists > 0 ? undefined : possible);
+        if (hit || page.emptyLists > 0) {
+            const read = hit && "read" in hit.pairing ? hit.pairing.read : reads[0];
+            const how = hit ? "an empty state" : `an empty list (${page.emptyLists})`;
+            const unsure = hit !== undefined && hit === possible;
+            out.push({
+                kind: "refused_empty",
+                detail: `${say(read)} was refused, and the page shows ${how} with no error. ` +
+                    (unsure
+                        ? `The empty state ("${hit.text}") names something no request on the page was for, so it may be about another section; the user may be told there is nothing to see when nothing could be loaded.`
+                        : `The user is told there is nothing to see when the truth is that nothing could be loaded.`) +
+                    standIn(read),
+                evidence: `refused-empty ${say(read)}`,
+                ...(unsure ? { severity: "medium" } : {}),
+            });
+        }
     }
     // Only writes this action sent, and not the page's own infrastructure.
     const isActionWrite = (r) => WRITING_METHODS.has(r.method.toUpperCase()) && !r.background && !INFRASTRUCTURE_WRITE_RE.test(r.url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.19.1",
+  "version": "3.20.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",