scenescout 3.14.1 → 3.15.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # scenescout
 
+## 3.15.0
+
+### Minor Changes
+
+- 3c488f3: Finding dedup can ask a model. When the dedup rule keeps a newly filed finding apart from everything recorded, a model judge is asked whether it is the same defect as one of the open findings on the same page (the three most alike, at most), and a "same" merges it; the merged filing's title, category, severity and evidence are kept under the finding and shown in the report with the judge's probability. Any failure, unsure answer or slow call leaves the rule's decision and is logged once per kind; three failed calls in a row switch the judge off for the run.
+  
+  `scenescout ci` judges by default with the run's model at the lowest effort its API takes, sending each asked pair's titles, categories and evidence, and the page's path; the calls count in the run's usage, and `--dedup rule` (or the action's `dedup` input) turns it off. The MCP server judges only when `SCENESCOUT_DEDUP=judge` or `scout_attach {dedup: "judge"}` asks for it, with `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in its environment (`SCENESCOUT_DEDUP_PROVIDER` picks one when both are set).
+- 47d5293: Add `scenescout <url>`, a first look at any app with nothing set up: `npx -y scenescout http://localhost:3000`. It runs the deterministic check's crawl and measurements in observe mode, where nothing but reads leaves the page (`--mode read-only` lets a plain POST through), visiting up to 20 pages and starting none after 3 minutes (`--max-routes`, `--max-minutes`), with no model and no API key. When the headless Chromium build is missing it downloads that and nothing else: no skill, no MCP registration, nothing on the PATH. It writes `report.md` and `check.json` to `scenescout-report/` in the current folder (a temporary folder when that cannot be written, or `--out`), and only into a folder that is new, empty or an earlier first look's: any other `scenescout-report/` is left as it is and the run exits 2, pointing at `--out`, and a `report.md` or `check.json` a first look did not write is never replaced; and the summary and the report open with the three issues to look at first: the highest severity, then the most pages affected, with one failure seen several ways (a missing image is a failed request, a broken image and a console line) taking one of the three places. It exits 0 once it has looked, whatever it found, and 2 when it could not run, such as when the address cannot be reached, or could not write the report. The guide's Start here page and the README's quickstart now lead with it.
+- 400add2: `scenescout login --script` signs in to passwordless apps and takes a fixed one-time code. `SCENESCOUT_LOGIN_OTP_CODE` is a code the test environment accepts, typed where the form asks for one, as an alternative to `SCENESCOUT_LOGIN_TOTP_SECRET` (setting both is refused at startup); it is redacted from all output like the other credentials. `SCENESCOUT_LOGIN_PASSWORD` may be left unset when a code is given: the run fills the username, presses the button that sends the code ("Send code", "Continue"), waits through the moment with no field on screen, and types the code; a password field that appears anyway stops the run naming the variable.
+  
+  Finding and submitting the code: a code split into one box per character is typed one character per box; a numeric field sized for a code is the code field once the username has gone; an email field whose label mentions a code stays the username. After typing, the run reads the page until it is clear how to go on, so a button enabled only once the form is complete is waited for, a page that takes the code itself is not submitted again, and a field the typing revealed is filled first. A button that signs in or verifies is pressed rather than one that sends a code where a page has both, and buttons that resend a code or change the address are never pressed. With no success URL or selector, a page with no sign-in field now counts as signed in only once a password or a code has gone, so the pause while a code is sent is not taken for a sign-in.
+- 3471e73: Snapshots say more about the page. Alert and status regions are listed by their text whether or not they carry a test id, and the diff reports a region that says something new. Controls show their state (`pressed`, `selected`, `checked`, `expanded`, `current`) and the diff reports it moving; the per-control `done` marker is now `exercised`. A `main:` line summarises the main area's heading and static text, or says `main: EMPTY`, and crawl lines carry the same count. Accessible names follow the accessible-name computation's order: wrapping labels and `title` name a control, a button-like input is named by its value, and a select is never named by its options. Elements listed only for a test id (wrappers, headings, decorative badges) are no longer counted as unnamed controls or in the coverage denominator, and nothing inside an `aria-hidden` subtree is counted as unnamed. Controls held outside the visible width of a horizontally scrolling container are reported once per container, under the new worth-a-look check rule `scrolled-out-controls`.
+
+### Patch Changes
+
+- f6997dc: The design audit's task-efficiency lines count only what they describe. Competing actions are buttons and links painted as buttons; text fields and breadcrumb links no longer count. Form burden counts the fields of a form; row-selection checkboxes, selects that edit a table row in place and search boxes no longer count, and when the page has a `<form>`, fields outside it no longer count either. The app shell's landmarks (navigation, banner, sidebar and footer regions outside the main content) are kept out of a page's score from the first audit, so the first pages of a run are no longer scored with the shell in them while later ones are scored without it. A shell built without landmarks is still recognised only once the shared-chrome census has seen it on several routes.
+- c9edcac: Fewer false oracle violations. A `scout_request` probe the server refuses is no longer reported as an `http_error` or `console_error` of the page visited next. `false_success` now pairs a refused write only with a success message the action put on screen: a status badge or heading already there, a column header and a write the page sent in the background or to its own telemetry no longer count; a success message beside an action whose other writes went through is reported as a partial `false_success` at medium ("partial: N of M writes from this action were refused"); and an announced "was refused", "rejected" or "could not" counts as the page admitting the refusal. The silent-submit note matches its words ("sign", "post", "save") as whole words and waits for a client-side route change before calling a click silent. A page error raised by a link click that left the URL unchanged and opened a confirmation, or whose message says a route change was cancelled, is reported at medium with a note instead of high.
+- a5f9c33: The refresh broker no longer holds back an app's requests when its refresh token is a cookie scoped to "/". A cookie alone no longer makes a request a refresh: only a POST, PUT or PATCH to a path named for a refresh, or an endpoint the broker has seen rotate the cookie (learned for every session of the role), goes through the lock. Scripts, stylesheets, images and fonts are never brokered, and when the broker cannot take the lock or read the profile the request goes out as the page sent it instead of being dropped. A refresh-named storage value that is an address is no longer taken for a token. On Windows, a lock file still being deleted as it changes hands (EPERM, EBUSY or EACCES) is waited for like a held lock instead of failing.
+
 ## 3.14.1
 
 ### Patch Changes

package/README.md

@@ -104,6 +104,28 @@ SceneScout needs only a URL. Give it the source code as well and it gets noticea
 
 ## 🚀 Quickstart
 
+### ⚡ A first look, nothing to set up
+
+Node 20 or newer and the address of an app you are allowed to test:
+
+```bash
+npx -y scenescout http://localhost:3000
+```
+
+It needs no model, no API key and no MCP client. It downloads the headless Chromium build if the machine has none (once, about 200 MB) and changes nothing else: no skill, no MCP registration, nothing on your PATH. Then it opens up to 20 pages in `observe` mode, where nothing but reads leaves the page (signing in and refreshing a token apart), starting none after 3 minutes. It measures each one the way [`scenescout check`](docs/guide/Ways-to-use-it.md#scenescout-check-a-gate-in-ci) does, writes `scenescout-report/report.md` in the current folder and prints the three issues to look at first:
+
+```
+Look at these first:
+  1. [medium] Request failed with a client error: GET /img/weekly-chart.png → HTTP 404 (on /)
+  2. [medium] Dead end: /reports-scheduled.html: 0 controls (on /reports-scheduled.html)
+  3. [medium] Control covered by pinned chrome: button "Save notes" is COVERED by pinned chrome [order-stickybar] at this scroll position — a click aimed at it lands on that element instead (on /order.html?id=1042)
+
+12 pages looked at in 12 s in observe mode: 0 high · 6 medium · 2 low · 5 worth a look, never counted.
+Report: scenescout-report/report.md
+```
+
+That is the [demo app](demo-app/). It exits 0 whatever it finds (a look, not a gate), and 2 when the address cannot be reached or the report cannot be written. After the address, `--max-routes` and `--max-minutes` raise the limits, `--mode read-only` lets a plain POST through, and `--out` names another folder. A `scenescout-report/` holding files a first look did not write is left alone, and no report it did not write is ever replaced. A first look only opens pages. To have your agent click, fill forms, compare roles and remember what it learned, set SceneScout up as below.
+
 ### 📦 Prerequisites
 
 | | |
@@ -193,9 +215,9 @@ A browser window opens at the URL. Sign in however the app asks, then come back
 
 Then `/scenescout --role admin`, or `scout_attach { role: "admin" }` from any agent. Every session attached with the same role gets its own browser built from that one login, so parallel lanes can all run as `admin`. A role with no saved login is refused with the command to run. `role` and `storageStatePath` are alternatives: pass one.
 
-Sessions of one role share one saved login, so they share its refresh token too. An app that rotates refresh tokens and treats a second use of a spent one as theft would revoke the whole token family, and sign every session of that role out, the moment two of them refreshed with the same token. SceneScout stops that for a session attached by role. When the page is about to send a refresh token from the role's profile, the session first takes a lock beside the profile (`.scenescout/auth/<role>.json.lock`, owner-only, taken over if its holder has not touched it in 30 seconds). Holding the lock, it re-reads the profile: if another session has rotated the token in the meantime, it loads that profile into its own browser and sends the current token in place of the spent one. Once the page has stored the rotated token, the session writes its state back over the profile and releases the lock. Sessions in separate processes share the lock through the file. A refresh token is recognised by name (a cookie, a storage key, or a field inside a JSON storage value whose name contains `refresh`) and is never printed or logged. An app whose sign-in renews through the identity provider's own session cookie needs none of this, since no refresh token is shared. `SCENESCOUT_REFRESH_BROKER=off` turns the broker off.
+Sessions of one role share one saved login, so they share its refresh token too. An app that rotates refresh tokens and treats a second use of a spent one as theft would revoke the whole token family, and sign every session of that role out, the moment two of them refreshed with the same token. SceneScout stops that for a session attached by role. When the page is about to send a refresh token from the role's profile, the session first takes a lock beside the profile (`.scenescout/auth/<role>.json.lock`, owner-only, taken over if its holder has not touched it in 30 seconds). Holding the lock, it re-reads the profile: if another session has rotated the token in the meantime, it loads that profile into its own browser and sends the current token in place of the spent one. Once the page has stored the rotated token, the session writes its state back over the profile and releases the lock. Sessions in separate processes share the lock through the file. A refresh token is recognised by name (a cookie, a storage key, or a field inside a JSON storage value whose name contains `refresh`) and is never printed or logged. A token that is only in a cookie makes a request a refresh only when the request is plausibly the refresh call, a POST to a path named for one or an endpoint seen to rotate the cookie, so a refresh cookie scoped to `/` never holds back the app's other requests; scripts, stylesheets, images and fonts are never brokered, and a broker that cannot do its job lets the request through unchanged. See [the guide](docs/guide/Signing-in.md#sessions-that-share-a-refresh-token). An app whose sign-in renews through the identity provider's own session cookie needs none of this, since no refresh token is shared. `SCENESCOUT_REFRESH_BROKER=off` turns the broker off.
 
-In CI, where nobody can type, `--script` signs in headless as a test user from `SCENESCOUT_LOGIN_USERNAME`, `SCENESCOUT_LOGIN_PASSWORD` and, for a one-time code, `SCENESCOUT_LOGIN_TOTP_SECRET`, and saves the same profile. No credential value is ever printed. See [signing in from CI](docs/ci.md#signing-in-from-ci) for the options and the rules: a test tenant's user, never production or a real person's account.
+In CI, where nobody can type, `--script` signs in headless as a test user from `SCENESCOUT_LOGIN_USERNAME`, `SCENESCOUT_LOGIN_PASSWORD` and, for a one-time code, `SCENESCOUT_LOGIN_TOTP_SECRET` or a fixed code the test environment accepts in `SCENESCOUT_LOGIN_OTP_CODE` (with no password for a passwordless sign-in), and saves the same profile. No credential value is ever printed. See [signing in from CI](docs/ci.md#signing-in-from-ci) for the options and the rules: a test tenant's user, never production or a real person's account.
 
 Before a parallel run, `scout_lane_brief` checks that the planner's saved login will outlast it: `runMinutes` (default 60) plus `expiryMarginMinutes` (default 10). It refuses only when it is sure, meaning every credential in the profile has a date, none was set for another host, and the last of them ends before the run does, and then names the `scenescout login` command to run again. A profile holds cookies other than the sign-in (analytics, preferences), so the first one to expire is reported as a warning rather than a reason to refuse, and a profile with undated credentials in it (a session cookie, or a refresh token with no expiry) is a warning that its lifetime is unknown.
 
@@ -430,6 +452,7 @@ npx scenescout ci http://127.0.0.1:3000
 - **Providers:** the Anthropic Messages API (default model `claude-sonnet-5`) or the OpenAI Responses API (default `gpt-6-luna`), chosen by which key is set; with both set, `--provider` decides. `--model` and `--effort` (default `low`) override; `--base-url` points at another endpoint that implements the same API.
 - **Caps:** at most 40 model turns, 1,500,000 tokens and 20 minutes (`--max-turns`, `--max-tokens`, `--max-minutes`). The first cap reached ends the exploration; the report is still written, and says which cap ended it.
 - **Mode:** `read-only` by default; `--mode observe` sends no form at all, `--mode safe-write` lets the run create records and change only the ones it created. `--mode destructive` runs only with `--allow-destructive` as well.
+- **Duplicates:** when the dedup rule keeps a filed finding apart, the run's model is asked at its lowest effort whether it is one already open on the same page, and merges it on a "same", keeping the filing's title, category, severity and evidence under that finding. The two findings' titles, categories and evidence, and the page's path, are sent; `--dedup rule` turns it off ([ADR 17](docs/adr/0017-a-model-judges-only-the-merges-the-rule-misses.md)).
 - **Output**, in `.scenescout/ci/` (or `--out`): `report.md` and `report.html` (the report an agent's run writes), `summary.md` (also appended to the GitHub job summary), `ci.json` and `ci.sarif`, with a usage line: turns, tokens, time and an estimated cost where the model's price is known (`--price-in`, `--price-out` give one for any model).
 
 There is a GitHub Action for it (`uses: brunoboto96/SceneScout/ci@…`). [docs/ci.md](docs/ci.md#an-unattended-exploratory-run) has the workflow and every option; [ADR 14](docs/adr/0014-an-unattended-run-reports-and-never-gates.md) says why it works this way.
@@ -674,7 +697,7 @@ src/
     memory.ts       cross-run storage + finding dedup
     profiles.ts     saved sign-ins: role names, where a profile lives, owner-only files, attach by role, sessionStorage restore
     refresh.ts      the refresh broker: which values are a role's refresh tokens, the lock beside the profile, swapping a spent token
-    scripted-login.ts  a CI sign-in: env and flags, TOTP (RFC 6238), which field is which, redaction
+    scripted-login.ts  a CI sign-in: env and flags, TOTP (RFC 6238) or a fixed code, which field is which, redaction
     expiry.ts       how long a saved sign-in lasts: cookie dates and JWT exp, checked before lanes start
     report.ts       the gap ledger + report generation
     check.ts        the check's rules, gate, report and SARIF

package/dist/check-run.js

@@ -9,12 +9,10 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { BrowserEngine } from "./engine/browser.js";
-import { checkFindings, redactFlowRuns, redactRoute, redactRoutes, settingsOf, withoutOwnResponse, } from "./engine/check.js";
+import { checkFindings, MAX_DISCOVERY_ROUNDS, 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
@@ -43,11 +41,19 @@ export function readCheckInputs(options) {
     return { flows, skippedFlows, findings: wellFormedFindings(findings ?? []) };
 }
 export async function runCheck(options, log = () => { }, inputs = { flows: [], findings: null }) {
+    if (options.paths && options.timeBudgetMs !== undefined)
+        throw new Error("a time budget applies to route discovery, not to a list of paths");
     // 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-"));
+    // Also on an exit the finally below never reaches, such as Ctrl+C, which the browser's driver answers with process.exit.
+    const removeScratch = () => fs.rmSync(scratch, { recursive: true, force: true });
+    process.once("exit", removeScratch);
     const engine = new BrowserEngine();
     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;
+    const pastDeadline = () => deadline !== undefined && Date.now() >= deadline;
     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.
@@ -68,23 +74,26 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
         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 });
+        const crawl = async (paths, limit, deadline) => {
+            await engine.crawl(paths, { inspect: true, limit, deadline });
             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.
+            // The start page first, whatever else is known: it is the one route the user named. The
+            // time budget does not apply to it, so a run always measures at least the page it was given.
             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)
+            for (let round = 0; round < MAX_DISCOVERY_ROUNDS && routes.length < options.maxRoutes; round++) {
+                if (engine.crawlableRoutes().length === 0 || pastDeadline())
                     break;
-                await crawl(undefined, options.maxRoutes - routes.length);
+                await crawl(undefined, options.maxRoutes - routes.length, deadline);
                 log(`  ${routes.length} route(s) checked`);
             }
         }
+        // Out of time with routes still to visit; a cap of routes reached first is --max-routes's to report.
+        const timeLimitReached = pastDeadline() && routes.length < options.maxRoutes && engine.crawlableRoutes().length > 0;
         // 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.
@@ -134,8 +143,9 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
             routes: measured,
             issues,
             worthALook,
-            // Routes that failed to load are issues already; "not visited" is only what --max-routes left out.
+            // Routes that failed to load are issues already; "not visited" is only what --max-routes (or the time budget) left out.
             unvisited: options.paths ? [] : engine.crawlableRoutes().map(redactRoute),
+            ...(options.timeBudgetMs !== undefined ? { timeBudget: { ms: options.timeBudgetMs, reached: timeLimitReached } } : {}),
             ignored: options.ignore,
             flows,
             skippedFlows: inputs.skippedFlows ?? [],
@@ -145,7 +155,8 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
     }
     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 });
+        process.off("exit", removeScratch);
+        removeScratch();
     }
 }
 /** Where a check writes when not told: beside the project's other SceneScout output, which is already ignored by git. */

package/dist/ci-run.js

@@ -17,6 +17,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { CreateMessageRequestSchema, ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { DEDUP_JUDGE_CAPABILITY, durationText, JUDGE_CALL_MS, JUDGE_MAX_OUTPUT_TOKENS, JUDGE_SYSTEM, JUDGE_TOOL, judgeKickoffOf, samplingResultOf, } from "./engine/dedup.js";
 import { CAPTURE_MARGIN, parseCaptureResult, rebaseUrl, SHOT_FILES, SHOTS_DIRNAME } from "./engine/capture.js";
 import { addUsage, wallLeftMs, guardToolArgs, capReached, CAPTURE_TOOLS, childEnv, ciCaptureKickoff, ciCaptureSystemPrompt, CI_DIRNAME, ciExitCode, ciKickoff, ciSarif, ciSummaryJson, ciSummaryMarkdown, ciSystemPrompt, ciToolArgs, ciTools, describeStop, findingsThisRun, NO_USAGE, readFindings, redactKeys, toolResultText, usageLine, } from "./engine/ci.js";
 import { resolveTimeLimits } from "./engine/limits.js";
@@ -135,22 +137,88 @@ export class HttpModelClient {
         this.conversation.addResults(results);
     }
 }
+/** One conversation with the provider `resolved` names. */
+function conversationFor(resolved, o, kickoff) {
+    return resolved.provider === "anthropic" ? new AnthropicConversation(o, kickoff) : new OpenAIConversation(o, kickoff);
+}
 export function httpClient(resolved, key, system, tools, kickoff) {
     const o = { baseUrl: resolved.baseUrl, model: resolved.model, effort: resolved.effort, system, tools };
-    const conversation = resolved.provider === "anthropic" ? new AnthropicConversation(o, kickoff) : new OpenAIConversation(o, kickoff);
-    return new HttpModelClient(conversation, key);
+    return new HttpModelClient(conversationFor(resolved, o, kickoff), key);
 }
-async function startServer(log) {
-    if (!fs.existsSync(serverPath))
-        throw new Error(`${serverPath} is missing: run \`npm run build\` first`);
-    const transport = new StdioClientTransport({ command: process.execPath, args: [serverPath], env: childEnv(process.env), stderr: "pipe" });
-    transport.stderr?.on("data", (chunk) => {
-        for (const line of chunk.toString("utf8").split(/\r?\n/))
-            if (line.trim())
-                log(`  [server] ${line}`);
-    });
-    const client = new Client({ name: "scenescout-ci", version: "1" });
-    await client.connect(transport);
+/**
+ * The dedup judge's model call over HTTP: one short conversation per pair, at
+ * `resolved`'s effort, with its output capped and every attempt and retry
+ * inside `callMs`. Used by `scenescout ci` (the run's provider and model at
+ * the judge's effort) and by the MCP server when a key is in its environment.
+ */
+export function httpJudgeAsk(resolved, key, deps = {}) {
+    return async (system, tools, kickoff, limitMs) => {
+        const ms = Math.min(deps.callMs ?? JUDGE_CALL_MS, limitMs ?? Infinity);
+        const o = { baseUrl: resolved.baseUrl, model: resolved.model, effort: resolved.effort, system, tools, maxOutputTokens: JUDGE_MAX_OUTPUT_TOKENS };
+        try {
+            return await new HttpModelClient(conversationFor(resolved, o, kickoff), key, { fetch: deps.fetch, sleep: deps.sleep, attemptMs: ms }).next(ms);
+        }
+        catch (err) {
+            // The "time cap" here is the judge call's own limit, not the run's: say which.
+            if (err instanceof OutOfTime)
+                throw new Error(err.message.replace(/^the time cap was reached/, `no answer within ${durationText(ms)}`));
+            throw err;
+        }
+    };
+}
+/**
+ * The client's answer to the server's dedup judge (a sampling request): the
+ * question goes to the run's model through `ask`, under this side's own
+ * JUDGE_SYSTEM and JUDGE_TOOL, and the answer goes back as the tool call. Its
+ * tokens are added to the run's usage, so the caps count them, and no call
+ * runs past the time cap: one asked after it is refused, and one asked before
+ * it gets only the time left. A request that is not the judge's question is
+ * refused; a failed call is reported to the server, whose judge then leaves
+ * the rule's decision and logs it.
+ */
+export function judgeHandler(o) {
+    const now = o.now ?? Date.now;
+    return async (request) => {
+        o.calls.calls += 1;
+        const question = judgeKickoffOf(request.params);
+        if (!question.ok) {
+            o.calls.failed += 1;
+            throw new McpError(ErrorCode.InvalidRequest, `this client answers only the dedup judge's question: ${question.error}`);
+        }
+        const left = wallLeftMs(o.spend, o.caps, now());
+        if (left <= 0) {
+            o.calls.failed += 1;
+            throw new McpError(ErrorCode.InternalError, "the run's time cap was reached, so the judge was not asked");
+        }
+        const started = now();
+        try {
+            const turn = await o.ask(JUDGE_SYSTEM, [JUDGE_TOOL], question.kickoff, Math.min(JUDGE_CALL_MS, left));
+            o.spend.usage = addUsage(o.spend.usage, turn.usage);
+            o.calls.usage = addUsage(o.calls.usage, turn.usage);
+            return samplingResultOf(turn, o.model);
+        }
+        catch (err) {
+            o.calls.failed += 1;
+            throw new McpError(ErrorCode.InternalError, redactKeys(err instanceof Error ? err.message : String(err), o.secrets ?? []));
+        }
+        finally {
+            o.calls.ms += now() - started;
+        }
+    };
+}
+/**
+ * The run's MCP client. With a judge handler it declares sampling with tools
+ * and DEDUP_JUDGE_CAPABILITY, and answers the server's dedup judge with it;
+ * without one it declares nothing, and the server dedups by the rule.
+ */
+export function ciClient(judge) {
+    const client = new Client({ name: "scenescout-ci", version: "1" }, judge ? { capabilities: { sampling: { tools: {} }, experimental: { [DEDUP_JUDGE_CAPABILITY]: {} } } } : undefined);
+    if (judge)
+        client.setRequestHandler(CreateMessageRequestSchema, judge);
+    return client;
+}
+/** A connected client as the loop's tool host. */
+export function toolHost(client) {
     return {
         tools: async () => (await client.listTools()).tools,
         call: async (name, args, timeoutMs) => {
@@ -162,6 +230,19 @@ async function startServer(log) {
         },
     };
 }
+async function startServer(log, judge) {
+    if (!fs.existsSync(serverPath))
+        throw new Error(`${serverPath} is missing: run \`npm run build\` first`);
+    const transport = new StdioClientTransport({ command: process.execPath, args: [serverPath], env: childEnv(process.env), stderr: "pipe" });
+    transport.stderr?.on("data", (chunk) => {
+        for (const line of chunk.toString("utf8").split(/\r?\n/))
+            if (line.trim())
+                log(`  [server] ${line}`);
+    });
+    const client = ciClient(judge);
+    await client.connect(transport);
+    return toolHost(client);
+}
 function readMemoryFindings(projectDir) {
     try {
         return readFindings(JSON.parse(fs.readFileSync(path.join(projectDir, MEMORY_DIRNAME, "memory.json"), "utf8")));
@@ -182,7 +263,7 @@ function readMemoryFindings(projectDir) {
  */
 export async function agentLoop(o) {
     const now = o.now ?? Date.now;
-    const spend = { turns: 0, usage: { ...NO_USAGE }, startedAt: o.startedAt ?? now() };
+    const spend = o.spend ?? { turns: 0, usage: { ...NO_USAGE }, startedAt: o.startedAt ?? now() };
     const allowed = new Set(o.tools.map((t) => t.name));
     for (;;) {
         const cap = capReached(spend, o.caps, now());
@@ -350,7 +431,15 @@ export async function runCi(options, resolved, deps) {
     const before = readMemoryFindings(options.projectDir);
     // Pictures an earlier run left in the same output are not this run's: they must never be uploaded as its.
     fs.rmSync(path.join(outDir, SHOTS_DIRNAME), { recursive: true, force: true });
-    let outcome = { stop: "could-not-start", spend: { turns: 0, usage: { ...NO_USAGE }, startedAt } };
+    // One spend for the run: the loop adds its turns, and the dedup judge's calls add their tokens, which the caps count.
+    const spend = { turns: 0, usage: { ...NO_USAGE }, startedAt };
+    // A run asked to show an element files no findings, so it has nothing to deduplicate.
+    const wantsJudge = options.dedup === "judge" && !options.show;
+    if (wantsJudge && !deps.judge)
+        log("No model was given for the dedup judge; the rule decides duplicates.");
+    const judgeAsk = wantsJudge ? deps.judge : undefined;
+    const judgeCalls = { calls: 0, failed: 0, usage: { ...NO_USAGE }, ms: 0 };
+    let outcome = { stop: "could-not-start", spend };
     let contractMet = false;
     let reportWritten = false;
     let capture;
@@ -361,11 +450,13 @@ export async function runCi(options, resolved, deps) {
     try {
         // The page-load limit may be longer than the usual attach budget; the attach gets that limit and a minute to launch.
         const attachMs = Math.max(ATTACH_MS, resolveTimeLimits(options, process.env).navMs + 60_000);
-        host = await startServer(log);
+        host = await startServer(log, judgeAsk ? judgeHandler({ ask: judgeAsk, model: resolved.model, spend, caps: options.caps, calls: judgeCalls, secrets, now }) : undefined);
         const attached = await host.call("scout_attach", {
             url: options.url,
             projectPath: options.projectDir,
             mode: options.mode,
+            // Named either way, so a SCENESCOUT_DEDUP in the job's environment never decides for the option.
+            dedup: judgeAsk ? "judge" : "rule",
             objective: `CI run: explore at level ${options.level}${options.focus ? `, focusing on ${options.focus}` : ""}`.slice(0, 300),
             task: "Starting the CI run",
             ...(options.storageStatePath ? { storageStatePath: options.storageStatePath } : {}),
@@ -390,7 +481,7 @@ export async function runCi(options, resolved, deps) {
                 caps: options.caps,
                 log,
                 now,
-                startedAt,
+                spend,
                 projectDir: options.projectDir,
                 onResult: (name, _args, r) => {
                     if (name === "scout_capture" && !r.isError)
@@ -449,6 +540,11 @@ export async function runCi(options, resolved, deps) {
         endedAt,
         findings: findingsThisRun(before, readMemoryFindings(options.projectDir)),
         ...(capture ? { capture } : {}),
+        ...(options.show
+            ? {}
+            : {
+                dedup: judgeAsk ? { by: "judge", ...(deps.judgeEffort ? { effort: deps.judgeEffort } : {}), ...judgeCalls } : { by: "rule" },
+            }),
     };
     const written = [];
     try {

package/dist/cli.js

@@ -2,6 +2,7 @@
 /**
  * SceneScout CLI.
  *
+ *   scenescout <url>                A first look with no setup: observe mode, capped, never a gate
  *   scenescout scan <projectPath>   Print project discovery results
  *   scenescout serve                Run the MCP server on stdio
  *   scenescout install              Install the skill, download the browser, register the MCP server
@@ -20,12 +21,13 @@ import { APPROX_DISK_MB, BROWSER_ENGINES, browserPresence, defaultAttachNote, de
 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 { defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
-import { httpClient, runCi } from "./ci-run.js";
+import { httpClient, httpJudgeAsk, runCi } from "./ci-run.js";
 import { runLogin, runScriptedLogin, savedLine } from "./login-run.js";
 import { credentialRedactor, LOGIN_ENV, readScriptedLogin } from "./engine/scripted-login.js";
 import { parseLoginArgs } from "./engine/profiles.js";
-import { detectProvider, EXIT_CI, KEY_ENV, parseCiArgs, redactKeys, secretValues } from "./engine/ci.js";
-import { EXIT, exitCodeOf, formatCheck, parseCheckArgs, refusedFlowReason, toSarif, toSummaryJson, unmeasuredReason } from "./engine/check.js";
+import { detectProvider, EXIT_CI, judgeEffort, KEY_ENV, parseCiArgs, redactKeys, secretValues } from "./engine/ci.js";
+import { EXIT, exitCodeOf, formatCheck, parseCheckArgs, refusedFlowReason, 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 { 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";
@@ -41,6 +43,18 @@ function usage(exitCode = 1) {
     console.log(`SceneScout ${packageVersion()} — AI exploratory UI testing engine (MCP)
 
 Usage:
+  scenescout <url> [options]        A first look, with no setup: visits the app's pages and measures them (no
+                                    model, no API key), writes ${FIRST_RUN_DIRNAME}/ in this folder and prints
+                                    the three issues to look at first. Downloads Chromium if it is missing and
+                                    changes nothing else: no skill, no MCP registration, nothing on PATH.
+                                    The address comes first, its options after it.
+                                    (--max-routes N (default 20), --max-minutes N (default 3): no page is started
+                                     past either; --mode observe|read-only (default observe: nothing but reads
+                                     leaves the page, sign-in and token refresh apart; read-only lets a plain POST
+                                     through); --out dir: where the report goes. ${FIRST_RUN_DIRNAME}/ is written
+                                     only when it is new, empty or an earlier first look's)
+                                    Exit code: 0 it looked, whatever it found; 2 could not run (the URL could
+                                    not be reached, a bad argument, no browser) or could not write the report.
   scenescout scan <projectPath>     Discover framework, routes, auth states
   scenescout serve                  Run the MCP server (stdio)
   scenescout install                One-step setup: skill + Chromium + MCP registration
@@ -96,7 +110,11 @@ Usage:
                                      --project dir (default: here); --out dir (default: .scenescout/ci);
                                      --show "the Save button": instead of exploring, capture that element as a PNG
                                       under shots/; --compare-url https://…: with --show, capture it there too and
-                                      write a diff picture)
+                                      write a diff picture;
+                                     --dedup judge|rule: judge (default) also asks the run's model, at its lowest
+                                      effort, whether a filed finding the rule keeps apart is one already on its
+                                      page (titles, categories, evidence and the page's path are sent);
+                                      rule asks nothing)
                                     Exit code: 0 the run ran (findings never change it), 2 could not run.
   scenescout login <url> --role <name>
                                     Open a visible browser at the URL, sign in there (SSO, MFA, anything), then
@@ -108,7 +126,9 @@ Usage:
   scenescout login <url> --role <name> --script
                                     For CI: sign in headless from SCENESCOUT_LOGIN_USERNAME, SCENESCOUT_LOGIN_PASSWORD
                                     and, if the form asks for a code, SCENESCOUT_LOGIN_TOTP_SECRET (base32 or an
-                                    otpauth:// URI), then save the profile as above. A test user only. No value
+                                    otpauth:// URI) or SCENESCOUT_LOGIN_OTP_CODE (a fixed code a test environment
+                                    accepts), then save the profile as above. With a code and no password, a
+                                    passwordless sign-in (the username, then the code). A test user only. No value
                                     is ever printed. Exit 0 signed in and saved, 1 not.
                                     (--success-url text|url; --success-selector css; --username-selector,
                                     --password-selector, --otp-selector, --submit-selector css; each of these also
@@ -574,6 +594,90 @@ async function check(args) {
         console.error(`scenescout check: could not run a saved flow: ${refused}`);
     process.exit(exitCodeOf(result));
 }
+/** `scenescout <url>`: a first look. Exit 0 once it has looked, whatever it found; 2 when it could not look or could not write its report. */
+async function firstRun(args) {
+    const fail = (message) => {
+        console.error(`scenescout: ${message}`);
+        process.exit(EXIT_FIRST_RUN.couldNotRun);
+    };
+    const parsed = parseFirstRunArgs(args, process.cwd());
+    if (!parsed.ok)
+        return fail(parsed.error);
+    const options = parsed.options;
+    // Found out now, not after the look; and nothing is created until the look has something to write.
+    const folderProblem = reportFolderProblem(options.outDir ?? path.join(process.cwd(), FIRST_RUN_DIRNAME), options.outDir !== undefined);
+    if (folderProblem)
+        return fail(folderProblem);
+    console.log(`SceneScout ${packageVersion()} — a first look at ${options.url}`);
+    console.log(`It opens pages and measures them and submits no form: up to ${options.maxRoutes} pages, starting none after ${options.maxMinutes} minute(s). No model, no API key.`);
+    console.log(modeSentence(options.mode));
+    // Only the build a headless Chromium launch needs. Nothing else install does happens here: no skill, no registration, nothing on PATH.
+    const downloads = firstRunDownloads(await presentBrowsers());
+    if (downloads.length > 0) {
+        console.log(downloadLine(downloads));
+        const began = Date.now();
+        if (!downloadBrowsers(downloads)) {
+            return fail(`Chromium could not be downloaded. Check the network or proxy and run this again, or download it by hand: npx playwright install ${downloads.join(" ")}`);
+        }
+        // The installer's exit code is not the build: look again before saying it is there.
+        const still = firstRunDownloads(await presentBrowsers());
+        if (still.length > 0)
+            return fail(`the download finished, but ${still.join(", ")} is still not where Playwright looks for it. Run: npx playwright install ${still.join(" ")}`);
+        console.log(`✓ Chromium downloaded in ${Math.round((Date.now() - began) / 1000)} s.`);
+    }
+    // An empty project of its own: nothing is read from, or written to, the folder this runs in except the report.
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "scenescout-first-run-"));
+    // Also on an exit the finally below never reaches, such as Ctrl+C, which the browser's driver answers with process.exit.
+    const removeProject = () => fs.rmSync(projectDir, { recursive: true, force: true });
+    process.once("exit", removeProject);
+    const began = Date.now();
+    let result;
+    let error = "";
+    try {
+        console.log(`\nLooking at ${options.url} …`);
+        result = await runCheck(firstRunCheckOptions(options, projectDir), (line) => console.log(line));
+    }
+    catch (err) {
+        error = err instanceof Error ? err.message : String(err);
+    }
+    finally {
+        process.off("exit", removeProject);
+        removeProject();
+    }
+    if (!result)
+        return fail(`could not run: ${error}`);
+    const unreachable = unreachableReason(result.routes);
+    if (unreachable)
+        return fail(`could not reach ${options.url}: ${unreachable}`);
+    const facts = { result, options, elapsedMs: Date.now() - began };
+    const files = {
+        "report.md": formatFirstRun(facts),
+        "check.json": JSON.stringify(toSummaryJson(result, packageVersion()), null, 2) + "\n",
+    };
+    // The look is done whatever happens to the files: its summary is printed either way.
+    let written;
+    let notWritten = "";
+    try {
+        written = writeFirstRunReport(files, { cwd: process.cwd(), tmpdir: os.tmpdir(), outDir: options.outDir });
+    }
+    catch (err) {
+        notWritten = err instanceof Error ? err.message : String(err);
+    }
+    if (written?.note)
+        console.log(written.note);
+    let where = `not written: ${notWritten}`;
+    if (written) {
+        const report = path.join(written.dir, "report.md");
+        const relative = path.relative(process.cwd(), report);
+        where = relative.startsWith("..") || path.isAbsolute(relative) ? report : relative;
+    }
+    console.log("");
+    for (const line of firstRunSummary(facts, where))
+        console.log(line);
+    if (!written)
+        return fail(`could not write the report: ${notWritten}`);
+    process.exit(EXIT_FIRST_RUN.ran);
+}
 /** `scenescout ci`: exit 0 when the run ran, 2 when it could not. Findings never change the exit code. */
 async function ci(args) {
     const secrets = secretValues(process.env);
@@ -591,11 +695,15 @@ async function ci(args) {
         return fail(provider.error);
     const resolved = provider.resolved;
     const key = (process.env[KEY_ENV[resolved.provider]] ?? "").trim();
-    say(`Exploring ${options.url} with ${resolved.provider} ${resolved.model} (effort ${resolved.effort}), ${options.mode} mode, level ${options.level} …`);
+    // The dedup judge asks the run's model at the lowest effort its API takes; --dedup rule asks nothing.
+    const judge = options.dedup === "judge" && !options.show ? { ...resolved, effort: judgeEffort(resolved.provider) } : null;
+    say(`Exploring ${options.url} with ${resolved.provider} ${resolved.model} (effort ${resolved.effort}), ${options.mode} mode, level ${options.level}` +
+        `${judge ? `, duplicates judged by the model at effort ${judge.effort}` : ""} …`);
     let run;
     try {
         run = await runCi(options, resolved, {
             makeClient: (system, tools, kickoff) => httpClient(resolved, key, system, tools, kickoff),
+            ...(judge ? { judge: httpJudgeAsk(judge, key), judgeEffort: judge.effort } : {}),
             log: say,
             secrets,
             version: packageVersion(),
@@ -688,6 +796,11 @@ try {
                 watch(path.resolve(positional[0] ?? process.cwd()), !a.includes("--no-open"));
             },
         },
+        // Anything unforeseen is still "could not run" (2), not the exit 1 the other commands share below.
+        firstRun: (a) => firstRun(a).catch((err) => {
+            console.error(`scenescout: could not run: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(EXIT_FIRST_RUN.couldNotRun);
+        }),
     });
 }
 catch (err) {

package/dist/commands.js

@@ -6,6 +6,9 @@
  * and ignored the rest. Every subcommand now answers `--help` / `-h` with the
  * usage text and exit 0 before it does anything, and a command that parses its
  * own flags by hand refuses one it does not know.
+ *
+ * A first argument that is an address instead of a subcommand is a first run,
+ * `scenescout <url>` (first-run.ts), which parses its own options.
  */
 const HANDLERS_OF = {
     scan: true,
@@ -70,6 +73,34 @@ export function unknownArgument(args, spec) {
 export function isSubcommand(command) {
     return command !== undefined && Object.hasOwn(HANDLERS_OF, command);
 }
+/** A host with no scheme: a name or address, an optional port, then optionally a path, query or fragment. */
+const BARE_HOST = /^(?:\[[0-9a-f:.]+\]|[a-z0-9-]+(?:\.[a-z0-9-]+)*)(?::\d{1,5})?(?:[/?#].*)?$/i;
+/** Whether an argument starts with a scheme, such as `http://`. */
+export function hasScheme(arg) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(arg);
+}
+/** The host part of an address written without its scheme: everything before its path, query or fragment. */
+export function hostOf(arg) {
+    return arg.split(/[/?#]/)[0];
+}
+/**
+ * Whether the first argument is an address, which makes the command line a
+ * first run (`scenescout <url>`): it has a scheme (`http://…`, and `ftp://…`,
+ * which the first run then refuses with a reason), or it reads as a host
+ * without one (`localhost:3000`, `example.com/app`), which the first run asks
+ * to be written in full. Subcommands are settled first, and a word that is
+ * neither (`instal`) still gets the usage.
+ */
+export function looksLikeUrl(arg) {
+    if (!arg || arg.startsWith("-"))
+        return false;
+    if (hasScheme(arg))
+        return true;
+    if (!BARE_HOST.test(arg))
+        return false;
+    const host = hostOf(arg);
+    return host.includes(".") || host.includes(":") || host.toLowerCase() === "localhost";
+}
 /** Settle help and flag errors for a subcommand before its handler is reached. */
 export function preflight(command, args) {
     if (wantsHelp(args))
@@ -93,8 +124,14 @@ export async function dispatch(command, args, h) {
         case "-v":
             return h.version();
     }
-    if (!isSubcommand(command))
-        return h.usage(1);
+    if (!isSubcommand(command)) {
+        if (!looksLikeUrl(command))
+            return h.usage(1);
+        // Its own parser refuses an option it does not know, with the first run's exit code, as check's does.
+        if (wantsHelp(args))
+            return h.usage(0);
+        return h.firstRun([command, ...args]);
+    }
     const verdict = preflight(command, args);
     if (verdict.kind === "help")
         return h.usage(0);