scenescout 3.9.0 → 3.11.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # scenescout
 
+## 3.11.0
+
+### Minor Changes
+
+- f61141e: `scenescout check` replays saved flows and re-tests open findings. Flows saved as `.scenescout/flows/*.json` use `scout_run_plan`'s steps (navigate, click, type, select, press) plus `expect-text`, `expect-url` and `expect-request`; each is replayed after the crawl with no model, and a flow whose step breaks fails the gate with a high `flow-step-failed` issue naming the flow and the step. A flow file that is not valid stops the check with exit 2, naming the file and the field. Open findings in the project's memory that a page load can reproduce (a failed GET, nothing done on the page but looking) are re-tested and reported as still reproducing or possibly fixed; the memory is never written. New options, also inputs of the GitHub Action: `--flows <dir|off>`, `--retest on|off`, and three settings for what a check may do, whose effective values are printed under the verdict and in `check.json`: `--flow-writes never|allow` (default `never`: flows replay under observe's rule whatever `--mode` says; `allow` replays them under `--mode`, so their form submissions are sent), `--on-refused-step report|stop` (default `report`: a flow whose step was refused is marked "could not run" in the report, JSON and SARIF, every other verdict is kept, and the check exits 2; `stop` exits 2 at once with no results) and `--gate-retests never|high|all` (default `high`: a re-tested finding filed high that still reproduces fails the gate). The defaults are what an unconfigured check does, for a first try or an agent running it unattended: its flows send no HTTP write and it never silently hides a result. A refused beacon or ping (`navigator.sendBeacon`, `<a ping>`) is listed in the flow's result as a background request and charged to no step, whatever its origin, while every other refused write (fetch, XHR, form post) is charged to its step wherever it goes; a write the last step sets off within 750 ms is still charged to it; the WebSocket connections a flow's page opened are listed; a `role=` target must name an ARIA role; anything else in the flows directory is listed as skipped with its reason. Pages loaded only to re-test a finding are measured and nothing else: they are not checked routes, do not count towards `--max-routes`, and add nothing to the route list. The GitHub Action also outputs `could-not-run` and `retests-failing`, and its annotation says when re-tested findings are among what failed the gate. `scout_run_plan` targets accept `role=<role>[name="…"]`, and the `.gitignore` SceneScout writes in `.scenescout/` no longer ignores `flows/*.json`, so flows can be committed.
+
+### Patch Changes
+
+- a1f8011: The benchmark has a second, held-out app (`npm run holdout:serve`), a library loans desk with its own planted defects and answer key, which nothing in the engine or the skill is tuned against. `npm run bench` takes `--app demo|holdout` to choose the key a run is scored with (the demo stays the default), records the app in every new archive, refuses to score an archive against another app's key, and `--all` scores each archive against its own app's key, one table per app.
+
+## 3.10.0
+
+### Minor Changes
+
+- 8901a03: `scenescout check` is now a GitHub Action: `uses: brunoboto96/SceneScout@v3.10.0` (or the release you are on) with a `url` installs SceneScout and the browser (cached between runs), runs the check, puts the report on the job summary, keeps `report.md`, `check.json` and `check.sarif` as an artifact, and can upload the SARIF to code scanning (`upload-sarif: true`, which needs `security-events: write`). Its inputs are the CLI's options by name, its outputs are the verdict and the counts by severity, and the step fails with the CLI's exit code: 1 when the gate fails, 2 with a "could not run" annotation when there is no verdict. `docs/ci.md` has a complete workflow and the same check on GitLab CI, CircleCI and plain shell. Each release also points the major tag (`v3`) at itself where the repository settings allow it.
+- 9b98a50: New `scenescout check <url>`: a deterministic sweep that needs no model, so it can gate a pull request. It visits the start page, the project's scanned routes and every same-origin link it finds, and measures each one: HTTP and page errors, layout geometry (covered, clipped and overlapping controls, blocking overlays), broken images, controls with no name, contrast, focus indicators and pages with no way out. It writes `report.md`, `check.sarif` and `check.json`, adds the report to the GitHub Actions job summary, and exits 0 on a pass, 1 when the gate fails (`--fail-on high` by default) and 2 when it could not run. It never writes to the app.
+- ccf5802: `scout_coverage` lists the forms seen this run that no session has submitted empty: a `<form>` with a native submit control (a button linked by `form="id"` included) and at least one text field, until a click on that submit control, or Enter in one of its text inputs, goes while every text field is blank. A form is known by its `id`, else its `name`, else its `action` and method, and only when it has none of those by its submit control. Forms with no text field (only checkboxes, radios or selects), search boxes, forms whose submit is disabled while they are blank, and fields with no `<form>` around them are not listed. The gap ledger is unchanged: like the dropdown options, this is a coverage prompt, not a gate on `extensive`.
+
+### Patch Changes
+
+- 4f883c7: The console line Chromium and WebKit print for a failed load ("Failed to load resource: …") now goes where its request went: when another site's frame sent the request outside the app, the line is attributed to that embed at medium severity, instead of being filed as a high-severity console error of the app. The same line for a request the app sent stays the app's, other console and page errors are still not attributed by frame, and Firefox prints no such line.
+- 8b18c82: `scout_close` no longer closes a lane of a parallel run whose report has not been accepted yet, since folding the report needs the lane's session attached. A session counts as a lane once `scout_lane_brief` or `scout_lane_report` has named it (a brief lane sharing the name of a session already live does not count), until the run's last session closes; a refused report does not count as folded. The refusal says to fold the lane with `scout_lane_report`, and `scout_close {all: true}` names every such lane, offers the other sessions to close by name, and closes nothing. Pass `force: true` to close anyway, which loses that lane's decisions. A session no lane tool has named closes as before.
+- 42f6a55: `scout_lane_report` decodes the HTML character references a relay adds when it escapes a lane's reply (`&lt;`, `&gt;`, `&amp;`, `&quot;`, `&#39;`, `&apos;` and numeric ones), once, in every string of the report, so evidence such as `-&gt;` matches the finding filed as `->` again. A reply that holds a literal `<` or `>` was not escaped on the way and is left as it is, so a lane reporting a page that double-escapes its text keeps its evidence. Length caps apply to the decoded text, so a route that only went over its cap by being escaped is no longer refused, and the fold says how many references it decoded.
+- d487207: A text field whose only label is its placeholder is no longer treated as labelled. The snapshot still shows the placeholder as the field's name and now flags it `no label: placeholder only`, the crawl counts it as unnamed, and `scenescout check` files it under a new medium rule, `placeholder-only-label`. A field named by nothing but its `name` attribute or type is flagged `no label` and filed as `unnamed-control`. A `<label>` (by `for` or wrapping the field), `aria-label`, `aria-labelledby` or `title` counts as a label. Element keys in project memory are unchanged.
+
 ## 3.9.0
 
 ### Minor Changes

package/README.md

@@ -344,6 +344,60 @@ A `🛡 WRITE-POLICY blocked` notice is the safety net doing its job, not an app
 
 ---
 
+## 🚦 In CI: a deterministic check
+
+An exploratory run is driven by a model, so two runs never find exactly the same things. That suits a report, but not a gate. `scenescout check` is the part that needs no model. It visits the start URL, the project's scanned routes and every same-origin link it finds, and measures each page:
+
+- HTTP and page errors
+- layout geometry (covered, clipped and overlapping controls, blocking overlays)
+- broken images
+- controls with no name, and fields whose only label is a placeholder
+- contrast and focus
+- pages with no way out
+
+```bash
+npx scenescout check http://127.0.0.1:3000 --fail-on high
+```
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Passed the gate |
+| 1 | Failed it: something at the `--fail-on` severity or worse |
+| 2 | Could not run, or not all of it: a bad argument, an app that never answered, only the sign-in page reached, a saved flow that is not valid, or a flow step the write policy refused |
+
+It writes `report.md`, `check.sarif` (for code-scanning dashboards) and `check.json` to `.scenescout/check/`, and on GitHub Actions it also puts the report on the job's summary page.
+
+On GitHub Actions, this repository is also an action that installs everything and keeps the results:
+
+```yaml
+- uses: brunoboto96/SceneScout@v3.10.0
+  with:
+    url: http://127.0.0.1:3000
+```
+
+[docs/ci.md](docs/ci.md) has a complete workflow (start the app, wait for it, check it), the action's inputs and outputs, code-scanning upload, and the same check on GitLab CI, CircleCI or any shell.
+
+With the default settings its saved flows send no HTTP write (they replay under observe's rule), and its crawl runs under `--mode observe` or `read-only`; `--flow-writes allow` lets flows write as `--mode` allows. By default it fails only on facts that mean a page is broken: a page that did not load, an uncaught exception, a 5xx, a failure shown as success. Other options:
+
+- `--fail-on medium` or `low` makes the gate stricter.
+- `--ignore <rule>` drops a rule.
+- `--paths /a,/b` checks only those pages.
+- `--storage-state <file>` checks while signed in.
+- `--flows <dir>` or `off` chooses which saved flows to replay; `--retest off` skips re-testing open findings.
+- `--flow-writes never|allow` (default `never`): `never` replays flows under observe's rule whatever `--mode` says; `allow` replays them under `--mode`, so in `read-only` a flow's form submissions are sent to the target on every run.
+- `--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.
+
+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.
+
+`scenescout check --help` lists every option. Why the defaults are what they are: [ADR 11](docs/adr/0011-a-gate-is-deterministic-and-fails-only-on-what-it-can-prove.md).
+
+It also replays the flows saved in `.scenescout/flows/*.json`, with no model: the steps `scout_run_plan` takes (navigate, click, type, select, press) plus `expect-text`, `expect-url` and `expect-request`. A flow whose step breaks fails the gate, naming the flow and the step. And it re-tests the open findings earlier runs left in the project's memory that a page load can reproduce, reporting each as still reproducing or possibly fixed; by default a finding filed high that still reproduces fails the gate. [docs/ci.md](docs/ci.md#saved-flows) has the flow format; [ADR 12](docs/adr/0012-a-check-replays-saved-flows-and-reports-re-tests.md) says why it works this way.
+
+Beyond those flows it explores nothing and fills no forms. That is the exploratory run's job, and its findings belong in a report, not a gate.
+
+---
+
 ## 🩺 Troubleshooting
 
 Run `npx -y scenescout doctor` first — it checks every setup item below (everything but the last row, which is about your app) and prints the fix.
@@ -549,7 +603,8 @@ npx -y scenescout watch <path>      # the same, live in your browser, with each
 src/
   mcp-server.ts     the 29 tools + per-session dispatch
   scan.ts           project discovery (framework, routes, auth)
-  cli.ts            scan · serve · install · doctor · status
+  cli.ts            scan · serve · install · doctor · check · status
+  check-run.ts      drives a check: attach, crawl every route, collect what was measured
   installer.ts      setup logic (skill link, MCP registration, diagnostics)
   engine/
     browser.ts      the engine class: attach, snapshot, actions, crawl, plans
@@ -571,9 +626,10 @@ src/
     design.ts       the design audit + page scoring
     memory.ts       cross-run storage + finding dedup
     report.ts       the gap ledger + report generation
+    check.ts        the check's rules, gate, report and SARIF
     replay.ts       the run as one page: steps, tasks, frames under each finding
     …               collector · dispatch · fixtures · authloss · reaper
-scripts/            the 23 test suites (smoke/ holds the real-browser ones)
+scripts/            the 24 test suites (smoke/ holds the real-browser ones)
 test-app/           fixtures for the real-browser smoke tests
 skills/scenescout/   the testing method (SKILL.md): a skill in Claude Code, served by the server everywhere else
 docs/how-it-works.md  what happens at each stage, in diagrams
@@ -603,6 +659,8 @@ The load-bearing choices are recorded as ADRs — read the relevant one before c
 - [8 · Recording is opt-in, and a recorded run is one self-contained page](docs/adr/0008-a-recorded-run-is-evidence-and-must-be-asked-for.md)
 - [9 · A refused write is answered, not dropped](docs/adr/0009-a-refused-write-is-answered-not-dropped.md)
 - [10 · A lane's confidence is checked, not trusted](docs/adr/0010-a-confidence-is-checked-not-trusted.md)
+- [11 · A gate is deterministic, and fails only on what it can prove](docs/adr/0011-a-gate-is-deterministic-and-fails-only-on-what-it-can-prove.md)
+- [12 · A check replays saved flows and re-tests open findings, within settings whose defaults do the least harm](docs/adr/0012-a-check-replays-saved-flows-and-reports-re-tests.md)
 
 ---
 
@@ -614,7 +672,7 @@ Working on SceneScout itself is the only reason to clone it:
 git clone https://github.com/brunoboto96/SceneScout.git scenescout && cd scenescout
 npm install        # installs dependencies and builds
 npm run setup      # same as `scenescout install`, but registers THIS checkout (the skill is linked, so edits are live)
-npm test           # build + 23 suites: 21 pure-logic suites (scan, oracle, policy, … bench, hygiene),
+npm test           # build + 24 suites: 22 pure-logic suites (scan, oracle, policy, … bench, hygiene),
                    #                     then smoke and mcp-check (the server over stdio), both with real browsers
 npm run bench -- --all   # re-score every archived benchmark run against the current answer key
 npm run demo       # regenerate examples/ from the demo app

package/dist/browsers.js

@@ -160,6 +160,38 @@ export function screencastSupport(engine) {
 export function focusAdvanceKey(engine, platform) {
     return engine === "webkit" && platform === "darwin" ? "Alt+Tab" : "Tab";
 }
+/**
+ * Whether the browser prints a console error of its own for a subresource that
+ * failed: "Failed to load resource: the server responded with a status of
+ * 500 …" or "Failed to load resource: net::ERR_…". Chromium and WebKit do, and
+ * give the resource's address as the message's location; Firefox prints
+ * nothing. Where it is printed, the console oracle charges the line to
+ * whoever sent the request (oracles.ts `failedLoadEchoOf`), so one failing
+ * request inside an embed is not also filed as the app's console error.
+ */
+export function echoesFailedLoads(engine) {
+    return engine !== "firefox";
+}
+/**
+ * The resource type a navigator.sendBeacon request carries when it is
+ * intercepted: Chromium calls it "ping", Firefox and WebKit "beacon". A saved
+ * flow excuses a refused beacon from its step (flow.ts `splitRefusals`), so
+ * every engine's name for it must be known.
+ */
+export function beaconResourceType(engine) {
+    return engine === "chromium" ? "ping" : "beacon";
+}
+/**
+ * Whether a beacon a page sends as it is being left (sendBeacon, or a
+ * keepalive fetch, on `pagehide`) escapes interception. In Chromium it is
+ * never routed, so the write policy does not see it and it reaches the server
+ * in every mode; Firefox and WebKit route it, and the policy refuses it like
+ * any other. A limit of the network-layer policy (ADR 2), reported in ADR 12;
+ * the check smoke suite asserts both directions per engine.
+ */
+export function unloadBeaconsEscapePolicy(engine) {
+    return engine === "chromium";
+}
 /**
  * Run in every page before its own scripts: takes shared workers away.
  *

package/dist/check-run.js

@@ -0,0 +1,150 @@
+/**
+ * Runs `scenescout check`: attach, crawl every route the engine can find,
+ * measure each one, replay the saved flows, re-test the open findings a page
+ * load can reproduce, and write the verdict. The rules live in
+ * engine/check.ts, engine/flow.ts and engine/verify.ts; this file only drives
+ * the browser and the files.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { BrowserEngine } from "./engine/browser.js";
+import { issuesFromRoutes, redactFlowRuns, redactRoute, redactRoutes, settingsOf, withoutOwnResponse, } from "./engine/check.js";
+import { loadFlows, resolveFlowsDir } from "./engine/flow.js";
+import { MemoryStore, MEMORY_DIRNAME } from "./engine/memory.js";
+import { checkRetestPlan, retestResults, wellFormedFindings } from "./engine/verify.js";
+/** Link discovery rounds: each crawl reveals the routes its pages link to. Past a few, a site is paginating rather than revealing. */
+const MAX_ROUNDS = 6;
+/**
+ * Read the flows and the findings, before any browser starts. Throws with a
+ * sentence naming the file and the field on anything it cannot read: a flow
+ * that is silently skipped is a flow that silently passes.
+ */
+export function readCheckInputs(options) {
+    const where = resolveFlowsDir(options.flows, options.projectDir, (p) => fs.existsSync(p) && fs.statSync(p).isDirectory());
+    if ("error" in where)
+        throw new Error(where.error);
+    const { flows, skipped: skippedFlows } = where.dir ? loadFlows(where.dir) : { flows: [], skipped: [] };
+    if (!options.retest)
+        return { flows, skippedFlows, findings: null };
+    // Read, never written: a check leaves the project's memory as it found it.
+    const memoryPath = path.join(options.projectDir, MEMORY_DIRNAME, "memory.json");
+    if (!fs.existsSync(memoryPath))
+        return { flows, skippedFlows, findings: null };
+    let findings;
+    try {
+        findings = JSON.parse(fs.readFileSync(memoryPath, "utf8")).findings;
+    }
+    catch (err) {
+        throw new Error(`could not read ${memoryPath} to re-test its findings (${err instanceof Error ? err.message : String(err)}). Pass --retest off to check without it`);
+    }
+    if (findings !== undefined && !Array.isArray(findings))
+        throw new Error(`${memoryPath}: "findings" is not a list. Pass --retest off to check without it`);
+    return { flows, skippedFlows, findings: wellFormedFindings(findings ?? []) };
+}
+export async function runCheck(options, log = () => { }, inputs = { flows: [], findings: null }) {
+    // A throwaway memory: a check is one run, and a store shared with earlier
+    // exploratory runs would count their visits as this check's and skip those routes.
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "scenescout-check-"));
+    const engine = new BrowserEngine();
+    const start = new URL(options.url);
+    try {
+        // Attached at the origin: the engine joins every crawled path onto the URL
+        // it attached to, so attaching to a start page with a path would double it.
+        const attached = await engine.attach({
+            url: start.origin,
+            projectDir: options.projectDir,
+            memoryStore: new MemoryStore(scratch),
+            mode: options.mode,
+            storageStatePath: options.storageStatePath,
+            ...(options.browser ? { browser: options.browser } : {}),
+            objective: "Deterministic check: visit every route and measure it",
+            task: "Checking every route",
+        });
+        // A saved session that no longer signs in would check the sign-in page and call it the app.
+        const authFailed = attached.split("\n").find((line) => line.startsWith("⚠ AUTH FAILED"));
+        if (authFailed)
+            throw new Error(authFailed.replace(/ Continuing now tests a logged-out app\.$/, "").replace(/re-attach/, "run the check again"));
+        const routes = [];
+        const crawl = async (paths, limit) => {
+            await engine.crawl(paths, { inspect: true, limit });
+            routes.push(...engine.lastCrawlHealth);
+        };
+        if (options.paths) {
+            await crawl(options.paths.slice(0, options.maxRoutes), options.maxRoutes);
+        }
+        else {
+            // The start page first, whatever else is known: it is the one route the user named.
+            await crawl([`${start.pathname}${start.search}${start.hash}`], 1);
+            for (let round = 0; round < MAX_ROUNDS && routes.length < options.maxRoutes; round++) {
+                if (engine.crawlableRoutes().length === 0)
+                    break;
+                await crawl(undefined, options.maxRoutes - routes.length);
+                log(`  ${routes.length} route(s) checked`);
+            }
+        }
+        // Pages of open findings the crawl did not load exactly: loaded now, so each re-test has its own measurement.
+        // Kept apart from `routes`: they are measured only to re-test, never checked against the page rules, and do not count
+        // towards --max-routes. With --paths the check stays on the paths it was given.
+        const plan = inputs.findings ? checkRetestPlan(inputs.findings) : null;
+        const retestPages = [];
+        if (plan && !options.paths) {
+            const missing = [...new Set(plan.candidates.map((c) => c.path))].filter((p) => !routes.some((r) => r.path === p));
+            if (missing.length > 0) {
+                await engine.crawl(missing, { limit: missing.length, measureOnly: true });
+                retestPages.push(...engine.lastCrawlHealth);
+                log(`  ${missing.length} page(s) of open findings loaded only to re-test them`);
+            }
+        }
+        const flowRuns = [];
+        for (const flow of inputs.flows) {
+            // --flow-writes never: observe's rule, whatever --mode lets the crawl do.
+            const replay = await engine.replayFlow(flow.steps, options.flowWrites === "never" ? "observe" : options.mode);
+            flowRuns.push({ name: flow.name, file: flow.file, steps: flow.steps.length, ...replay });
+            log(`  flow ${flow.name}: ${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.
+            if (replay.outcome.status === "refused" && options.onRefusedStep === "stop")
+                break;
+        }
+        const retest = plan
+            ? {
+                open: plan.open,
+                extraPages: retestPages.length,
+                results: retestResults(plan.candidates, [...routes, ...retestPages].map((r) => ({
+                    path: r.path,
+                    status: r.status,
+                    ...(r.loadError !== undefined ? { loadError: r.loadError } : {}),
+                    loginRedirect: r.loginRedirect,
+                    httpErrors: withoutOwnResponse(r)
+                        .violations.filter((v) => v.kind === "http_error")
+                        .map((v) => v.detail),
+                }))),
+            }
+            : null;
+        const measured = redactRoutes(routes.map(withoutOwnResponse));
+        const flows = redactFlowRuns(flowRuns);
+        return {
+            url: redactRoute(options.url),
+            generatedAt: new Date().toISOString(),
+            mode: options.mode,
+            failOn: options.failOn,
+            routes: measured,
+            issues: issuesFromRoutes(measured, start.origin, options.ignore, flows),
+            // Routes that failed to load are issues already; "not visited" is only what --max-routes left out.
+            unvisited: options.paths ? [] : engine.crawlableRoutes().map(redactRoute),
+            ignored: options.ignore,
+            flows,
+            skippedFlows: inputs.skippedFlows ?? [],
+            retest,
+            settings: settingsOf(options),
+        };
+    }
+    finally {
+        await engine.close().catch((err) => log(`closing the browser failed: ${err instanceof Error ? err.message : String(err)}`));
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/** Where a check writes when not told: beside the project's other SceneScout output, which is already ignored by git. */
+export function defaultCheckDir(projectDir) {
+    return path.join(projectDir, MEMORY_DIRNAME, "check");
+}

package/dist/cli.js

@@ -6,6 +6,7 @@
  *   scenescout serve                Run the MCP server on stdio
  *   scenescout install              Install the skill, download the browser, register the MCP server
  *   scenescout doctor               Check every piece of the setup and say how to fix what is missing
+ *   scenescout check <url>          Visit every route, measure it, and pass or fail (no model involved)
  */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
@@ -16,13 +17,20 @@ import { fileURLToPath } from "node:url";
 import { APPROX_DISK_MB, BROWSER_ENGINES, browserPresence, defaultAttachNote, defaultEngine, launchTarget, parseBrowserSelection, playwrightInstallArgs, } from "./browsers.js";
 import { CLIENT_LABELS, firstMessageHint, manualFor, parseClients, registerWithClient, vscodeBinary } from "./clients.js";
 import { CLI_NAME, diagnose, ensureCommand, findOnUserPath, installSkill, isEphemeralRoot, launchCommand, manualRegisterCommand, planCommand, registerMcp, resolveClaudeDir, spawnRunner, } from "./installer.js";
-import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME } from "./engine/memory.js";
+import { defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
+import { EXIT, exitCodeOf, formatCheck, parseCheckArgs, refusedFlowReason, toSarif, toSummaryJson, unmeasuredReason } from "./engine/check.js";
+import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME, writeSelfIgnore } from "./engine/memory.js";
 import { formatStatus, liveEngines, liveTokenFileName, localClock, LIVE_TOKEN_FILE, pidAlive, watchTarget, wholeSessions, } from "./engine/live.js";
 import { formatScan, scanProject } from "./scan.js";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(here, "..");
+/** This package's version, as published. */
+function packageVersion() {
+    return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
+}
 function usage(exitCode = 1) {
-    console.log(`SceneScout — AI exploratory UI testing engine (MCP)
+    // The version beside the name: an old global install is otherwise easy to mistake for this one.
+    console.log(`SceneScout ${packageVersion()} — AI exploratory UI testing engine (MCP)
 
 Usage:
   scenescout scan <projectPath>     Discover framework, routes, auth states
@@ -39,6 +47,23 @@ Usage:
   scenescout doctor                 Check the setup and print the fix for anything missing
                                     (--engine: only node, the build and the browser — for plugin
                                      installs and other MCP clients)
+  scenescout check <url>            Visit every route, measure each one, and pass or fail — no model involved,
+                                    so it can gate a pull request. Writes report.md, check.sarif and check.json.
+                                    (--fail-on high|medium|low|never (default high); --mode observe|read-only;
+                                     --max-routes N (default 50); --paths /a,/b to check only those;
+                                     --ignore rule,rule; --storage-state file to check signed in;
+                                     --project dir (default: here); --out dir (default: .scenescout/check);
+                                     --browser chromium|firefox|webkit;
+                                     --flows dir|off: replay the flows saved there (default: .scenescout/flows);
+                                     --retest on|off: re-test open findings a page load reproduces (default on);
+                                     --flow-writes never|allow: never (default) replays flows under observe's
+                                      rule whatever --mode says; allow replays them under --mode, so their
+                                      form submissions are sent;
+                                     --on-refused-step report|stop: report (default) marks a flow whose step was
+                                      refused "could not run", keeps every other verdict and exits 2; stop exits 2 there;
+                                     --gate-retests never|high|all: which still-reproducing findings fail the gate
+                                      (default high: those filed high))
+                                    Exit code: 0 passed, 1 failed the gate, 2 could not run.
   scenescout status [projectPath]   What is the engine doing right now? (every session + recent actions)
   scenescout watch [projectPath]    Open the live view in a browser: what each session is doing, a thumbnail
                                     of its page, and a live stream you can switch on per session
@@ -385,8 +410,7 @@ async function install(flags) {
     }
     else {
         const onPath = () => findOnUserPath({ names: process.platform === "win32" ? [`${CLI_NAME}.cmd`] : [CLI_NAME], pathValue: process.env.PATH ?? "" });
-        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
-        const done = ensureCommand(planCommand({ packageRoot, nodePath: process.execPath, version: pkg.version, resolved: onPath(), platform: process.platform }), spawnRunner);
+        const done = ensureCommand(planCommand({ packageRoot, nodePath: process.execPath, version: packageVersion(), resolved: onPath(), platform: process.platform }), spawnRunner);
         if (done.status === "present") {
             cli = CLI_NAME;
             console.log(`✓ \`${CLI_NAME}\` command already on PATH: ${done.at}`);
@@ -445,6 +469,70 @@ async function doctor(flags) {
         ? "\nAll good. Ask your agent:  Use SceneScout to test http://localhost:3000"
         : "\nAll good. In any project, run:  /scenescout   (or ask: Use SceneScout to test http://localhost:3000)");
 }
+/** `scenescout check`: exit 0 passed, 1 failed the gate, 2 could not run. */
+async function check(args) {
+    if (args.includes("--help") || args.includes("-h"))
+        usage(0);
+    const parsed = parseCheckArgs(args, process.cwd());
+    if (!parsed.ok) {
+        console.error(`scenescout check: ${parsed.error}`);
+        process.exit(EXIT.error);
+    }
+    const options = parsed.options;
+    const outDir = options.outDir ?? defaultCheckDir(options.projectDir);
+    let inputs;
+    try {
+        inputs = readCheckInputs(options);
+    }
+    catch (err) {
+        console.error(`scenescout check: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(EXIT.error);
+    }
+    let result;
+    try {
+        console.log(`Checking ${options.url} …${inputs.flows.length > 0 ? ` (and ${inputs.flows.length} saved flow(s))` : ""}`);
+        result = await runCheck(options, (line) => console.log(line), inputs);
+    }
+    catch (err) {
+        console.error(`scenescout check: could not run: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(EXIT.error);
+    }
+    const unmeasured = unmeasuredReason(result.routes, !options.paths);
+    if (unmeasured) {
+        console.error(`scenescout check: could not measure ${options.url}: ${unmeasured}`);
+        process.exit(EXIT.error);
+    }
+    const refused = refusedFlowReason(result);
+    // --on-refused-step stop: no verdict is written at all.
+    if (refused && options.onRefusedStep === "stop") {
+        console.error(`scenescout check: could not run a saved flow: ${refused}`);
+        process.exit(EXIT.error);
+    }
+    const markdown = formatCheck(result);
+    try {
+        const version = packageVersion();
+        if (!options.outDir)
+            writeSelfIgnore(path.dirname(outDir));
+        fs.mkdirSync(outDir, { recursive: true });
+        fs.writeFileSync(path.join(outDir, "report.md"), markdown);
+        fs.writeFileSync(path.join(outDir, "check.sarif"), JSON.stringify(toSarif(result, version), null, 2) + "\n");
+        fs.writeFileSync(path.join(outDir, "check.json"), JSON.stringify(toSummaryJson(result, version), null, 2) + "\n");
+        // 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);
+    }
+    catch (err) {
+        // A verdict nobody can read is not a pass or a fail: exit as "could not run", never as the gate's 1.
+        console.error(`scenescout check: could not write the results to ${outDir}: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(EXIT.error);
+    }
+    console.log("\n" + markdown);
+    console.log(`Wrote report.md, check.sarif and check.json to ${outDir}`);
+    // --on-refused-step report: everything else has its verdict in the files, and the exit code still says the run was incomplete.
+    if (refused)
+        console.error(`scenescout check: could not run a saved flow: ${refused}`);
+    process.exit(exitCodeOf(result));
+}
 const [, , command, ...args] = process.argv;
 // A CLI's failure mode should be a sentence, not a stack trace. `scan` on a
 // path that does not exist and `status` on a half-written status.json both
@@ -461,8 +549,7 @@ try {
             usage(0);
         case "--version":
         case "-v": {
-            const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
-            console.log(pkg.version);
+            console.log(packageVersion());
             break;
         }
         case "scan": {
@@ -484,6 +571,10 @@ try {
             await doctor(args);
             break;
         }
+        case "check": {
+            await check(args);
+            break;
+        }
         case "status": {
             status(path.resolve(args[0] ?? process.cwd()));
             break;