scenescout 3.15.0 → 3.16.0

package/dist/mcp-server.js

@@ -29,7 +29,10 @@
  *   a loopback-only live view shows what each one is looking at
  *   (`scenescout watch <project>`, engine/live.ts, ADR 7).
  */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { spawn } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -37,8 +40,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { BrowserEngine } from "./engine/browser.js";
+import { readyBrowser } from "./engine/launch.js";
+import { defaultEngine } from "./browsers.js";
+import { downloadBrowsers, presentBrowsers } from "./installer.js";
 import { reapOrphanBrowsers } from "./engine/reaper.js";
-import { FINDING_CATEGORIES, isWorthALook, MemoryStore, mergeableCategories, redactSecrets } from "./engine/memory.js";
+import { describeMerge, 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";
@@ -48,18 +54,25 @@ import { SessionQueue, withWatchdog } from "./engine/dispatch.js";
 import { FIXTURE_KINDS } from "./engine/fixtures.js";
 import { feedForSession, LIVE_ENV, writeStatusFile, LIVE_TOKEN_FILE, liveEngines, liveTokenFileName, pidAlive, statusFileName, LiveServer, StatusBoard, } from "./engine/live.js";
 import { formatBriefs, MAX_LANES, planLanes } from "./engine/brief.js";
+import { decideOpen, OPEN_CHOICES, OPEN_ENV, openChoiceFromEnv, openInBrowser } from "./engine/open.js";
 import { DEFAULT_EXPIRY_MARGIN_MINUTES, DEFAULT_RUN_MINUTES, judgeProfileFile } from "./engine/expiry.js";
-import { loginCommand } from "./engine/profiles.js";
-import { formatNeverSubmittedEmpty } from "./engine/forms.js";
-import { computeGaps, formatRouteCoverage, formatUnchosenOptions, generateReport, replayDocument, reportEvidence } from "./engine/report.js";
+import { parseLoginArgs } from "./engine/profiles.js";
+import { LOGIN_WINDOW_MAX_MS, savedLine, startLoginWindow } from "./login-run.js";
+import { LoginWindows, WAIT_SAYS } from "./engine/signed-in.js";
+import { computeGaps, coverageView, formatRouteCoverage, generateReport, replayDocument, reportEvidence } from "./engine/report.js";
+import { DEFAULT_REPORT_AUDIENCE, REPORT_AUDIENCES } from "./engine/plain.js";
 import { describeVerdict, formatWorklist, unknownIds, VERDICTS, verifyWorklist } from "./engine/verify.js";
+import { CRITERION_VERDICTS, findCriterion, formatCriteriaForLanes, formatReading, isTicketFileName, judgeCriterion, MAX_CRITERION_FINDINGS, MAX_REASON, MAX_TICKET_FILE_BYTES, MAX_TICKET_TEXT, MAX_TICKETS, NOT_TESTED_REASONS, parseTickets, TICKET_FILE_EXTENSIONS, } from "./engine/tickets.js";
 import { ACTION_TIMEOUT_ENV, DEFAULT_ACTION_TIMEOUT_MS, DEFAULT_CRAWL_NAV_TIMEOUT_MS, DEFAULT_NAV_TIMEOUT_MS, LIMIT_BOUNDS, NAV_TIMEOUT_ENV, watchdogFor, } from "./engine/limits.js";
+import { MAX_READ_POSTS, READ_POSTS_ENV } from "./engine/policy.js";
+import { chooseProjectFolder, PROJECTS_DIR_ENV, workspaceFromRoots } from "./engine/project-folder.js";
 import { RECORD_MAX_FRAMES, resolveFrame } from "./engine/replay.js";
 import { describePace, normalizePace } from "./engine/settle.js";
 import { needsTask, taskRefusal, TASK_MAX } from "./engine/task.js";
 import { EXPLORE_PROMPT_ARGUMENTS, explorePrompt, loadPlaybook, PLAYBOOK_PROMPT, PLAYBOOK_TOOL, SERVER_INSTRUCTIONS } from "./playbook.js";
 import { formatScan, scanProject } from "./scan.js";
-import { CAPTURE_MARGIN, CAPTURES_DIRNAME, captureFileName, captureResultText, MAX_CAPTURE_MARGIN } from "./engine/capture.js";
+import { CAPTURE_MARGIN, CAPTURES_DIRNAME, captureFileName, captureResultText, describePicture, EVIDENCE_ENV, EVIDENCE_LIMITS, EVIDENCE_MARGIN, EVIDENCE_MODES, evidenceFrame, evidenceSettings, findingPicturePath, MAX_CAPTURE_MARGIN, RECORD_ENV, recordChoice, returnsInline, } from "./engine/capture.js";
+import { decodePng, fitPicture } from "./engine/png.js";
 /** Live sessions: each name owns an independent BrowserEngine (browser + auth). */
 const engines = new Map();
 /**
@@ -254,8 +267,10 @@ function reportExtras(eng) {
         designAudits: eng.memory?.auditsThisRun ?? eng.designAuditCount,
         createdResources: eng.createdResources,
         unvisitedRoutes: unvisited,
+        knownRoutes: all,
         mode: eng.mode,
         trustedEmbeds: [...eng.trustedEmbeds],
+        readPosts: eng.readPosts.map((e) => e.entry),
         policyAttributed: eng.oracleLog.policyAttributed,
         version: PKG_VERSION,
         attachedSessions: [...engines.keys()],
@@ -334,6 +349,28 @@ function liveLine() {
     return (`\nLive view: http://127.0.0.1:${liveAddress.port}/${liveAddress.token}/ — give this address to the user so they can watch every session ` +
         `(current tool, page thumbnail, optional live stream). It opens on this machine only and cannot act on the run.`);
 }
+/** What each session's attach decided to open (engine/open.ts). scout_report reads it for the report. */
+const openDecisions = new Map();
+/** The live view is one address for every session, so it is opened once per server. */
+let liveOpened = false;
+/** Whether a result has named the setting that turns opening off; named once. */
+let openSettingNamed = false;
+/** Whether an attach has said why the live view was not opened; said once. */
+let openWhySaid = false;
+/** Open a target in the default browser and say so in a line for the tool result; a failure is said, never thrown. */
+function openForUser(what, target) {
+    const outcome = openInBrowser(target, {
+        platform: process.platform,
+        spawn: (command, args, options) => spawn(command, args, options),
+        onError: (why) => logLine(`could not open ${what}: ${why}`),
+    });
+    if (!outcome.ok)
+        return `\nCould not open ${what}: ${outcome.why}.`;
+    if (openSettingNamed)
+        return `\nOpened ${what} in the default browser.`;
+    openSettingNamed = true;
+    return `\nOpened ${what} in the default browser (${OPEN_ENV}=none, or scout_attach {open: "none"}, turns this off).`;
+}
 function flushStatus(dir) {
     // Not awaited on a tool call's hot path: status is best-effort observability
     // and must never add blocking filesystem latency there. The writer queues
@@ -451,11 +488,17 @@ function serializedPerSession(label, fn, timeoutMs = 60_000) {
         return sessionQueue.run(session, exec);
     };
 }
+const requestExtra = new AsyncLocalStorage();
+function asRequestExtra(value) {
+    return value && typeof value.sendNotification === "function" ? value : undefined;
+}
 /** Control-plane tools (scout_scan/scout_session/scout_close-all) don't target one browser — their own tiny chain keeps them off session queues without racing each other. */
 let controlChain = Promise.resolve();
 function serializedControl(fn) {
     return (...args) => {
-        const run = controlChain.then(() => fn(...args), () => fn(...args));
+        // The SDK passes the request's extra (progress token, notifications) after the arguments; it is kept for the call, as requestExtra.
+        const call = () => requestExtra.run(asRequestExtra(args[1]), () => fn(...args));
+        const run = controlChain.then(call, call);
         controlChain = run.catch(() => { });
         return run;
     };
@@ -568,7 +611,7 @@ server.registerTool("scout_lane_brief", {
                 runMs: (runMinutes ?? DEFAULT_RUN_MINUTES) * 60_000,
                 marginMs: (expiryMarginMinutes ?? DEFAULT_EXPIRY_MARGIN_MINUTES) * 60_000,
                 role: eng.auth.role,
-                rerun: loginCommand(eng.auth.role, eng.baseUrl),
+                rerun: eng.reloginCommand(eng.auth.role),
             });
             if (verdict.kind === "refuse")
                 return errorText(new Error(verdict.message));
@@ -578,7 +621,11 @@ server.registerTool("scout_lane_brief", {
         const all = routes && routes.length > 0 ? routes : eng.allKnownRoutes();
         const briefs = planLanes(all, lanes, { goal, mode: eng.mode, role: eng.role });
         laneLedger.nameBriefed(briefs.map((b) => b.lane), (s) => engines.has(s));
-        return text(expiryNote + formatBriefs(briefs, { goal, mode: eng.mode, role: eng.role, roleProfile: eng.auth.kind === "role" }), session);
+        // A run given tickets tells every lane which criteria it answers.
+        const criteria = eng.memory ? formatCriteriaForLanes(eng.memory.ticketsThisRun().tickets) : "";
+        return text(expiryNote +
+            formatBriefs(briefs, { goal, mode: eng.mode, role: eng.role, roleProfile: eng.auth.kind === "role" }) +
+            (criteria ? `\n${criteria}` : ""), session);
     }
     catch (err) {
         return errorText(err);
@@ -645,7 +692,7 @@ server.registerTool("scout_lane_report", {
                     .map((u) => `  · ${u}`)
                     .join("\n") +
                 (unfiled.length > MAX_UNFILED_NAMED ? `\n  … +${unfiled.length - MAX_UNFILED_NAMED} more` : "") +
-                `\nFile each with scout_finding (the same evidence), or confirm which finding already covers it, before closing the lane's session. A judged defect that is never filed is not in the report.`
+                `\nFile each with scout_finding (the same evidence), or have the lane name the finding's id in the decision's "finding", before closing the lane's session. A judged defect that is never filed is not in the report.`
             : "";
         laneLedger.fold(lane, engines.get(lane)?.attached === true);
         // A lane that lost its sign-in and re-attached from its role's profile
@@ -681,10 +728,14 @@ server.registerTool("scout_scan", {
     }
 }));
 server.registerTool("scout_attach", {
-    description: "Launch a browser and attach to a running web app. First attach in this conversation and you have read neither the SceneScout skill nor scout_playbook? Call scout_playbook before this. Write policy is enforced at the NETWORK layer: mode='observe' blocks EVERY request that is not a GET (login and token refresh excepted) — choose it for a target that holds real data, where even an ordinary form submission would create a record; mode='read-only' (default) blocks destructive-labeled elements AND all PUT/PATCH/DELETE + destructive POSTs, but lets ordinary form POSTs through; mode='safe-write' allows creating data and permits updates/deletes ONLY on resources this session created (use when the user wants create/edit flows tested); mode='destructive' allows everything — ONLY when the user explicitly confirmed a disposable/seeded environment. Pass `role` to sign in with a login the user saved by `scenescout login <url> --role <name>`, or a Playwright storage-state JSON as storageStatePath. Pass `session` to keep MULTIPLE roles alive at once (one browser each, genuinely concurrent) for collaboration testing — target each directly with every tool's `session` param, or use scout_session to set which one is the default; coverage and findings merge into one project memory.",
+    description: "Launch a browser and attach to a running web app. First attach in this conversation and you have read neither the SceneScout skill nor scout_playbook? Call scout_playbook before this. Write policy is enforced at the NETWORK layer: mode='observe' blocks EVERY request that is not a GET (login and token refresh excepted, and POSTs the user named in readPosts) — choose it for a target that holds real data, where even an ordinary form submission would create a record; mode='read-only' (default) blocks destructive-labeled elements AND all PUT/PATCH/DELETE + destructive POSTs, but lets ordinary form POSTs through; mode='safe-write' allows creating data and permits updates/deletes ONLY on resources this session created (use when the user wants create/edit flows tested); mode='destructive' allows everything — ONLY when the user explicitly confirmed a disposable/seeded environment. Pass `role` to sign in with a login the user saved by `scenescout login <url> --role <name>`, or a Playwright storage-state JSON as storageStatePath. Pass `session` to keep MULTIPLE roles alive at once (one browser each, genuinely concurrent) for collaboration testing — target each directly with every tool's `session` param, or use scout_session to set which one is the default; coverage and findings merge into one project memory.",
     inputSchema: {
         url: z.string().describe("Base URL of the running app, e.g. http://localhost:3000"),
-        projectPath: z.string().describe("Absolute path to the project (memory + report live in .scenescout/ here)"),
+        projectPath: z
+            .string()
+            .optional()
+            .describe("Absolute path to the project (memory + report live in .scenescout/ here). Pass it whenever you have a project or working folder. " +
+            `Omitted: the client's workspace folder, else a folder per tested site under the user's documents folder (Documents/SceneScout/<host>/, or ${PROJECTS_DIR_ENV}), which the result names — tell the user where it is.`),
         storageStatePath: z.string().optional().describe("Optional Playwright storage-state JSON path for authenticated exploration. Not with `role`."),
         role: z
             .string()
@@ -701,7 +752,7 @@ server.registerTool("scout_attach", {
         browser: z
             .enum(["chromium", "firefox", "webkit"])
             .optional()
-            .describe("Browser to drive. Default: the SCENESCOUT_BROWSER environment variable, else chromium. firefox and webkit must be downloaded first (scenescout install --browser-only --browsers firefox). Use them for a cross-browser pass; stay on chromium otherwise."),
+            .describe("Browser to drive. Default: the SCENESCOUT_BROWSER environment variable, else chromium. A build that is not on disk is downloaded on this attach, once, except in CI or with SCENESCOUT_BROWSER_DOWNLOAD=off, where the attach names the command to run. Use firefox or webkit for a cross-browser pass; stay on chromium otherwise."),
         viewportWidth: z.number().int().min(320).max(3840).optional().describe("Viewport width (default 1280); use e.g. 390 for a mobile pass"),
         viewportHeight: z.number().int().min(480).max(2400).optional().describe("Viewport height (default 900)"),
         objective: z
@@ -729,11 +780,22 @@ server.registerTool("scout_attach", {
             .optional()
             .describe('Origins of embedded frames (e.g. "https://pay.example.com") whose writes out of the app may go out — ONLY when the user named them, typically a provider in test mode, and only in safe-write mode. ' +
             "Never add one yourself. Hostile input, repeated-click probes and uploads stay refused in them."),
+        readPosts: z
+            .array(z.string().max(300))
+            .max(MAX_READ_POSTS)
+            .optional()
+            .describe(`POST endpoints that only read, e.g. ["POST /api/search", "POST https://api.example.com/reports/query"], which observe mode then lets out — ONLY when the user named them. Never add one yourself, even when the gap ledger lists a refused POST: ask the user. ` +
+            `Exact paths; * stands for one path segment. Still refused when the path or body looks destructive or the body is a GraphQL mutation. Observe mode only. Default: the ${READ_POSTS_ENV} environment variable, else none.`),
         record: z
             .boolean()
-            .default(false)
+            .optional()
             .describe("Keep a frame of the page after every action, under .scenescout/recordings/, and show it beside that step in report.html. " +
-            "Off by default: a recording is pictures of the app under test sitting in the project folder. Turn it on for QA work, where the run is evidence and not only a report."),
+            `Default: the ${RECORD_ENV} environment variable (on or off), else off: a recording is pictures of the app under test sitting in the project folder. Turn it on for QA work, where the run is evidence and not only a report.`),
+        evidence: z
+            .enum(EVIDENCE_MODES)
+            .optional()
+            .describe("What happens to the picture each scout_finding takes of what it is about. 'inline': kept under .scenescout/recordings/, shown in report.html, and returned in the scout_finding result so the conversation shows it. 'file': kept and shown in the report only. 'off': none taken. " +
+            `Default: the ${EVIDENCE_ENV} environment variable, else 'inline', or 'file' in a CI job. Pictures are bounded in size and in how many one session returns (see the configuration reference).`),
         actionTimeoutMs: z
             .number()
             .int()
@@ -760,9 +822,20 @@ server.registerTool("scout_attach", {
             "'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."),
+        open: z
+            .enum(OPEN_CHOICES)
+            .optional()
+            .describe(`Open the live view (on this attach) and/or report.html (when scout_report writes it) in the user's default browser: 'live', 'report', 'both' or 'none'. ` +
+            `Default: the ${OPEN_ENV} environment variable, else 'both' on a local desktop session (headed or headless) and 'none' in CI, over SSH, or with no display. ` +
+            "Pass it only when the user asked for something other than the default."),
     },
-}, serializedControl(async ({ url, projectPath, storageStatePath, role, mode, headed, browser, viewportWidth, viewportHeight, objective, task, record, trustedEmbeds, paceMs, actionTimeoutMs, navTimeoutMs, session, dedup, }) => {
+}, serializedControl(async ({ url, projectPath, storageStatePath, role, mode, headed, browser, viewportWidth, viewportHeight, objective, task, record, evidence, trustedEmbeds, readPosts, paceMs, actionTimeoutMs, navTimeoutMs, session, dedup, open, }) => {
     try {
+        // Settled first: a refusal leaves the default session as it was.
+        const folder = await projectFolderFor(url, projectPath);
+        if ("refused" in folder)
+            return errorText(new Error(folder.refused));
+        projectPath = folder.dir;
         const target = session ?? activeName;
         if (session) {
             activeName = session;
@@ -824,15 +897,25 @@ server.registerTool("scout_attach", {
         // Moving this session to another project leaves its old one; if it was
         // the last session there, that run is over. Re-attaching to the SAME
         // project is the same run, and keeps what the run has learned.
+        // Before anything changes: a SCENESCOUT_OPEN the server cannot use refuses the attach.
+        const opening = decideOpen(open ?? openChoiceFromEnv(process.env), {
+            env: process.env,
+            platform: process.platform,
+        });
         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 recording = recordChoice(record, process.env);
+        const pictures = evidenceSettings(evidence, process.env);
         const viewport = viewportWidth && viewportHeight ? { width: viewportWidth, height: viewportHeight } : undefined;
+        // The first attach on a machine without the browser downloads it here, once, rather than failing with a command to run.
+        const browserNote = await readyBrowserFor({ engine: browser ?? defaultEngine(process.env), headed: headed ?? false }, requestExtra.getStore());
         const out = await eng.attach({
             url,
             projectDir: projectPath,
+            projectChosen: folder.source === "default",
             storageStatePath,
             role,
             mode,
@@ -846,8 +929,9 @@ server.registerTool("scout_attach", {
             objective: objective ?? task,
             paceMs,
             task: objective ? task : undefined,
-            record,
+            record: recording,
             trustedEmbeds,
+            readPosts,
             actionTimeoutMs,
             navTimeoutMs,
             memoryStore: store,
@@ -859,18 +943,109 @@ server.registerTool("scout_attach", {
             await ensureLive(eng.memory.dir);
             writeStatus(target, "idle", "scout_attach");
         }
+        // A new attach is a new count of pictures returned.
+        evidenceFor.set(eng, { ...pictures, shown: 0 });
+        openDecisions.set(target, opening);
+        // The address holds the token, and goes only to this machine's opener: the live view's loopback and token rules are unchanged.
+        let openNote = "";
+        if (opening.live && liveAddress && !liveOpened) {
+            liveOpened = true;
+            openNote = openForUser("the live view", `http://127.0.0.1:${liveAddress.port}/${liveAddress.token}/`);
+        }
+        else if (!opening.live && liveAddress && !openWhySaid) {
+            // Once per server, so a person wondering why no window appeared is told how to change it.
+            openWhySaid = true;
+            openNote = `\nNot opened in a browser (${opening.why}); scout_attach {open} or ${OPEN_ENV} changes that.`;
+        }
         // Recording writes pictures of the app under test into the project, so
         // a run doing it says where they go rather than leaving the person to
         // find a folder of screenshots later.
-        const recordNote = record && eng.memory?.dir
+        const recordNote = recording && 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 + dedupNote + describePace(eng.pace) + (engines.size > 1 ? `\n${sessionLines()}` : "") + liveLine(), target);
+        const picturesNote = pictures.mode !== "off" && eng.memory?.dir
+            ? `\n📷 FINDING PICTURES: ${pictures.mode} (${pictures.source}): each scout_finding keeps a picture of what it names under ${path.join(eng.memory.dir, "recordings")}/ for report.html${pictures.mode === "inline" ? `, and returns the first ${pictures.inlineMax} in its result` : ""}.`
+            : "";
+        return text(browserNote +
+            out +
+            (folder.note ? `\n\n${folder.note}` : "") +
+            conflictNote +
+            recordNote +
+            picturesNote +
+            dedupNote +
+            describePace(eng.pace) +
+            (engines.size > 1 ? `\n${sessionLines()}` : "") +
+            liveLine() +
+            openNote, target);
     }
     catch (err) {
         return errorText(err);
     }
 }));
+/**
+ * readyBrowser with the real download, returning the line that opens the
+ * attach's answer when it downloaded (empty when it did not). Each line goes
+ * to stderr and, when the client asked for progress, as a progress
+ * notification; the last one is repeated while the download runs, so a client
+ * that extends its timeout on progress keeps waiting.
+ */
+async function readyBrowserFor(need, extra) {
+    const token = extra?._meta?.progressToken;
+    let progress = 0;
+    let last = "";
+    const notify = (message) => {
+        if (token === undefined || !extra)
+            return;
+        extra.sendNotification({ method: "notifications/progress", params: { progressToken: token, progress: ++progress, message } }).catch((err) => {
+            logLine(`progress notification failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
+    const say = (line) => {
+        last = line;
+        logLine(line);
+        notify(line);
+    };
+    const note = await readyBrowser(need, {
+        env: process.env,
+        present: presentBrowsers,
+        say,
+        download: async (targets) => {
+            const heartbeat = setInterval(() => notify(last), 10_000);
+            try {
+                return await downloadBrowsers(targets, "stderr");
+            }
+            finally {
+                clearInterval(heartbeat);
+            }
+        },
+    });
+    return note ? `${note}\n\n` : "";
+}
+/**
+ * The folder an attach keeps its files in (engine/project-folder.ts): the
+ * projectPath given, else the client's workspace folder, else a folder per
+ * tested site. Only a client that offers roots is asked for them.
+ */
+async function projectFolderFor(url, given) {
+    let workspace = null;
+    if (given === undefined && server.server.getClientCapabilities()?.roots) {
+        try {
+            workspace = workspaceFromRoots((await server.server.listRoots(undefined, { timeout: 3000 })).roots);
+        }
+        catch (err) {
+            logLine(`the client offers a workspace but did not list it (${err.message}); using the default folder`);
+        }
+    }
+    const userDirsFile = path.join(os.homedir(), ".config", "user-dirs.dirs");
+    const userDirs = process.platform === "linux" && fs.existsSync(userDirsFile) ? fs.readFileSync(userDirsFile, "utf8") : undefined;
+    return chooseProjectFolder({
+        given,
+        workspace,
+        url,
+        home: { platform: process.platform, homedir: os.homedir(), env: process.env, userDirs },
+        exists: fs.existsSync,
+    });
+}
 /** 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. */
@@ -904,6 +1079,61 @@ function configureDedup(store, asked) {
     store.dedupOff = undefined;
     return plan.note;
 }
+/** Each session's finding-picture settings from its last attach, and how many pictures its results have carried since. */
+const evidenceFor = new WeakMap();
+/**
+ * Take, bound and keep a filed finding's picture (capture.ts decides whether
+ * and of what; png.ts fits it). Returns the line the result adds and, when the
+ * result carries it, the picture. A picture that cannot be taken or kept never
+ * fails the filing, which is already recorded: the line says why there is none.
+ */
+async function findingPicture(eng, filed, ref) {
+    const settings = evidenceFor.get(eng);
+    const dir = eng.memory?.dir;
+    if (!settings || !dir)
+        return { line: "" };
+    const { finding, isNew } = filed;
+    const plan = evidenceFrame({
+        mode: settings.mode,
+        ref,
+        pageOpen: eng.alive,
+        isNew,
+        hasPicture: !!finding.picture,
+        regressed: !isNew && !!finding.regressedAt && finding.regressedAt === finding.foundAt,
+    });
+    if (!plan.take)
+        return { line: settings.mode === "off" ? "" : `\nNo picture taken: ${plan.why}.` };
+    try {
+        const shot = await eng.captureEvidence(plan.frame === "element" ? plan.ref : undefined, EVIDENCE_MARGIN);
+        const fitted = fitPicture(decodePng(shot.png), settings.maxPx, settings.maxBytes);
+        if (!fitted)
+            return { line: `\nNo picture kept: none small enough to be readable fits in ${Math.round(settings.maxBytes / 1024)} KB.` };
+        const rel = findingPicturePath(eng.sessionKey, finding.id);
+        const file = path.join(dir, rel);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, fitted.png);
+        const picture = {
+            width: fitted.width,
+            height: fitted.height,
+            frame: shot.frame,
+            ...(shot.label ? { label: shot.label } : {}),
+            at: new Date().toISOString(),
+        };
+        eng.memory?.setPicture(finding.id, rel, picture);
+        const said = `\n📷 Picture (${describePicture(picture)}${fitted.shrunk ? ", shrunk to fit" : ""}): ${file}${shot.note ? ` — ${shot.note}` : ""}`;
+        if (!returnsInline(settings.mode, settings.shown, settings.inlineMax)) {
+            const capped = settings.mode === "inline"
+                ? ` Not shown here: this session has returned its ${settings.inlineMax} (${EVIDENCE_LIMITS.inline.env} sets how many); it is in report.html.`
+                : "";
+            return { line: said + capped };
+        }
+        settings.shown += 1;
+        return { line: said, image: { type: "image", data: fitted.png.toString("base64"), mimeType: "image/png" } };
+    }
+    catch (err) {
+        return { line: `\nNo picture kept: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 /** What scout_finding tells the agent about what filing did. */
 function filedText(filed, category) {
     const { finding, isNew, promoted } = filed;
@@ -918,7 +1148,7 @@ function filedText(filed, category) {
         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.`;
+    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} run${finding.runs === 1 ? "" : "s"}${filed.merge?.sameRun ? " (already filed this run, so the count did not change)" : ""}.${filed.merge ? describeMerge(filed.merge, finding.convention) : ""} 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:"];
@@ -927,6 +1157,114 @@ function sessionLines() {
     }
     return lines.join("\n");
 }
+// Signing in from the conversation: a window the person signs in in, watched
+// in the background, so a call need not last as long as the person takes and
+// a second call picks up the same window. One per project and role.
+const pendingLogins = new LoginWindows(LOGIN_WINDOW_MAX_MS);
+/** How long one scout_login call waits for the person, by default and at most, in seconds. */
+const LOGIN_WAIT_DEFAULT_S = 120;
+const LOGIN_WAIT_MAX_S = 600;
+/** How often a waiting call tells a client that asked for progress that it is still going, in ms. */
+const LOGIN_PROGRESS_EVERY_MS = 10_000;
+server.registerTool("scout_login", {
+    description: "Open a visible browser window for the USER to sign in to the app as a role, and save that sign-in for scout_attach { role }. " +
+        "Use it when an attach is refused because no sign-in is saved for the role, or the saved one has expired. " +
+        'Tell the user first, in plain words: "A browser window is opening. Sign in there as you normally would; it closes by itself once you are in." ' +
+        "The window saves once the user is back on the app with a new session (a round trip through a single sign-on provider is followed, not taken for the end) and closes. " +
+        "Never type credentials into it yourself. Returns once signed in and saved, or after waitSeconds with the window still open: then call scout_login again with the same role to keep waiting. " +
+        "Closing the window saves nothing. Needs a desktop: on a machine with no display, ask the user to run `scenescout login <url> --role <name>` where they can see the window.",
+    inputSchema: {
+        url: z.string().describe("Where to sign in: the app's address or its sign-in page, e.g. http://localhost:3000/login"),
+        role: z.string().max(40).describe("The name to save the sign-in under, e.g. admin; scout_attach { role } signs in with it"),
+        projectPath: z
+            .string()
+            .optional()
+            .describe("Absolute path to the project (the sign-in is saved in .scenescout/auth/ here), as for scout_attach. Omitted: the same folder an attach with no projectPath uses for this site, which the result names."),
+        browser: z
+            .enum(["chromium", "firefox", "webkit"])
+            .optional()
+            .describe("Browser to open. Default: the SCENESCOUT_BROWSER environment variable, else chromium"),
+        successUrl: z
+            .string()
+            .max(500)
+            .optional()
+            .describe("Only when the user says how to tell: signed in once the URL's path contains this, or the URL starts with it (an absolute URL), instead of when a new session appears"),
+        waitSeconds: z
+            .number()
+            .int()
+            .min(1)
+            .max(LOGIN_WAIT_MAX_S)
+            .optional()
+            .describe(`How long this call waits for the user before returning with the window still open (default ${LOGIN_WAIT_DEFAULT_S})`),
+    },
+}, async (args, extra) => {
+    try {
+        // The folder an attach with no projectPath would use, so the attach after this finds the sign-in.
+        const folder = await projectFolderFor(args.url, args.projectPath);
+        if ("refused" in folder)
+            return errorText(new Error(folder.refused));
+        const projectDir = path.resolve(folder.dir);
+        const where = folder.note ? `\n\n${folder.note}` : "";
+        const parsed = parseLoginArgs([args.url, "--role", args.role, ...(args.browser ? ["--browser", args.browser] : []), ...(args.successUrl ? ["--success-url", args.successUrl] : [])], projectDir);
+        if (!parsed.ok)
+            return errorText(new Error(parsed.error));
+        const options = { ...parsed.options, projectDir };
+        const key = `${options.projectDir}\0${options.role}`;
+        const { window: pending, resumed } = await pendingLogins.get(key, () => startLoginWindow(options));
+        const waitMs = (args.waitSeconds ?? LOGIN_WAIT_DEFAULT_S) * 1000;
+        const progressToken = extra._meta?.progressToken;
+        let ticks = 0;
+        const ticker = progressToken !== undefined
+            ? setInterval(() => {
+                ticks += 1;
+                const p = pending.progress();
+                void extra
+                    .sendNotification({
+                    method: "notifications/progress",
+                    params: {
+                        progressToken,
+                        progress: ticks,
+                        message: `Waiting for the sign-in as "${options.role}": ${p.reason === "starting" ? "the window is opening" : WAIT_SAYS[p.reason]}`,
+                    },
+                })
+                    .catch((err) => console.error(`[scenescout] scout_login progress: ${err instanceof Error ? err.message : String(err)}`));
+            }, LOGIN_PROGRESS_EVERY_MS)
+            : undefined;
+        let timer;
+        let onAbort;
+        const outcome = await Promise.race([
+            pending.done,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve("waiting"), waitMs);
+            }),
+            new Promise((resolve) => {
+                onAbort = () => resolve("cancelled");
+                extra.signal.addEventListener("abort", onAbort, { once: true });
+            }),
+        ]).finally(() => {
+            clearTimeout(timer);
+            if (ticker)
+                clearInterval(ticker);
+            if (onAbort)
+                extra.signal.removeEventListener("abort", onAbort);
+        });
+        const differs = resumed && pending.url !== options.url ? ` (the window was opened at ${pending.url} by an earlier call; that one is still the one being watched)` : "";
+        if (outcome === "waiting" || outcome === "cancelled") {
+            const p = pending.progress();
+            return text(`Still waiting for the user to sign in as "${options.role}"${differs}: ${p.reason === "starting" ? "the window is opening" : WAIT_SAYS[p.reason]}. ` +
+                `The window stays open for up to ${LOGIN_WINDOW_MAX_MS / 60_000} minutes from when it opened. Call scout_login again with the same role to keep waiting, once the user says they are done or to check.` +
+                where, activeName);
+        }
+        // This call reports the outcome; the next call for the role opens a new window.
+        pendingLogins.reported(key, pending);
+        if (!outcome.ok)
+            return errorText(new Error(`nothing was saved for role "${options.role}": ${outcome.error}`));
+        return text(`${outcome.detected}\n${savedLine(options, outcome.saved)}${where}`, activeName);
+    }
+    catch (err) {
+        return errorText(err);
+    }
+});
 server.registerTool("scout_session", {
     description: "List live sessions, or set which one is the DEFAULT (used by any tool call that omits `session`). Prefer passing `session` directly on each tool call for multi-role work — that's what lets concurrent dispatch happen; scout_session is for sequential convenience (skip repeating `session` on every call) and for checking what's live. Both browsers stay live and authenticated regardless of which is default — re-snapshot a session after a break to see what changed while it was away.",
     inputSchema: {
@@ -976,7 +1314,7 @@ server.registerTool("scout_session", {
     }
 }));
 server.registerTool("scout_snapshot", {
-    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.",
+    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 a route returns a DIFF against its last snapshot, even after visiting elsewhere, and another tab of the same screen diffs against that screen's last tab; refs stay stable, including across a search or filter that rewrites only the query string. On a dense page, says what past the element cap was cut. Cheap — prefer this over screenshots.",
     inputSchema: {
         full: z.boolean().default(false).describe("Force a full element list instead of a diff"),
         session: sessionParam,
@@ -990,9 +1328,13 @@ server.registerTool("scout_snapshot", {
     }
 }));
 server.registerTool("scout_crawl", {
-    description: "Engine-side route sweep in ONE call: visits each path (default: all known routes not yet visited), records states into coverage memory, and returns a per-route health summary (HTTP status, element count, oracle violations, dead-ends, auth-redirects). Navigation-only — safe in read-only mode. Use this FIRST for broad coverage; explore interactively only where it flags problems or where journeys matter.",
+    description: "Engine-side route sweep in ONE call: visits each path (default: all known routes not yet visited), records states into coverage memory, and returns a per-route health summary (HTTP status, element count, what the main area holds, oracle violations, dead-ends, auth-redirects, and ERROR-VIEW or STILL-LOADING for a main area showing only an alert or a loading placeholder). Navigation-only — safe in read-only mode. Use this FIRST for broad coverage; explore interactively only where it flags problems or where journeys matter.",
     inputSchema: {
-        paths: z.array(z.string()).max(150).optional().describe("Paths to visit, e.g. ['/orders','/settings']. Omit to crawl all unvisited known routes."),
+        paths: z
+            .array(z.string())
+            .max(150)
+            .optional()
+            .describe("Paths to visit, e.g. ['/orders','/settings'], or full URLs on the attached origin. A path resolves from the origin's root, whatever page the session attached on. Omit to crawl all unvisited known routes."),
         session: sessionParam,
     },
 }, serializedPerSession("scout_crawl", async ({ paths }, session) => {
@@ -1004,7 +1346,7 @@ server.registerTool("scout_crawl", {
     }
 }, 600_000));
 server.registerTool("scout_run_plan", {
-    description: "Execute up to 20 actions in ONE call — use for mechanical sequences (fill a form, walk a wizard) so each step doesn't cost a round-trip. Targets resolve at execution time by semantic locator: 'testid=…', 'text=…', 'label=…' or 'role=button[name=Save]' (never snapshot refs). The same steps, saved to .scenescout/flows/<name>.json with expect-text / expect-url / expect-request steps added, are replayed by `scenescout check` on every pull request. An `upload` step attaches a file as scout_upload does (target required — the file input or the control that opens its chooser; value = a fixture kind or a project-relative path). The plan ABORTS at the first NEW oracle violation, policy refusal, or failed step, returning a transcript of how far it got; repeats of already-reported violations do not abort (they stay logged for the report).",
+    description: "Execute up to 20 actions in ONE call — use for mechanical sequences (fill a form, walk a wizard) so each step doesn't cost a round-trip. Targets resolve at execution time by semantic locator: 'testid=…', 'text=…', 'label=…' or 'role=button[name=Save]' (never snapshot refs). The same steps, saved to .scenescout/flows/<name>.json with expect-text / expect-url / expect-request steps added, are replayed by `scenescout check` on every pull request. An `upload` step attaches a file as scout_upload does (target required — the file input or the control that opens its chooser; value = a fixture kind or a project-relative path). The plan ABORTS at the first NEW oracle violation, policy refusal, or failed step, returning a transcript of how far it got; repeats of already-reported violations do not abort (they stay logged for the report). For a sweep of independent steps (tabs, filters, pages) pass onViolation \"continue\": a new error status or its console echo is listed on its step's line and the plan goes on; a failed step, a policy refusal or any other violation still stops it. A select step whose value names no option fails at once, listing the options.",
     inputSchema: {
         steps: z
             .array(z.object({
@@ -1022,30 +1364,39 @@ server.registerTool("scout_run_plan", {
         }))
             .min(1)
             .max(20),
+        onViolation: z
+            .enum(["stop", "continue"])
+            .default("stop")
+            .describe("stop (default): end the plan at the first new oracle violation, right for a form flow whose steps depend on each other. continue: list a new http_error or console_error on its step's line and run the next step, for a sweep of independent steps"),
         task: taskParam,
         objective: legacyObjectiveParam,
         session: sessionParam,
     },
-}, serializedPerSession("scout_run_plan", async ({ steps }, session) => {
+}, serializedPerSession("scout_run_plan", async ({ steps, onViolation }, session) => {
     try {
-        return text(await engineFor(session).runPlan(steps), session);
+        return text(await engineFor(session).runPlan(steps, onViolation ?? "stop"), session);
     }
     catch (err) {
         return errorText(err);
     }
 }, 240_000));
+const leaveParam = z
+    .boolean()
+    .optional()
+    .describe("How to answer if the page asks to confirm leaving (a beforeunload prompt over unsent input): true leaves and discards that input, false stays. Omitted, observe and read-only stay and other modes leave. The result says when the page asked.");
 server.registerTool("scout_click", {
     description: "Click an element by its ref from the latest scout_snapshot. Returns the outcome plus any oracle violations triggered. clicks=2 (or 3) probes IMPATIENT-USER behaviour: a rapid multi-click that fires the same state-changing request twice means the control is not guarded against double submission (button stays enabled, endpoint not idempotent) — use it on every important submit/create button once; the result says explicitly whether duplicates fired.",
     inputSchema: {
         ref: z.string().describe("Element ref, e.g. e12"),
         clicks: z.number().int().min(1).max(3).default(1).describe("1 = normal; 2-3 = rapid repeated clicks (double-submit probe)"),
+        leave: leaveParam,
         task: taskParam,
         objective: legacyObjectiveParam,
         session: sessionParam,
     },
-}, serializedPerSession("scout_click", async ({ ref, clicks }, session) => {
+}, serializedPerSession("scout_click", async ({ ref, clicks, leave }, session) => {
     try {
-        return text(await engineFor(session).click(ref, clicks ?? 1), session);
+        return text(await engineFor(session).click(ref, clicks ?? 1, leave), session);
     }
     catch (err) {
         return errorText(err);
@@ -1121,10 +1472,10 @@ server.registerTool("scout_hover", {
     }
 }));
 server.registerTool("scout_select", {
-    description: "Select an option in a <select> by ref.",
+    description: "Select an option in a <select> by ref. The value is matched against the options before anything is picked: an exact value, an exact label, either ignoring case, then a label it starts with. A value matching no option, or several, is refused at once with the options listed.",
     inputSchema: {
         ref: z.string(),
-        value: z.string().describe("Option value or label"),
+        value: z.string().describe("Option value or label (or the start of a label, when only one option has it)"),
         task: taskParam,
         objective: legacyObjectiveParam,
         session: sessionParam,
@@ -1138,23 +1489,24 @@ server.registerTool("scout_select", {
     }
 }));
 server.registerTool("scout_navigate", {
-    description: "Navigate to a URL or a path relative to the attached base URL (e.g. '/orders'). Also supports 'back' via scout_back.",
+    description: "Navigate to a path on the attached origin (e.g. '/orders') or a full URL on it. A path resolves from the origin's root, whatever page the session attached on. Also supports 'back' via scout_back.",
     inputSchema: {
         target: z.string().describe("Absolute URL or path like /settings"),
+        leave: leaveParam,
         task: taskParam,
         objective: legacyObjectiveParam,
         session: sessionParam,
     },
-}, serializedPerSession("scout_navigate", async ({ target }, session) => {
+}, serializedPerSession("scout_navigate", async ({ target, leave }, session) => {
     try {
-        return text(await engineFor(session).navigate(target), session);
+        return text(await engineFor(session).navigate(target, leave), session);
     }
     catch (err) {
         return errorText(err);
     }
 }));
 server.registerTool("scout_request", {
-    description: "Call the app's own API as this session, with the UI bypassed — the check that turns a hidden or disabled control into a proven refusal. A button that is not shown proves nothing; the same action refused by the server does. The fetch runs IN the page, so it carries the session's cookies and replays the Authorization header the app itself last sent, and it passes through the same interception the write policy is enforced on: in safe-write a mutation on a record this session did not create is refused here exactly as it would be for a click, and that refusal is the engine's safety net, not a finding. Returns the status line, the timing, the headers that decide whether two responses are truly identical (content-type, location, www-authenticate, retry-after, cache-control), and the body. Unlike a shell call, every request is recorded in the run's trail and its signature is what a finding should quote. Paths are fenced to the attached origin: use another session to reach another host.",
+    description: "Call the app's own API as this session, with the UI bypassed — the check that turns a hidden or disabled control into a proven refusal. A button that is not shown proves nothing; the same action refused by the server does. The fetch runs IN the page, so it carries the session's cookies and replays the Authorization header the app itself last sent, and it passes through the same interception the write policy is enforced on: in safe-write a mutation on a record this session did not create is refused here exactly as it would be for a click, and that refusal is the engine's safety net, not a finding. Returns the status line, the timing, the headers that decide whether two responses are truly identical (content-type, location, www-authenticate, retry-after, cache-control), and the body — its first 2000 characters, or the part named by select (one JSON value by path) or offset/limit (a window of characters). Unlike a shell call, every request is recorded in the run's trail and its signature is what a finding should quote. Paths are fenced to the attached origin: use another session to reach another host.",
     inputSchema: {
         path: z.string().min(1).max(2000).describe("Path on the attached origin, e.g. /api/things/12, or a full URL on that same origin"),
         method: z.enum(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]).optional().describe("Default GET"),
@@ -1163,13 +1515,48 @@ server.registerTool("scout_request", {
             .record(z.string().max(2000))
             .optional()
             .describe("Extra headers. One given here wins over the app's own, which is how a session tests a different or absent credential."),
+        select: z
+            .string()
+            .max(500)
+            .optional()
+            .describe('Return one value of a JSON response body by its dotted path, e.g. "stats.open" or "items.0.name", pretty-printed and up to 8000 characters. A path that is not there says which keys are.'),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .max(1_000_000)
+            .optional()
+            .describe("Return the body (or the selected value) from this character on. The body is cut at 2000 characters by default; the result names the next offset."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(8000)
+            .optional()
+            .describe("How many characters to return with offset or select. Default 2000, or 8000 for a select with no offset."),
         task: taskParam,
         objective: legacyObjectiveParam,
         session: sessionParam,
     },
 }, serializedPerSession("scout_request", async (args, session) => {
     try {
-        return text(await engineFor(session).apiRequest({ method: args.method, path: args.path, body: args.body, headers: args.headers }), session);
+        const view = { select: args.select, offset: args.offset, limit: args.limit };
+        return text(await engineFor(session).apiRequest({ method: args.method, path: args.path, body: args.body, headers: args.headers, view }), session);
+    }
+    catch (err) {
+        return errorText(err);
+    }
+}));
+server.registerTool("scout_network", {
+    description: "List the data requests (fetch and XHR) the current page made since its document loaded: method, path, status and time, oldest first, each marked with the route it was sent from when a client-side route change moved the page since. Use it when the page and the server seem to disagree — an empty list where the API has data, a stale value after a save — to tell a request that failed, one still pending and one that never ran apart. Read-only: it lists what the browser already saw and sends nothing. Credentials in query strings are redacted. A full page load starts a new list; scout_request's own calls are marked.",
+    inputSchema: {
+        contains: z.string().max(200).optional().describe("Only requests whose path contains this text, e.g. /api/things"),
+        limit: z.number().int().min(1).max(200).optional().describe("How many of the newest to list. Default 40."),
+        session: sessionParam,
+    },
+}, serializedPerSession("scout_network", async (args, session) => {
+    try {
+        return text(engineFor(session).listPageRequests({ contains: args.contains, limit: args.limit }), session);
     }
     catch (err) {
         return errorText(err);
@@ -1177,10 +1564,10 @@ server.registerTool("scout_request", {
 }));
 server.registerTool("scout_back", {
     description: "Go back in browser history (tests back-button resilience).",
-    inputSchema: { task: taskParam, objective: legacyObjectiveParam, session: sessionParam },
-}, serializedPerSession("scout_back", async (_args, session) => {
+    inputSchema: { leave: leaveParam, task: taskParam, objective: legacyObjectiveParam, session: sessionParam },
+}, serializedPerSession("scout_back", async ({ leave }, session) => {
     try {
-        return text(await engineFor(session).goBack(), session);
+        return text(await engineFor(session).goBack(leave), session);
     }
     catch (err) {
         return errorText(err);
@@ -1322,7 +1709,7 @@ server.registerTool("scout_capture", {
     }
 }));
 server.registerTool("scout_finding", {
-    description: "Record a structured finding (bug, UX issue, or improvement). Deduplicates across runs; automatically captures the recent action trace as the repro. Use for anything worth reporting: crashes, oracle violations you confirmed, dead ends, confusing UX, permission leaks, missing testids — and design-audit improvement opportunities (ux-polish) with their concrete measurements.",
+    description: "Record a structured finding (bug, UX issue, or improvement). Deduplicates across runs; automatically captures the recent action trace as the repro, and a picture of what it is about (the element `ref` names, else the viewport), kept for report.html and returned in this result as an image. Use for anything worth reporting: crashes, oracle violations you confirmed, dead ends, confusing UX, permission leaks, missing testids — and design-audit improvement opportunities (ux-polish) with their concrete measurements.",
     inputSchema: {
         severity: z.enum(["high", "medium", "low"]),
         category: z.enum(FINDING_CATEGORIES).describe("Pick the closest — use 'other' only when nothing fits"),
@@ -1338,9 +1725,14 @@ server.registerTool("scout_finding", {
             .max(LANE_CONVENTION_MAX)
             .optional()
             .describe("Only for a WORTH-A-LOOK finding: the observation is real, and it is a defect only under a convention of this project you cannot see. Name that convention, e.g. 'a 4px spacing scale' or 'test ids on every control'. The report lists it under \"Worth a look\", apart from the defects, and does not count it as one. Not for \"I could not tell\": leave that unfiled or look closer. Omit for a defect."),
+        ref: z
+            .string()
+            .max(20)
+            .optional()
+            .describe("The ref, from the latest scout_snapshot, of the element the finding is about. Its picture (the element plus a margin) is kept with the finding and shown in report.html. Omit it and the picture is the viewport."),
         session: sessionParam,
     },
-}, serializedPerSession("scout_finding", async ({ severity, category, title, detail, evidence, convention, }, session) => {
+}, serializedPerSession("scout_finding", async ({ severity, category, title, detail, evidence, convention, ref, }, session) => {
     try {
         const eng = engineFor(session);
         if (!eng.memory)
@@ -1358,34 +1750,40 @@ server.registerTool("scout_finding", {
         });
         if (filed.judgeError)
             logLine(`dedup judge: ${filed.judgeError}; the rule decided`);
-        return text(filedText(filed, category), session);
+        const picture = await findingPicture(eng, filed, ref);
+        const result = text(filedText(filed, category) + picture.line, session);
+        if (picture.image)
+            result.content.push(picture.image);
+        return result;
     }
     catch (err) {
         return errorText(err);
     }
 }));
 server.registerTool("scout_coverage", {
-    description: "Show exploration coverage: states visited across all runs, which elements remain unexercised, which options of a dropdown used this run no session has chosen yet, and which forms seen this run no session has submitted with every text field blank. Use to decide where to explore next and when the level's budget is satisfied.",
-    inputSchema: { session: sessionParam },
-}, serializedPerSession("scout_coverage", async (_args, session) => {
+    description: "Show exploration coverage: states visited, which elements remain unexercised, which options of a dropdown used this run no session has chosen yet, and which forms seen this run no session has submitted with every text field blank. Use to decide where to explore next and when the level's budget is satisfied. In a parallel run it shows this session's own work by default — the routes it reached this run and the forms it saw — so one lane is not handed another's gaps; scope:\"project\" shows every session's, each form and route tagged with the sessions that saw it.",
+    inputSchema: {
+        scope: z
+            .enum(["session", "project"])
+            .optional()
+            .describe("'session': only the routes this session reached this run and the forms it saw. 'project': every route in the memory, across runs and sessions. Default: 'session' when other sessions share this project, else 'project'."),
+        session: sessionParam,
+    },
+}, serializedPerSession("scout_coverage", async (args, session) => {
     try {
         const eng = engineFor(session);
-        if (!eng.memory)
+        const memory = eng.memory;
+        if (!memory)
             throw new Error("Not attached.");
-        const cov = eng.memory.coverage();
+        const shared = [...engines.values()].some((e) => e !== eng && e.memory === memory);
         const unvisited = eng.unvisitedKnownRoutes();
         const lines = [
-            ...(eng.memory.lastSaveError
+            ...(memory.lastSaveError
                 ? [
-                    `⚠ MEMORY WRITE FAILING: ${eng.memory.lastSaveError} — coverage/findings since the last successful write are NOT persisted to disk. If this doesn't clear on its own, check the project directory still exists and is writable.`,
+                    `⚠ MEMORY WRITE FAILING: ${memory.lastSaveError} — coverage/findings since the last successful write are NOT persisted to disk. If this doesn't clear on its own, check the project directory still exists and is writable.`,
                 ]
                 : []),
-            `States known: ${cov.states} · Elements exercised: ${cov.elementsExercised}/${cov.elementsTotal}${cov.embeds.total > 0 ? ` (plus ${cov.embeds.exercised}/${cov.embeds.total} inside other sites' frames, not counted)` : ""}`,
-            formatRouteCoverage(eng.allKnownRoutes(), unvisited),
-            `Unexercised elements by route:`,
-            ...cov.unexercised.slice(0, 25).map((u) => `  ${u.state}: ${u.keys.slice(0, 6).join(", ")}${u.keys.length > 6 ? ` … +${u.keys.length - 6}` : ""}`),
-            ...formatUnchosenOptions(eng.memory.unchosenOptions()),
-            ...formatNeverSubmittedEmpty(eng.memory.formsNeverSubmittedEmpty()),
+            ...coverageView(memory, eng.sessionKey, args.scope ?? (shared ? "session" : "project"), formatRouteCoverage(eng.allKnownRoutes(), unvisited)),
         ];
         return text(lines.join("\n"), session);
     }
@@ -1405,9 +1803,13 @@ server.registerTool("scout_report", {
             .enum(["index", "full"])
             .default("index")
             .describe("How much of the history to print. 'index' lists findings from earlier runs, and resolved ones, as a row each: id, severity, age, title. 'full' prints every one in full as before — on one project that was 1.75 MB against 113 KB, nearly half of it findings already fixed. Use 'full' when handing the document to someone who has no access to the memory."),
+        report: z
+            .enum(REPORT_AUDIENCES)
+            .default(DEFAULT_REPORT_AUDIENCE)
+            .describe("Which parts the report carries. 'both' (default): a plain-language section first — a short summary, then each problem with numbered steps, what was expected, what happened, its picture and its impact (blocks users, annoying, cosmetic), each with its technical detail folded beneath — followed by the technical report. 'qa': the plain section alone, for a tester or anyone not technical. 'dev': the technical report alone, as before the plain section existed. It applies to the files this call writes; the live view always shows both."),
         session: sessionParam,
     },
-}, serializedPerSession("scout_report", async ({ force, level, history }, session) => {
+}, serializedPerSession("scout_report", async ({ force, level, history, report }, session) => {
     try {
         const eng = engineFor(session);
         if (!eng.memory)
@@ -1444,6 +1846,7 @@ server.registerTool("scout_report", {
             routesTotal: all.length,
             designAudits: auditsThisRun,
             unvisitedRoutes: unvisited,
+            knownRoutes: all,
             mode: eng.mode,
         });
         if (lvl === "extensive" && gapList.length > 0) {
@@ -1458,21 +1861,25 @@ server.registerTool("scout_report", {
             return text(`NOT GENERATED — the '${lvl}' completion contract is unmet:\n\n${gates.join("\n\n")}\n\n` +
                 `Then call scout_report again. Pass force=true ONLY if the user explicitly capped the budget.`, session);
         }
-        const { path: p, summary } = generateReport(eng.memory, eng.oracleLog.all, {
+        const { path: p, summary, html, } = generateReport(eng.memory, eng.oracleLog.all, {
             history,
+            report,
             routesVisited: all.length - unvisited.length,
             routesTotal: all.length,
             designAudits: auditsThisRun,
             createdResources: eng.createdResources,
             unvisitedRoutes: unvisited,
+            knownRoutes: all,
             mode: eng.mode,
             trustedEmbeds: [...eng.trustedEmbeds],
+            readPosts: eng.readPosts.map((e) => e.entry),
             policyAttributed: eng.oracleLog.policyAttributed,
             // Which sessions are still open decides whether a quiet one is holding a browser, and how long its trailing idle runs.
             attachedSessions: [...engines.keys()],
         });
         void p;
-        return text(summary, session);
+        const openNote = html && openDecisions.get(session)?.report ? openForUser("the report", html) : "";
+        return text(summary + openNote, session);
     }
     catch (err) {
         return errorText(err);
@@ -1536,6 +1943,108 @@ server.registerTool("scout_verify", {
         return errorText(err);
     }
 }));
+// Answering the tickets: read their acceptance criteria, then record a verdict on each.
+server.registerTool("scout_tickets", {
+    description: "Read the tickets or acceptance criteria the person gave this run, pasted (`text`) or from a file (`path`), and keep them so the report answers each criterion: passed, failed or not tested. " +
+        'Recognises Given/When/Then scenarios, checklists, numbered and "AC1:" criteria, and lists under an "Acceptance criteria" heading; several tickets may be given at once. ' +
+        "A ticket with no recognisable criteria is reported as such, never guessed at. Returns each criterion's id (AC1, AC2, …) to judge it by with scout_criterion. Touches no browser.",
+    inputSchema: {
+        text: z.string().max(MAX_TICKET_TEXT).optional().describe("The tickets as pasted. Pass this or `path`."),
+        path: z
+            .string()
+            .optional()
+            .describe(`A ticket file to read (${TICKET_FILE_EXTENSIONS.join(", ")}), absolute or relative to the project folder. Pass this or \`text\`.`),
+        session: sessionParam,
+    },
+}, serializedPerSession("scout_tickets", async ({ text: pasted, path: file }, session) => {
+    try {
+        const eng = engineFor(session);
+        if (!eng.memory)
+            throw new Error("Not attached — attach first, so the tickets are kept with the project.");
+        if ((pasted === undefined) === (file === undefined))
+            return text("Pass the tickets as `text`, or a file as `path`: one of the two.", session);
+        let body = pasted ?? "";
+        let source = "pasted text";
+        if (file !== undefined) {
+            // The file a link points at is what is read, so its name is what is checked: a "notes.md" link to a key file is refused.
+            const full = fs.realpathSync(path.isAbsolute(file) ? file : path.resolve(path.dirname(eng.memory.dir), file));
+            if (!isTicketFileName(full))
+                return text(`Not read: a ticket file is one of ${TICKET_FILE_EXTENSIONS.join(", ")}. Paste anything else as \`text\`.`, session);
+            const stat = fs.statSync(full);
+            if (!stat.isFile())
+                return text(`Not read: ${full} is not a file.`, session);
+            if (stat.size > MAX_TICKET_FILE_BYTES)
+                return text(`Not read: ${full} is larger than ${MAX_TICKET_FILE_BYTES} bytes.`, session);
+            body = fs.readFileSync(full, "utf8");
+            source = path.basename(full);
+        }
+        if (!body.trim())
+            return text("Nothing to read: the tickets are empty.", session);
+        const parsed = parseTickets(body, source);
+        const kept = eng.memory.addTickets(parsed);
+        // Say what a bound left out, so a long backlog is never answered in part without a word.
+        const cuts = [
+            ...(body.length > MAX_TICKET_TEXT ? [`only the first ${MAX_TICKET_TEXT} characters were read`] : []),
+            ...(parsed.length >= MAX_TICKETS ? [`at most ${MAX_TICKETS} tickets are read at once`] : []),
+        ];
+        return text(formatReading(kept) + (cuts.length ? `\n\n⚠ Not everything was read: ${cuts.join("; ")}. Read the rest in another call.` : ""), session);
+    }
+    catch (err) {
+        return errorText(err);
+    }
+}));
+server.registerTool("scout_criterion", {
+    description: "Record whether one acceptance criterion of a ticket read with scout_tickets passed, failed or was not tested, with how sure you are. " +
+        "The link from a criterion to the findings that show it is YOUR judgement, stated with a confidence — never matched on words. " +
+        'A "fail" names the findings that show it (file them with scout_finding first); "not-tested" says why in untestedBecause. Recording the same criterion again from the same session replaces your earlier verdict. Touches no browser.',
+    inputSchema: {
+        ticket: z.string().min(1).describe('The ticket\'s id as scout_tickets gave it, e.g. "PROJ-12" or "T1"'),
+        criterion: z.string().min(1).describe('The criterion\'s id, e.g. "AC2" (or just "2")'),
+        verdict: z.enum(CRITERION_VERDICTS).describe('"pass", "fail" or "not-tested"'),
+        findings: z
+            .array(z.string())
+            .max(MAX_CRITERION_FINDINGS)
+            .optional()
+            .describe("Ids of the findings that show this criterion failing (required for a fail; may be given for a pass, none for not-tested)"),
+        confidence: z.number().min(0).max(1).describe("How sure you are of this verdict and of the findings linked to it, from 0 to 1. State it honestly"),
+        reason: z.string().min(1).max(MAX_REASON).describe("What you saw, or why it could not be tried, in a sentence"),
+        untestedBecause: z
+            .enum(NOT_TESTED_REASONS)
+            .optional()
+            .describe('Only with verdict "not-tested": "no-access" (the role this run used could not reach it), "observe-blocked" (it needs a change sent and this session is in observe mode), "out-of-scope" (it is outside what this run could check, such as an email or another system)'),
+        session: sessionParam,
+    },
+}, serializedPerSession("scout_criterion", async (args, session) => {
+    try {
+        const eng = engineFor(session);
+        const memory = eng.memory;
+        if (!memory)
+            throw new Error("Not attached.");
+        const judged = judgeCriterion(args, {
+            tickets: memory.tickets,
+            findings: memory.findings,
+            mode: eng.mode,
+            session: eng.sessionKey,
+            at: new Date().toISOString(),
+        });
+        if (!judged.ok)
+            return text(`Not recorded: ${judged.reason}.`, session);
+        memory.addCriterionVerdict(judged.record);
+        const r = judged.record;
+        const ticket = memory.tickets.find((t) => t.id === r.ticket);
+        const criterion = ticket ? findCriterion(ticket, r.criterion) : undefined;
+        const linked = r.findings.map((id) => memory.findings.find((f) => f.id === id)).filter((f) => f !== undefined);
+        const said = r.verdict === "pass" ? "passes" : r.verdict === "fail" ? "fails" : `was not tested (${r.untestedBecause})`;
+        return text([
+            `Recorded: ${r.ticket} ${r.criterion} ${said}, confidence ${r.confidence.toFixed(2)}.`,
+            ...(criterion ? [`  ${criterion.text}`] : []),
+            ...linked.map((f) => `  linked: [${f.severity}] ${f.title} (${f.id})`),
+        ].join("\n"), session);
+    }
+    catch (err) {
+        return errorText(err);
+    }
+}));
 server.registerTool("scout_close", {
     description: "Close a session's browser (memory persists on disk). Default: the DEFAULT session. Pass session to close a specific one, or all=true to close every live session at the end of a multi-role run. " +
         "A session that is a lane of a parallel run (named by scout_lane_brief or scout_lane_report) is not closed until its lane report has been accepted by scout_lane_report, since folding needs the session attached; the refusal names every such lane.",
@@ -1588,6 +2097,7 @@ server.registerTool("scout_close", {
         await eng.close();
         const saveError = eng.memory?.lastSaveError;
         engines.delete(name);
+        openDecisions.delete(name);
         // The last session on this project ends its run.
         if (eng.memory && ![...engines.values()].some((e) => e.memory === eng.memory))
             eng.memory.endRun();
@@ -1648,7 +2158,7 @@ async function shutdown() {
             console.error(`[scenescout] could not remove the live view's token file in ${dir}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    await Promise.allSettled([live?.stop(), ...[...engines.values()].map((e) => e.close())]);
+    await Promise.allSettled([live?.stop(), ...[...engines.values()].map((e) => e.close()), ...pendingLogins.all().map((p) => p.cancel())]);
 }
 process.on("SIGINT", () => {
     void shutdown().finally(() => process.exit(0));