scenescout 3.14.1 → 3.15.0

package/dist/login-run.js

@@ -20,7 +20,7 @@ import { explicitLimits, isTimeoutMessage, LIMIT_NAMES } from "./engine/limits.j
 import { redactRoute } from "./engine/check.js";
 import { describeLifetime, readLifetime } from "./engine/expiry.js";
 import { describeSaved, mergeSessionStorage, withSessionStorage, writeProfile } from "./engine/profiles.js";
-import { chooseFields, chooseSubmit, describeStep, fieldIdentity, nextStep, secondsLeft, totp as totpCode, TOTP_MIN_SECONDS_LEFT, urlMatches, } from "./engine/scripted-login.js";
+import { afterTyping, chooseFields, describeStep, fieldIdentity, filledNames, nextStep, otpBoxes, quotable, secondsLeft, splitCode, totp as totpCode, TOTP_MIN_SECONDS_LEFT, urlMatches, } from "./engine/scripted-login.js";
 /**
  * Read what the profile keeps from a signed-in context: cookies, localStorage
  * and IndexedDB through Playwright's storage state, and sessionStorage, which
@@ -250,22 +250,37 @@ function collectFields(selectors) {
     }
     return out;
 }
-/** A page's error or alert text, if it shows one: the reason a refused sign-in gives. Redacted before it is printed. */
+/**
+ * The error or alert a page shows, if any: the first one on screen with text
+ * in it (a hidden, pre-rendered alert says nothing about this run), whole.
+ * The caller redacts it before shortening it (quotable).
+ */
 async function alertText(page) {
-    const text = await page
+    return (page
         .evaluate(() => {
-        const el = document.querySelector('[role="alert"], [aria-live="assertive"], .error, .alert');
-        return (el?.textContent ?? "").replace(/\s+/g, " ").trim();
+        for (const el of Array.from(document.querySelectorAll('[role="alert"], [aria-live="assertive"], .error, .alert'))) {
+            const r = el.getBoundingClientRect();
+            const st = getComputedStyle(el);
+            const text = (el.textContent ?? "").trim();
+            if (text && r.width > 0 && r.height > 0 && st.visibility !== "hidden" && st.display !== "none")
+                return text;
+        }
+        return "";
     })
-        // The page's message only adds to the refusal being reported; a page navigating away as it is read leaves the refusal as it stands.
-        .catch(() => "");
-    return text.slice(0, 200);
+        // The page's message only adds to the error being reported; a page navigating away as it is read leaves that error as it stands.
+        .catch(() => ""));
 }
 /**
  * Sign in with no one at the keyboard: headless, the credentials from the
  * environment, the form found by engine/scripted-login.ts's rules. Every line
  * it logs and every error it throws goes through the credential redaction
  * first. Saves the profile exactly as the manual login does.
+ *
+ * Each step fills what the page asks for, then reads the page again until it
+ * is clear how to submit (engine/scripted-login.ts's afterTyping): a page that
+ * submitted the step itself is not submitted again, a button the page enables
+ * only once the form is complete is waited for, and a field the typing
+ * revealed is filled first.
  */
 export async function runScriptedLogin(options, config, redactor, log, now = () => Date.now() / 1000) {
     const redact = (text) => redactor.redact(text);
@@ -330,7 +345,7 @@ export async function runScriptedLogin(options, config, redactor, log, now = ()
             const got = await page.evaluate(collectFields, config.selectors).catch((err) => {
                 if (midNavigation(err))
                     return null;
-                throw err;
+                throw fail(err.message);
             });
             if (got === null)
                 return null;
@@ -345,19 +360,49 @@ export async function runScriptedLogin(options, config, redactor, log, now = ()
             return `${pageKey()}|${Object.keys(chosen).sort().join(",")}`;
         };
         const stepOpts = (successMatchedNow) => ({
-            hasTotp: config.totp !== undefined,
+            hasPassword: config.password !== undefined,
+            ...(config.code ? { code: config.code.kind } : {}),
             successConfigured: Boolean(config.success.url || config.success.selector),
             successMatched: successMatchedNow,
         });
+        /** The code to type now: the fixed one, or the TOTP code, waiting for the next one when this one is about to expire. */
+        const currentCode = async (source) => {
+            if (source.kind === "fixed")
+                return source.code;
+            const params = source.params;
+            if (secondsLeft(params, now()) < TOTP_MIN_SECONDS_LEFT)
+                await page.waitForTimeout(secondsLeft(params, now()) * 1000 + 200);
+            const code = totpCode(params, now());
+            redactor.add(code);
+            return code;
+        };
+        const at = (f) => page.locator(`[${TAG}="${f.index}"]`);
+        /** A failed action as this run's error: the time limit explained, redacted like everything else it throws. */
+        const actionError = (err) => {
+            const explained = loginTimeout(err, "action", limits.actionMs);
+            return fail(explained instanceof Error ? explained.message : String(explained));
+        };
+        const actionFailed = (err) => Promise.reject(actionError(err));
+        /** What the page says, fit to quote. */
+        const pageSays = async () => quotable(await alertText(page), redact, 200);
+        /** A button's text fit to quote, redacted before it is shortened. */
+        const buttonText = (f) => quotable(f.text || f.label || "the submit button", redact, 40);
+        /** The run's deadline passed: say what it was waiting for, and what the page says, if anything. */
+        const timedOut = async (waitingFor) => {
+            const says = await pageSays();
+            return fail(`timed out after ${config.timeoutMs / 1000}s waiting for ${waitingFor} (at ${where()})${says ? `. The page says: "${says}"` : ""}`);
+        };
+        const submitOpts = { passwordless: config.password === undefined };
         let lastWait = "the sign-in form to appear";
         for (;;) {
             if (Date.now() > deadline)
-                throw fail(`timed out after ${config.timeoutMs / 1000}s waiting for ${lastWait} (at ${where()})`);
+                throw await timedOut(lastWait);
             const fields = await read();
             if (fields === null) {
                 await page.waitForTimeout(POLL_MS);
                 continue;
             }
+            const keyAtRead = pageKey();
             const chosen = chooseFields(fields);
             const step = nextStep(chosen, progress, stepOpts(await successMatched()));
             if (step.kind === "done") {
@@ -367,7 +412,7 @@ export async function runScriptedLogin(options, config, redactor, log, now = ()
                 // a page between a redirect and its first render shows no fields either.
                 await page.waitForLoadState("load", { timeout: limits.actionMs }).catch((err) => {
                     if (!/timeout/i.test(err.message) && !midNavigation(err))
-                        throw err;
+                        throw fail(err.message);
                 });
                 await page.waitForTimeout(POLL_MS * 2);
                 const settled = await read();
@@ -376,48 +421,104 @@ export async function runScriptedLogin(options, config, redactor, log, now = ()
                 continue;
             }
             if (step.kind === "refused") {
-                const says = await alertText(page);
+                const says = await pageSays();
                 throw fail(`sign-in refused: ${step.reason}.${says ? ` The page says: "${says}"` : ""}`);
             }
             if (step.kind === "stuck")
                 throw fail(`sign-in stuck: ${step.reason}.`);
             if (step.kind === "wait") {
+                const credentialSent = progress.submitted.has("password") || progress.submitted.has("otp");
                 lastWait =
                     progress.submits === 0
                         ? "the sign-in form to appear (set the field selectors if the form is not found)"
-                        : "the signed-in page (the success URL or selector, or the sign-in fields to go)";
+                        : !credentialSent
+                            ? "the page to ask for the password or the one-time code (set --password-selector or --otp-selector if the field is there but not found)"
+                            : "the signed-in page (the success URL or selector, or the sign-in fields to go)";
                 await page.waitForTimeout(POLL_MS);
                 continue;
             }
             if (progress.submits >= MAX_SUBMITS)
                 throw fail(`gave up after ${MAX_SUBMITS} submits without reaching the signed-in page`);
-            let last = null;
+            let boxOpts = {};
+            // What this step typed, recorded as submitted only once the step is: a step the page holds back (fill-more) is typed again.
+            const typedIds = new Map();
             for (const kind of step.fill) {
                 const field = chosen[kind];
-                let value;
-                if (kind === "otp") {
-                    const totp = config.totp;
-                    if (secondsLeft(totp, now()) < TOTP_MIN_SECONDS_LEFT)
-                        await page.waitForTimeout(secondsLeft(totp, now()) * 1000 + 200);
-                    value = totpCode(totp, now());
-                    redactor.add(value);
+                const boxes = kind === "otp" ? otpBoxes(fields, field) : null;
+                if (boxes) {
+                    const split = splitCode(await currentCode(config.code), boxes.length, config.code.kind);
+                    if (!split.ok)
+                        throw fail(`sign-in stuck: ${split.error}.`);
+                    for (const [i, box] of boxes.entries()) {
+                        try {
+                            // A box is often enabled only once the one before it is filled.
+                            await page.waitForFunction(([attr, index]) => {
+                                const el = document.querySelector(`[${attr}="${index}"]`);
+                                return el !== null && !el.disabled;
+                            }, [TAG, String(box.index)], { timeout: limits.actionMs, polling: 50 });
+                            // Cleared only when it holds something: clearing sends Delete, which some boxes take as a step back to the box before.
+                            if ((await at(box).inputValue({ timeout: limits.actionMs })) !== "")
+                                await at(box).fill("", { timeout: limits.actionMs });
+                            // Typed as keys: a box that moves on to the next by itself, or reads keys rather than its value, still gets its character.
+                            await at(box).pressSequentially(split.chars[i], { timeout: limits.actionMs });
+                        }
+                        catch (err) {
+                            // The first line only: the call log after it names the character being typed, which no redaction of the whole code catches.
+                            const explained = loginTimeout(err, "action", limits.actionMs);
+                            const first = (explained instanceof Error ? explained.message : String(explained)).split("\n")[0];
+                            throw fail(`could not type into box ${i + 1} of ${boxes.length} of the one-time code: ${first}`);
+                        }
+                    }
+                    boxOpts = { codeBoxes: boxes.length };
                 }
-                else
-                    value = kind === "username" ? config.username : config.password;
-                await page
-                    .locator(`[${TAG}="${field.index}"]`)
-                    .fill(value, { timeout: limits.actionMs })
-                    .catch((err) => Promise.reject(loginTimeout(err, "action", limits.actionMs)));
-                progress.submitted.set(kind, fieldIdentity(field));
-                last = field;
+                else {
+                    const value = kind === "otp" ? await currentCode(config.code) : kind === "username" ? config.username : config.password;
+                    await at(field).fill(value, { timeout: limits.actionMs }).catch(actionFailed);
+                }
+                typedIds.set(kind, fieldIdentity(field));
             }
-            const button = chooseSubmit(fields);
             const before = signature(fields);
-            await (button
-                ? page.locator(`[${TAG}="${button.index}"]`).click({ timeout: limits.actionMs })
-                : page.locator(`[${TAG}="${last.index}"]`).press("Enter", { timeout: limits.actionMs })).catch((err) => Promise.reject(loginTimeout(err, "action", limits.actionMs)));
+            const shownBefore = new Set(Object.keys(chosen));
+            const readNow = async () => {
+                const now = await read();
+                return afterTyping(step.fill, { left: now === null || pageKey() !== keyAtRead, fields: now ?? [] }, shownBefore, submitOpts);
+            };
+            let next;
+            for (;;) {
+                await page.waitForTimeout(POLL_MS);
+                next = await readNow();
+                if (next.kind !== "wait")
+                    break;
+                if (Date.now() > deadline) {
+                    const control = next.button ? `the "${buttonText(next.button)}" button` : "the field just filled";
+                    throw await timedOut(`${control} to be enabled, or the page to move on, after filling ${filledNames(step.fill, boxOpts)}`);
+                }
+            }
+            if (next.kind === "fill-more") {
+                say(describeStep(step.fill, "more", boxOpts));
+                continue;
+            }
+            let by = "page";
+            if (next.kind === "click" || next.kind === "enter") {
+                try {
+                    if (next.kind === "click")
+                        await at(next.button).click({ timeout: limits.actionMs });
+                    else
+                        await at(next.field).press("Enter", { timeout: limits.actionMs });
+                }
+                catch (err) {
+                    // The page moved on while the click waited (it took the step itself, or the click went through as it left): the step is
+                    // done. Otherwise the click's own error is the one to report, also when reading the page to tell fails.
+                    const moved = await readNow().then((after) => after.kind === "moved", () => false);
+                    if (!moved)
+                        throw actionError(err);
+                }
+                by = next.kind === "click" ? { button: buttonText(next.button) } : "enter";
+            }
+            for (const [kind, identity] of typedIds)
+                progress.submitted.set(kind, identity);
             progress.submits += 1;
-            const did = describeStep(step.fill, button ? button.text || button.label || "the submit button" : null);
+            const did = describeStep(step.fill, by, boxOpts);
             say(did);
             lastWait = `the page to move on after that step (${did})`;
             // Wait for the form to move on: another page, or other fields on this one.

package/dist/mcp-server.js

@@ -3,8 +3,12 @@
  * SceneScout MCP server (stdio).
  *
  * Exposes deterministic browser-exploration tools — Playwright actions, state
- * memory, oracles, findings, report — to any MCP client. No LLM calls happen
- * here: the client (e.g. Claude Code on a subscription) is the brain.
+ * memory, oracles, findings, report — to any MCP client. The client (e.g.
+ * Claude Code on a subscription) is the brain, and no LLM call happens here
+ * unless finding dedup is set to ask a model judge (SCENESCOUT_DEDUP, or
+ * scout_attach {dedup}): then a filing the dedup rule keeps apart is put to a
+ * model, through the client when it is a `scenescout ci` run, else with a key
+ * from this process's environment (engine/dedup.ts).
  *
  * The server process is a per-conversation daemon and behaves like one:
  * - Multi-session, genuinely concurrent: named sessions each own a live
@@ -35,6 +39,9 @@ import { z } from "zod";
 import { BrowserEngine } from "./engine/browser.js";
 import { reapOrphanBrowsers } from "./engine/reaper.js";
 import { FINDING_CATEGORIES, isWorthALook, MemoryStore, mergeableCategories, redactSecrets } from "./engine/memory.js";
+import { DEDUP_ENV, DEDUP_MODES, redactKeys, secretValues } from "./engine/ci.js";
+import { DedupJudge, planDedup, samplingAsk } from "./engine/dedup.js";
+import { httpJudgeAsk } from "./ci-run.js";
 import { decodedEntitiesNote, ignoredConventionsNote, LANE_CONVENTION_MAX, LANE_NAME_MAX, LaneLedger, laneCloseGuard, laneReportInstruction, parseLaneReport, summarizeLaneReport, } from "./engine/lane.js";
 import { MAX_UNFILED_NAMED, unfiledDefects } from "./engine/calibration.js";
 import { SessionQueue, withWatchdog } from "./engine/dispatch.js";
@@ -746,8 +753,15 @@ server.registerTool("scout_attach", {
             .max(40)
             .optional()
             .describe("Session name for multi-role runs (e.g. 'admin', 'qa'). Creates/replaces that session's browser and makes it the default. Default: 'default'."),
+        dedup: z
+            .enum(DEDUP_MODES)
+            .optional()
+            .describe(`How this run tells a filed finding from one already recorded. Default: the ${DEDUP_ENV} environment variable, else 'rule', the store's rule alone. ` +
+            "'judge': the rule first, then, for a filing the rule keeps apart from everything recorded, a model is asked whether it is one of the open findings on its page, and merges it when it says so. " +
+            "It needs ANTHROPIC_API_KEY or OPENAI_API_KEY in the server's environment, and sends each pair's titles, categories and evidence, and the page's path, to that provider — ONLY when the user asked for it. " +
+            "Applies to every session of the project until the run ends."),
     },
-}, serializedControl(async ({ url, projectPath, storageStatePath, role, mode, headed, browser, viewportWidth, viewportHeight, objective, task, record, trustedEmbeds, paceMs, actionTimeoutMs, navTimeoutMs, session, }) => {
+}, serializedControl(async ({ url, projectPath, storageStatePath, role, mode, headed, browser, viewportWidth, viewportHeight, objective, task, record, trustedEmbeds, paceMs, actionTimeoutMs, navTimeoutMs, session, dedup, }) => {
     try {
         const target = session ?? activeName;
         if (session) {
@@ -813,6 +827,8 @@ server.registerTool("scout_attach", {
         const previous = eng.memory;
         if (previous && previous !== store && ![...engines.values()].some((e) => e !== eng && e.memory === previous))
             previous.endRun();
+        // Before the browser starts: a value it cannot use refuses the attach rather than being replaced.
+        const dedupNote = configureDedup(store, dedup);
         const viewport = viewportWidth && viewportHeight ? { width: viewportWidth, height: viewportHeight } : undefined;
         const out = await eng.attach({
             url,
@@ -849,12 +865,61 @@ server.registerTool("scout_attach", {
         const recordNote = record && eng.memory?.dir
             ? `\n\n📸 RECORDING: a frame of the page after each action, under ${path.join(eng.memory.dir, "recordings", target)}/ (at most ${RECORD_MAX_FRAMES}). scout_report writes them into report.html beside report.md.`
             : "";
-        return text(out + conflictNote + recordNote + describePace(eng.pace) + (engines.size > 1 ? `\n${sessionLines()}` : "") + liveLine(), target);
+        return text(out + conflictNote + recordNote + dedupNote + describePace(eng.pace) + (engines.size > 1 ? `\n${sessionLines()}` : "") + liveLine(), target);
     }
     catch (err) {
         return errorText(err);
     }
 }));
+/** Keys in this process's environment, and anything shaped like one, taken out of a line before it is shown. */
+const withoutKeys = (text) => redactKeys(text, secretValues(process.env));
+/** A line for the operator, on stderr. */
+function logLine(line) {
+    console.error(withoutKeys(`[scenescout] ${line}`));
+}
+/**
+ * Set how a project's filings are deduplicated for this run (engine/dedup.ts
+ * planDedup): what this attach names, else what an earlier attach of the run
+ * named, else DEDUP_ENV. Returns the line the attach reports, or "".
+ */
+function configureDedup(store, asked) {
+    if (asked)
+        store.dedupChoice = asked;
+    const plan = planDedup(store.dedupChoice, process.env, server.server.getClientCapabilities());
+    if (plan.mode === "rule") {
+        store.dedupJudge = null;
+        store.dedupOff = undefined;
+        return "";
+    }
+    // On already for this run: say so only when it has since been switched off.
+    if (store.dedupJudge instanceof DedupJudge)
+        return store.dedupJudge.off ? `\n⚠ DEDUP JUDGE OFF: switched off earlier in this run after ${store.dedupJudge.off}. The rule decides duplicates.` : "";
+    if (plan.via === "off") {
+        store.dedupOff = plan.why;
+        logLine(`dedup judge off: ${plan.why}; the rule decides duplicates`);
+        return plan.note;
+    }
+    const ask = plan.via === "client" ? samplingAsk((params, options) => server.server.createMessage(params, options)) : httpJudgeAsk(plan.resolved, plan.key);
+    store.dedupJudge = new DedupJudge(ask, { label: plan.label, log: logLine, redact: withoutKeys });
+    store.dedupOff = undefined;
+    return plan.note;
+}
+/** What scout_finding tells the agent about what filing did. */
+function filedText(filed, category) {
+    const { finding, isNew, promoted } = filed;
+    if (isNew && isWorthALook(finding))
+        return `Recorded as worth a look (not a defect in the report's totals): ${finding.title} (id ${finding.id}) — a defect only if your project uses ${finding.convention}`;
+    if (isNew)
+        return `Finding recorded: [${finding.severity}] ${finding.title} (id ${finding.id})`;
+    if (filed.judged)
+        return (`Not recorded as new: the dedup judge read it as the same defect as finding ${finding.id} (p_same ${filed.judged.pSame.toFixed(2)}) — [${finding.severity}] ${finding.title}, filed as ${finding.category}, seen in ${finding.runs} runs.` +
+            `${promoted ? " That finding was worth a look and is now a defect." : ""} Its title, category, severity and evidence are kept on that finding, so the report shows the merge. If yours is a different defect, file it again with a title that says what differs.`);
+    if (promoted)
+        return `Merged into finding ${finding.id}, which was worth a look, and promoted to a defect: [${finding.severity}] ${finding.title}. It now counts among the report's findings.`;
+    if (finding.regressedAt)
+        return `⟳ REOPENED as a REGRESSION: finding ${finding.id} was previously resolved but the evidence reproduces again (seen in ${finding.runs} runs). Worth calling out to the user.`;
+    return `Not recorded as new: merged into existing finding ${finding.id} — [${finding.severity}] ${finding.title}${finding.evidence ? ` (evidence: ${finding.evidence.slice(0, 160)})` : " (no evidence)"}, filed as ${finding.category}, seen in ${finding.runs} runs. If yours is a different bug, file it again: under the category that says what is wrong if it is another kind of defect (a finding filed as ${category} merges only with one filed as ${mergeableCategories(category).join(" or ")}), or with evidence naming the request that failed for you (method and path) — two findings are kept apart when both name requests and none is shared.`;
+}
 function sessionLines() {
     const lines = ["Live sessions:"];
     for (const [name, eng] of engines) {
@@ -911,7 +976,7 @@ server.registerTool("scout_session", {
     }
 }));
 server.registerTool("scout_snapshot", {
-    description: "Capture the current page state: URL, state fingerprint, interactable elements with refs (e1, e2, …), geometry issues, coverage, and oracle violations since the last action. Re-snapshotting the same route returns a DIFF (refs stay stable). Cheap — prefer this over screenshots.",
+    description: "Capture the current page state: URL, state fingerprint, a one-line summary of the main area's heading and text, interactable elements with refs (e1, e2, …) and their state (pressed, selected, checked, expanded, current), what the page announces (alert and status regions, by their text), geometry issues, coverage, and oracle violations since the last action. Re-snapshotting the same route returns a DIFF (refs stay stable). Cheap — prefer this over screenshots.",
     inputSchema: {
         full: z.boolean().default(false).describe("Force a full element list instead of a diff"),
         session: sessionParam,
@@ -1280,9 +1345,9 @@ server.registerTool("scout_finding", {
         const eng = engineFor(session);
         if (!eng.memory)
             throw new Error("Not attached — findings need an active session.");
-        const [finding, isNew, promoted] = eng.memory.addFinding({
+        const filed = await eng.memory.fileFinding({
             severity,
-            category: category,
+            category,
             title,
             detail,
             evidence,
@@ -1291,15 +1356,9 @@ server.registerTool("scout_finding", {
             state: eng.currentState || "(unknown)",
             session: eng.sessionKey,
         });
-        return text(isNew
-            ? isWorthALook(finding)
-                ? `Recorded as worth a look (not a defect in the report's totals): ${finding.title} (id ${finding.id}) — a defect only if your project uses ${finding.convention}`
-                : `Finding recorded: [${finding.severity}] ${finding.title} (id ${finding.id})`
-            : promoted
-                ? `Merged into finding ${finding.id}, which was worth a look, and promoted to a defect: [${finding.severity}] ${finding.title}. It now counts among the report's findings.`
-                : finding.regressedAt
-                    ? `⟳ REOPENED as a REGRESSION: finding ${finding.id} was previously resolved but the evidence reproduces again (seen in ${finding.runs} runs). Worth calling out to the user.`
-                    : `Not recorded as new: merged into existing finding ${finding.id} — [${finding.severity}] ${finding.title}${finding.evidence ? ` (evidence: ${finding.evidence.slice(0, 160)})` : " (no evidence)"}, filed as ${finding.category}, seen in ${finding.runs} runs. If yours is a different bug, file it again: under the category that says what is wrong if it is another kind of defect (a finding filed as ${category} merges only with one filed as ${mergeableCategories(category).join(" or ")}), or with evidence naming the request that failed for you (method and path) — two findings are kept apart when both name requests and none is shared.`, session);
+        if (filed.judgeError)
+            logLine(`dedup judge: ${filed.judgeError}; the rule decided`);
+        return text(filedText(filed, category), session);
     }
     catch (err) {
         return errorText(err);

package/package.json

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

package/skills/scenescout/SKILL.md

@@ -34,8 +34,8 @@ You are the brain of an exploratory UI tester. The SceneScout MCP server gives y
 1. **`scout_crawl` first, always.** One call visits every known route (pass `paths` to sweep a specific subset instead), records coverage, and returns per-route health. This is the whole breadth pass — do not visit routes one-by-one with navigate+snapshot.
 2. **Investigate what the crawl flagged.** For each problem route (violations, dead-ends, auth-redirects): navigate there, `scout_snapshot`, reproduce, then `scout_finding`.
 3. **Run journeys with `scout_run_plan {steps}`.** Mechanical sequences (fill form → submit → check) go in ONE plan call — `steps` is an ordered list of `{action, target, value}` — with `testid=`/`text=`/`label=`/`role=button[name="Save"]` targets — not one LLM turn per click. The plan aborts at the first violation and tells you where; that's your cue to investigate interactively. When the user wants a flow kept working, save the plan that walked it as `.scenescout/flows/<name>.json` — `{"name", "steps"}`, the same steps, starting with a `navigate`, plus `{"action":"expect-text","text"}`, `{"action":"expect-url","pattern"}` or `{"action":"expect-request","request":"GET /api/…","status":200}` where the outcome shows — and `scenescout check` replays it on every pull request. Save only flows that read: a check replays flows under observe's rule unless the project passes `--flow-writes allow`, so a step that sends a write is reported as "could not run" and the check exits 2.
-4. **Snapshot economics:** `scout_snapshot` after landing somewhere new; re-snapshots of the same route return *diffs* with stable refs — "No element changes" costs you almost nothing. `scout_screenshot` ONLY for suspected pixel-native issues (a canvas, a rendering glitch); geometry problems (overlap, off-screen, a covered control) are already in the snapshot as GEOMETRY issues, and images that failed to load are listed under BROKEN IMAGES — file those, quoting the line. `scout_capture {ref}` saves a PNG of one element (plus a `margin` of pixels around it) only when the user asks to see how something looks; it shows, it does not judge. Controls inside embeds (`<iframe>`) are listed with the page's, each marked `⟨in … frame⟩`, and act by ref like any other. A frame of the app's own origin is the app: test it fully. A frame of another site (`cross-origin`) is someone else's system that the user has not authorised you to test: click and type there as a user would, to see the embed render and respond, but never send it hostile input — the engine refuses markup, values over 200 characters, control characters, repeated-click probes and uploads there, and you must not try SQL, template or other injection shapes either — and file what you find there as the embed's behaviour, naming its origin, not as the app's bug. A failing request such a frame sent outside the app says so (`in an embed of …`) and is kept at medium; console errors cannot be told apart by frame and stay the app's; its controls are counted apart and never enter the app's coverage or gap ledger. Its container text is masked, and the writes it sends outside the app are refused in every mode but destructive — unless the user names that origin as a trusted embed (a provider in test mode, say): pass it in `scout_attach {trustedEmbeds: ["https://…"]}` and, in safe-write only, its writes go out. Never add an origin the user did not name. The FRAMES line names frames that were not read; say in your summary that their contents were not explored.
-5. **Native-user behaviours.** `scout_type {ref, textValue}` (or its alias `value`, matching `scout_select` and a plan step) APPENDS when a field already has content (menu clicks often insert @-mention chips or commands into composers — appending preserves them; the result reports what was already there); pass `replace=true` only to deliberately clear, and `pressEnter=true` to submit from the field the way a user would. Before concluding a badge, icon, or "N errors" indicator *does nothing*, `scout_hover` it — tooltips and hover cards are invisible to snapshots and clicks, and hover output includes what appeared. In HEADED mode (`scout_attach {headed:true}`, which the user asks for when they want to watch) the user's physical mouse competes with the synthetic pointer: if a hover reveals nothing and the finding matters, ask the user to move their mouse off the browser window and retry before filing. **Scroll long pages with `scout_scroll`** — the design audit and snapshot measure at the current scroll position, so judge deep sections by scrolling then re-auditing; it refuses to scroll where a real user couldn't and reports SCROLL LOCKED (the leaked modal scroll-lock that silently amputates everything below the fold — snapshots also flag it passively as an OVERLAY line), and scrolling triggers lazy-loaded content whose failures surface as fresh oracle violations. Elements fully clipped inside an overflow-hidden container are flagged UNREACHABLE in GEOMETRY issues — no amount of scrolling reveals them; that's a high-value layout bug, distinct from merely below-the-fold content. **A page can hold SEVERAL independent scroll regions** and plain `scout_scroll` moves the largest one, so a sidebar nav beside a taller main pane never budges: pass `scout_scroll {target:"testid=…"}` to scroll one region. Never report a nav item, tab or list row as missing/truncated until you have scrolled ITS container — content scrolled out of a secondary pane looks exactly like content that was cut off.
+4. **Snapshot economics:** `scout_snapshot` after landing somewhere new; re-snapshots of the same route return *diffs* with stable refs — "No element changes" costs you almost nothing. **Reading a snapshot:** each line is `ref role "name" [flags]`. State flags come first — `pressed`, `selected`, `checked`, `expanded`, `current` — so the active filter, the chosen tab or the open section is in the text, and the diff says when one moves (`now [pressed]`, `no longer [pressed]`); `exercised` means this project already acted on that control, not that it is in any state. What the page announces is listed by its text whether or not it carries a test id: `alert "…"` and `status "…"` lines (role=alert/status, aria-live regions, `<output>`) — read them after every submit before concluding an action gave no feedback; a region that says something new shows in the diff as `~ ref alert "new text" (was …)`. The `main:` line summarises the main area besides its controls (`main: h1 "Orders" · 2 paragraphs · 180 chars of static text`, or `main: EMPTY`): a page whose main area holds only text is not a blank page, and `main: EMPTY` is the line that is. Elements listed only for their test id (wrappers, headings, decorative badges) are not controls: they are never counted as unnamed or as coverage gaps. `scout_screenshot` ONLY for suspected pixel-native issues (a canvas, a rendering glitch); geometry problems (overlap, off-screen, a covered control) are already in the snapshot as GEOMETRY issues, and images that failed to load are listed under BROKEN IMAGES — file those, quoting the line. `scout_capture {ref}` saves a PNG of one element (plus a `margin` of pixels around it) only when the user asks to see how something looks; it shows, it does not judge. Controls inside embeds (`<iframe>`) are listed with the page's, each marked `⟨in … frame⟩`, and act by ref like any other. A frame of the app's own origin is the app: test it fully. A frame of another site (`cross-origin`) is someone else's system that the user has not authorised you to test: click and type there as a user would, to see the embed render and respond, but never send it hostile input — the engine refuses markup, values over 200 characters, control characters, repeated-click probes and uploads there, and you must not try SQL, template or other injection shapes either — and file what you find there as the embed's behaviour, naming its origin, not as the app's bug. A failing request such a frame sent outside the app says so (`in an embed of …`) and is kept at medium; console errors cannot be told apart by frame and stay the app's; its controls are counted apart and never enter the app's coverage or gap ledger. Its container text is masked, and the writes it sends outside the app are refused in every mode but destructive — unless the user names that origin as a trusted embed (a provider in test mode, say): pass it in `scout_attach {trustedEmbeds: ["https://…"]}` and, in safe-write only, its writes go out. Never add an origin the user did not name. The FRAMES line names frames that were not read; say in your summary that their contents were not explored.
+5. **Native-user behaviours.** `scout_type {ref, textValue}` (or its alias `value`, matching `scout_select` and a plan step) APPENDS when a field already has content (menu clicks often insert @-mention chips or commands into composers — appending preserves them; the result reports what was already there); pass `replace=true` only to deliberately clear, and `pressEnter=true` to submit from the field the way a user would. Before concluding a badge, icon, or "N errors" indicator *does nothing*, `scout_hover` it — tooltips and hover cards are invisible to snapshots and clicks, and hover output includes what appeared. In HEADED mode (`scout_attach {headed:true}`, which the user asks for when they want to watch) the user's physical mouse competes with the synthetic pointer: if a hover reveals nothing and the finding matters, ask the user to move their mouse off the browser window and retry before filing. **Scroll long pages with `scout_scroll`** — the design audit and snapshot measure at the current scroll position, so judge deep sections by scrolling then re-auditing; it refuses to scroll where a real user couldn't and reports SCROLL LOCKED (the leaked modal scroll-lock that silently amputates everything below the fold — snapshots also flag it passively as an OVERLAY line), and scrolling triggers lazy-loaded content whose failures surface as fresh oracle violations. Elements fully clipped inside an overflow-hidden container are flagged UNREACHABLE in GEOMETRY issues — no amount of scrolling reveals them; that's a high-value layout bug, distinct from merely below-the-fold content. Controls held outside the visible width of a horizontally scrolling container (a wide table's action column) are one GEOMETRY line per container, `N controls are scrolled out of view inside a horizontally scrolling container …`: reachable by scrolling that container sideways, and worth a look rather than a defect unless the project keeps row actions in view. **A page can hold SEVERAL independent scroll regions** and plain `scout_scroll` moves the largest one, so a sidebar nav beside a taller main pane never budges: pass `scout_scroll {target:"testid=…"}` to scroll one region. Never report a nav item, tab or list row as missing/truncated until you have scrolled ITS container — content scrolled out of a secondary pane looks exactly like content that was cut off.
 6. **The rest of the input vocabulary.** `scout_select` sets a `<select>` option by value or visible label — use it rather than clicking a native dropdown open, which does not render as page DOM. `scout_press` sends a real key to the focused element (`Escape` to dismiss a modal, `Tab` to walk focus order, `Enter` to submit from a field); it is also how the keyboard-only pass at `extensive` is performed, and it vets the focused control first so a destructive action cannot be triggered blind in read-only mode. **`scout_upload {ref}` attaches a file the way a user does** — `ref` is a visible `<input type=file>` (snapshots list these with role `file`; `scout_type` on one redirects here) OR the button/label/dropzone that opens the file chooser (the chooser is intercepted and answered — that is how the hidden input behind a styled "Choose file" control is reached); omit `ref` when the page has exactly one file input, hidden or not (snapshots disclose hidden ones on a FILE INPUTS line). Nothing needs to exist on disk: a small VALID fixture is generated in memory, its kind inferred from the input's `accept` attribute or chosen with `fixture` (`pdf`, `png`, `txt`, `csv`, `json`); `filePath` uploads a real file but must live inside the attached project (fenced, like navigation is fenced to the origin); `name` overrides the filename. The result flags a file that violates `accept` (a mismatch the app then ACCEPTS is a validation finding), warns when the app cleared the input after selection, and says whether a state-changing request fired on selection — if none did, either click the form's submit or read the next snapshot for a client-side rejection. Plans take `{action:"upload", target, value:"pdf"}` steps (`target` required). When the input or its trigger was addressed by `ref`, the gap ledger counts an attached-but-unsent file as filled-never-submitted; the ref-less path has no listed element to mark.
 7. **Say what you are doing: `task` is required before a tool acts.** A session shows two lines to whoever is watching. Its **objective** is the whole remit you were given, set once at `scout_attach {objective}` ("Admin lane: §2 registers, §7 plan gating", "Approve and reject orders as a manager"). Its **task** is what you are doing *right now*, and every tool that changes the app or the page — `scout_navigate`, `scout_back`, `scout_click`, `scout_type`, `scout_select`, `scout_press`, `scout_upload`, `scout_run_plan` — takes it: a few words for the batch in front of you ("Filtering the documents register by status", "Filling the deviation form with invalid dates", "Signing in as QA_Team"). Say what you are DOING, not what you are checking — "§2.4 filtering narrows the set and is reflected in the URL" is the acceptance criteria, which is the result you will judge, not the batch you are running; naming the item is fine ("§2.4: filtering the documents register"). The task STAYS SET until you pass a different one, so a batch costs a few words, not one per call — pass a fresh one whenever you move on. Acting with none standing is refused: the person watching would otherwise see a session clicking through their app with nothing to say why. `scout_journey {action:"start", goal:…}` sets the task too while it runs — use a journey when you are MEASURING a whole user task, the parameter for everything else.
 
@@ -106,7 +106,7 @@ The engine is self-healing (orphaned browsers reaped, wedged calls time out with
 - **Always pass `evidence`** to `scout_finding` — a canonical machine signature like `GET /api/reports/dashboard 403` or `widget dashboard-summary-widget shows 0`. It's what deduplicates the same bug across runs when titles get rephrased.
 - File judgment findings too: confusing flows, no-feedback actions, state lost on refresh, permission leaks (low-privilege role reaching admin surface), `missing-testid` (low, where the project's test-id convention is known; worth a look otherwise), unnamed interactables (a11y, low).
 - Respect refusals — never retry or route around a policy refusal; note it and move on.
-- Duplicates are fine; `scout_finding` dedups across runs.
+- Duplicates are fine; `scout_finding` dedups across runs. When it says a model judge merged your filing into another finding, your title, category, severity and evidence are kept on that finding; refile only if it is a different defect, with a title that says what differs. Pass `scout_attach {dedup: "judge"}` only when the user asks for model-judged dedup: it sends finding titles, categories and evidence, and the page's path, to a model provider, and needs a key in the server's environment.
 
 ## Finishing