scenescout 1.4.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # scenescout
 
+## 2.0.0
+
+### Major Changes
+
+- 74a45d6: **A tool that acts on the app now needs an objective.** `scout_navigate`, `scout_back`, `scout_click`, `scout_type`, `scout_select`, `scout_press`, `scout_upload` and `scout_run_plan` take an `objective`: one short sentence naming what the current batch of actions is for. It stays set until a different one is passed, so a batch costs one sentence rather than one per call, and `scout_journey` still sets it (and outranks it) while a journey runs. A call that acts with none standing is refused with what to pass and why.
+  
+  This is the breaking part: an agent that never states one now gets a refusal instead of a click. It exists because the objective was optional and therefore usually absent — someone watching a run saw sessions working through their app with nothing to say why, which is the one thing the live view is for. The objective now also appears on each card in the grid, not only in a session's close-up, and a session that has not said anything yet says so.
+
+## 1.5.0
+
+### Minor Changes
+
+- 791b4d0: The live view now hands over the report when the run ends. Closing the last session used to take the report with it — the view served it from the live engine, so the moment the browsers went the page said there was nothing to report. The last rendering is now kept, and when the board empties the page says the run has finished, opens the report by itself, and names the file it belongs in: `saved at <path>` once `scout_report` has written it, or plainly that it is not on disk and this page holds the only copy. A **Save a copy** button downloads that copy through the viewer's own browser (nothing is asked of the engine, which still answers `GET` and nothing else), and closing the tab on a finished run whose report was never written asks for confirmation first.
+
 ## 1.4.0
 
 ### Minor Changes

package/dist/engine/browser.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { elementKey, fingerprintState, isNonPageRoute, normalizePath } from "./fingerprint.js";
 import { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore } from "./memory.js";
+import { normalizeObjective } from "./objective.js";
 import { describeInjection, newInjections, probeQueries, probeScript, probeShape, rememberProbe } from "./injection.js";
 import { AuthLossTracker } from "./authloss.js";
 import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, } from "./collector.js";
@@ -205,6 +206,27 @@ export class BrowserEngine {
     journey = null;
     /** The session's task, from scout_attach. Empty when the agent gave none. */
     task = "";
+    /**
+     * What the batch of actions running right now is for. Required before a
+     * tool may act (objective.ts), stated by the agent on the call or by a
+     * journey, and kept until it is replaced — a batch costs one sentence.
+     */
+    objective = null;
+    /** Set what this session is doing now. An empty value clears it. */
+    setObjective(text) {
+        const clean = normalizeObjective(text);
+        if (!clean) {
+            this.objective = null;
+            return;
+        }
+        if (this.objective?.text === clean)
+            return;
+        this.objective = { text: clean, since: Date.now() };
+    }
+    /** Whether anything is standing that the live view could show as the objective. */
+    get hasObjective() {
+        return this.journey !== null || this.objective !== null;
+    }
     /**
      * Begin measuring a user JOURNEY — the interaction cost of completing one
      * real task ("create an order", "approve a document"). E2E suites assert
@@ -2000,7 +2022,13 @@ export class BrowserEngine {
             browser: this.engineName,
             headed: this.headed,
             ...(this.task ? { task: this.task } : {}),
-            ...(this.journey ? { objective: this.journey.goal, objectiveSince: new Date(this.journey.startedAt).toISOString() } : {}),
+            // A journey is a whole user task being measured, so its goal outranks
+            // the batch objective while it runs.
+            ...(this.journey
+                ? { objective: this.journey.goal, objectiveSince: new Date(this.journey.startedAt).toISOString() }
+                : this.objective
+                    ? { objective: this.objective.text, objectiveSince: new Date(this.objective.since).toISOString() }
+                    : {}),
         };
     }
     /**

package/dist/engine/live-page.js

@@ -48,6 +48,13 @@ export const LIVE_PAGE = `<!doctype html>
   button[aria-pressed="true"] { background: var(--accent); border-color: var(--accent); color: #fff; }
   #banner { display: none; margin: 12px 16px 0; padding: 8px 12px; border-radius: 6px; background: var(--stuck-bg); color: var(--stuck); }
   #empty { display: none; padding: 48px 16px; text-align: center; color: var(--muted); }
+  #finished { display: none; max-width: 640px; margin: 48px auto; padding: 24px; text-align: center;
+    background: var(--panel); border: 1px solid var(--line); border-radius: 8px; }
+  #finished.open { display: block; }
+  #finished h2 { margin: 0 0 8px; font-size: 18px; }
+  #finished p { margin: 0 0 8px; color: var(--muted); }
+  #finished .where { font: 12px/1.6 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; overflow-wrap: anywhere; }
+  #finished button { margin-top: 8px; padding: 7px 14px; font-weight: 600; }
   main { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 320px), 1fr)); gap: 12px; padding: 16px; }
   .card { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; overflow: hidden; display: flex; flex-direction: column; }
   .card.stuck { border-color: var(--stuck); }
@@ -96,6 +103,9 @@ export const LIVE_PAGE = `<!doctype html>
   #focus .brief .since { margin-top: -10px; font-size: 12px; color: #98a2b3; }
   @media (max-width: 700px) { #focus .lower { flex-direction: column; height: 45vh; } }
   .task { padding: 0 12px 2px; font-size: 12px; color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .doing { padding: 0 12px 4px; font-size: 12px; color: var(--text); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .doing::before { content: "▸ "; color: var(--accent); }
+  .doing.unset { color: var(--stuck); }
   #focus .feed .a { color: #e6e9ee; }
   #focus .feed .t, #focus .feed .d, #focus .feed .none { color: #98a2b3; }
   #focus .feed .bad { color: #fca5a5; }
@@ -143,12 +153,19 @@ export const LIVE_PAGE = `<!doctype html>
 </header>
 <div id="banner" role="alert" data-testid="live-unreachable-banner">The engine is not answering. It may have exited; this page will pick up again if it comes back.</div>
 <div id="empty" data-testid="live-empty-state">No session is attached yet. Cards appear here as soon as one attaches.</div>
+<div id="finished" data-testid="live-finished-state">
+  <h2>The run has finished</h2>
+  <p>Its browsers are closed, so there is nothing left to watch. What it found is in the report.</p>
+  <p class="where" id="finished-where" data-testid="live-finished-where"></p>
+  <button type="button" id="finished-report" data-testid="live-finished-report">Read the report</button>
+</div>
 <main id="grid"></main>
 <div id="report" role="dialog" aria-modal="true" aria-label="The run's report" data-testid="live-report-dialog">
   <div class="bar">
     <strong>Report</strong>
     <span class="meta" id="report-meta" data-testid="live-report-meta"></span>
     <span class="spacer"></span>
+    <button type="button" id="report-save" data-testid="live-report-save">Save a copy</button>
     <button type="button" id="report-close" data-testid="live-report-close">Close</button>
   </div>
   <div class="doc" id="report-doc" data-testid="live-report-doc"></div>
@@ -187,6 +204,14 @@ export const LIVE_PAGE = `<!doctype html>
   var reportOpen = false;
   var reportTimer = null;
   var reportProblem = null;
+  // The run had sessions and has none now: its browsers are gone, and this
+  // page holds the only rendering of the report unless it was written to disk.
+  var sawRun = false;
+  var finished = false;
+  var reportShown = false;
+  var reportFile = null;
+  var reportMarkdown = null;
+  var savedACopy = false;
   // A result that reads as a failure is shown in red.
   var BAD_RESULT = /error|fail|refus|block|violation|abandoned/i;
 
@@ -282,6 +307,8 @@ export const LIVE_PAGE = `<!doctype html>
     top.appendChild(nameEl); top.appendChild(role); top.appendChild(badge);
     var task = el('div', 'task');
     task.setAttribute('data-testid', 'live-card-task-' + name);
+    var doing = el('div', 'doing');
+    doing.setAttribute('data-testid', 'live-card-objective-' + name);
     var tool = el('div', 'line');
     var url = el('div', 'line');
     var shot = el('button', 'shot');
@@ -304,9 +331,9 @@ export const LIVE_PAGE = `<!doctype html>
     toggle.setAttribute('data-testid', 'live-card-toggle-' + name);
     var spec = el('span', 'spec');
     foot.appendChild(toggle); foot.appendChild(spec);
-    root.appendChild(top); root.appendChild(task); root.appendChild(tool); root.appendChild(url); root.appendChild(shot); root.appendChild(feed); root.appendChild(foot);
+    root.appendChild(top); root.appendChild(task); root.appendChild(doing); root.appendChild(tool); root.appendChild(url); root.appendChild(shot); root.appendChild(feed); root.appendChild(foot);
 
-    var card = { name: name, root: root, role: role, badge: badge, task: task, tool: tool, url: url, shot: shot, img: img, feed: feed, toggle: toggle, spec: spec, live: false };
+    var card = { name: name, root: root, role: role, badge: badge, task: task, doing: doing, tool: tool, url: url, shot: shot, img: img, feed: feed, toggle: toggle, spec: spec, live: false };
     toggle.addEventListener('click', function () { setLive(card, !card.live); });
     shot.addEventListener('click', function () { openFocus(name); });
     img.src = shotUrl(name);
@@ -435,7 +462,8 @@ export const LIVE_PAGE = `<!doctype html>
           meta.textContent = '';
           return;
         }
-        meta.textContent = 'as the run stands at ' + clock(d.at) + ' · scout_report writes this document to .scenescout/report.md at the end';
+        reportMarkdown = d.markdown;
+        meta.textContent = (finished ? 'as the run left it at ' : 'as the run stands at ') + clock(d.at) + ' · ' + whereItIs();
         renderMarkdown(doc, d.markdown);
       })
       .catch(function (err) {
@@ -448,6 +476,28 @@ export const LIVE_PAGE = `<!doctype html>
         }
       });
   }
+  /** Where the report's file is, and whether the agent has written it there. */
+  function whereItIs() {
+    if (!reportFile) return 'scout_report writes this document to .scenescout/report.md at the end';
+    if (reportFile.written) return 'saved at ' + reportFile.path;
+    return 'NOT saved: ' + reportFile.path + ' does not exist — the agent has not run scout_report, so this page holds the only copy';
+  }
+
+  // Saving is the viewer's own browser writing a file the page already has;
+  // nothing is sent to the engine, which only ever answers GET (ADR 7).
+  function saveACopy() {
+    if (!reportMarkdown) return;
+    var url = URL.createObjectURL(new Blob([reportMarkdown], { type: 'text/markdown' }));
+    var a = document.createElement('a');
+    a.href = url;
+    a.download = 'scenescout-report.md';
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(function () { URL.revokeObjectURL(url); }, 10000);
+    savedACopy = true;
+  }
+
   function openReport() {
     reportOpen = true;
     document.getElementById('report').classList.add('open');
@@ -503,6 +553,12 @@ export const LIVE_PAGE = `<!doctype html>
     card.task.textContent = s.task || '';
     card.task.title = s.task || '';
     card.task.hidden = !s.task;
+    // What it is doing right now, in the agent's words. A session that acts
+    // without saying is refused by the engine, so a blank one here is a
+    // session that has not acted yet — say that rather than showing nothing.
+    card.doing.textContent = s.objective || 'not said yet';
+    card.doing.title = s.objective || '';
+    card.doing.className = 'doing' + (s.objective ? '' : ' unset');
     card.badge.className = 'badge ' + s.state;
     card.badge.textContent = d.badge;
     card.tool.textContent = d.tool;
@@ -608,7 +664,21 @@ export const LIVE_PAGE = `<!doctype html>
       delete frames[name];
     });
     syncEvents();
-    document.getElementById('empty').style.display = snap.sessions.length ? 'none' : 'block';
+    reportFile = snap.report || reportFile;
+    if (snap.sessions.length > 0) sawRun = true;
+    finished = sawRun && snap.sessions.length === 0;
+    document.getElementById('empty').style.display = snap.sessions.length || finished ? 'none' : 'block';
+    document.getElementById('finished').classList.toggle('open', finished);
+    if (finished) {
+      var where = document.getElementById('finished-where');
+      where.textContent = whereItIs();
+      where.className = 'where' + (reportFile && reportFile.written ? '' : ' unset');
+      // The moment somebody wants the report is the moment the run ends: show it.
+      if (!reportShown) {
+        reportShown = true;
+        if (!reportOpen) openReport();
+      }
+    }
     document.getElementById('engine').textContent = 'engine pid ' + snap.pid + ' · v' + snap.version;
     document.getElementById('counts').textContent = snap.sessions.length + ' session' + (snap.sessions.length === 1 ? '' : 's') +
       ' · ' + counts.running + ' running · ' + counts.idle + ' idle' + (counts.stuck ? ' · ' + counts.stuck + ' stuck' : '');
@@ -633,6 +703,16 @@ export const LIVE_PAGE = `<!doctype html>
   document.getElementById('focus-feed').addEventListener('mouseleave', function () { showObjective(null); });
   document.getElementById('focus').addEventListener('click', function (e) { if (e.target === this) closeFocus(); });
   document.getElementById('report-open').addEventListener('click', openReport);
+  document.getElementById('finished-report').addEventListener('click', openReport);
+  document.getElementById('report-save').addEventListener('click', saveACopy);
+  // Closing the tab on a finished run whose report was never written to disk
+  // throws the only copy away. The browser shows its own confirm/dismiss, and
+  // only when the person has interacted with the page at least once.
+  window.addEventListener('beforeunload', function (e) {
+    if (!finished || savedACopy || (reportFile && reportFile.written)) return;
+    e.preventDefault();
+    e.returnValue = '';
+  });
   document.getElementById('report-close').addEventListener('click', closeReport);
   document.addEventListener('keydown', function (e) {
     if (e.key !== 'Escape') return;

package/dist/engine/objective.js

@@ -0,0 +1,49 @@
+/**
+ * The objective: one short sentence saying what the batch of actions a session
+ * is performing right now is FOR.
+ *
+ * The engine sees tool calls, never the reasoning behind them, so the live
+ * view can only show an objective the agent states. Left optional it was
+ * usually blank — a person watching saw a session click through an app with
+ * nothing to say why. So a tool that acts on the app requires one: passed on
+ * the call, or already standing from an earlier call or a journey. It stays
+ * set until it is replaced, so a batch costs one sentence, not one per click.
+ *
+ * Reading the page (snapshot, hover, scroll, coverage, the audits) needs none:
+ * orienting is what an agent does before it can say what it is about to do.
+ */
+/** Longer than this is a paragraph, not an objective; the live view shows one line. */
+export const OBJECTIVE_MAX = 120;
+/**
+ * The tools that act on the app under test. Each changes what the person
+ * watching is looking at, so each has to be able to say why.
+ */
+export const NEEDS_OBJECTIVE = new Set([
+    "scout_navigate",
+    "scout_back",
+    "scout_click",
+    "scout_type",
+    "scout_select",
+    "scout_press",
+    "scout_upload",
+    "scout_run_plan",
+]);
+export function needsObjective(tool) {
+    return NEEDS_OBJECTIVE.has(tool);
+}
+/** One line, whitespace collapsed, bounded. Empty input clears the objective. */
+export function normalizeObjective(text) {
+    return (text ?? "").replace(/\s+/g, " ").trim().slice(0, OBJECTIVE_MAX);
+}
+/**
+ * What a session is told when it acts with no objective standing. It names the
+ * parameter, gives the shape of a good one, and says the rule it satisfies —
+ * an agent that reads this once should not need it again.
+ */
+export function objectiveRefusal(tool) {
+    return (`${tool} needs an objective: this session has none, so the live view cannot say what it is doing.\n` +
+        `Pass objective:"…" on this call — one short sentence about the batch of actions you are performing, ` +
+        `in the words you would use to tell a colleague ("Sign in as QA_Team and check where it lands", "Fill the deviation form with invalid dates"). ` +
+        `It stays set until you pass a different one, so a batch costs one sentence, not one per call. ` +
+        `scout_journey {action:"start", goal:"…"} sets it too, and is what to use when you are measuring a whole user task.`);
+}

package/dist/mcp-server.js

@@ -37,8 +37,9 @@ import { reapOrphanBrowsers } from "./engine/reaper.js";
 import { MemoryStore, redactSecrets } from "./engine/memory.js";
 import { SessionQueue, withWatchdog } from "./engine/dispatch.js";
 import { FIXTURE_KINDS } from "./engine/fixtures.js";
-import { feedForSession, LIVE_ENV, writeStatusFile, LIVE_TOKEN_FILE, LiveServer, StatusBoard } from "./engine/live.js";
+import { feedForSession, LIVE_ENV, writeStatusFile, LIVE_TOKEN_FILE, LiveServer, StatusBoard, } from "./engine/live.js";
 import { computeGaps, formatRouteCoverage, generateReport } from "./engine/report.js";
+import { needsObjective, objectiveRefusal, OBJECTIVE_MAX } from "./engine/objective.js";
 import { EXPLORE_PROMPT_ARGUMENTS, explorePrompt, loadPlaybook, PLAYBOOK_PROMPT, PLAYBOOK_TOOL, SERVER_INSTRUCTIONS } from "./playbook.js";
 import { formatScan, scanProject } from "./scan.js";
 /** Live sessions: each name owns an independent BrowserEngine (browser + auth). */
@@ -105,8 +106,44 @@ const liveTokenWrites = new Map();
 let liveTokenWarned = false;
 /** Why the live view could not start, when it could not: told to the agent and written to status.json. */
 let liveError = null;
+/**
+ * The last run's report, kept after its sessions close. The engines are gone
+ * by then, so this is the only way the live view can still show what the run
+ * found — which is the moment somebody most wants to read it.
+ */
+let lastRun = null;
+/** Render the report for a session that is about to close, so the live view keeps it. */
+function keepReport(eng) {
+    if (!eng.memory)
+        return;
+    try {
+        const { markdown } = generateReport(eng.memory, eng.oracleLog.all, reportExtras(eng), { write: false });
+        lastRun = { markdown: redactSecrets(markdown), at: new Date().toISOString(), dir: eng.memory.dir };
+    }
+    catch {
+        // Best-effort: a report that cannot be rendered must not fail a close.
+    }
+}
+/** Where this run's report belongs, and whether the agent has written it there yet. */
+function reportFile(dir) {
+    if (!dir)
+        return undefined;
+    const file = path.join(dir, "report.md");
+    try {
+        return { path: file, written: fs.existsSync(file) };
+    }
+    catch {
+        return { path: file, written: false };
+    }
+}
 const liveProvider = {
-    snapshot: () => ({ pid: process.pid, version: PKG_VERSION, at: new Date().toISOString(), sessions: board.list() }),
+    snapshot: () => ({
+        pid: process.pid,
+        version: PKG_VERSION,
+        at: new Date().toISOString(),
+        sessions: board.list(),
+        report: reportFile(engines.values().next().value?.memory?.dir ?? lastRun?.dir),
+    }),
     // The engine holds no reasoning — it never sees one — so the feed is what the
     // session DID: the action log, which is the same trail a finding's repro uses.
     activity: (session, limit) => feedForSession(engines.get(session)?.memory?.actionLog ?? [], session, limit, redactSecrets),
@@ -118,7 +155,7 @@ const liveProvider = {
     report: () => {
         const eng = (lastWriter && engines.get(lastWriter.session)) ?? engines.values().next().value;
         if (!eng?.memory)
-            return null;
+            return lastRun ? { markdown: lastRun.markdown, at: lastRun.at } : null;
         const { markdown } = generateReport(eng.memory, eng.oracleLog.all, reportExtras(eng), { write: false });
         return { markdown: redactSecrets(markdown), at: new Date().toISOString() };
     },
@@ -273,6 +310,16 @@ const sessionQueue = new SessionQueue();
 function serializedPerSession(label, fn, timeoutMs = 60_000) {
     return (args) => {
         const session = args.session ?? activeName;
+        // Every acting tool passes through here, so the objective is required in
+        // one place rather than eight. A call that states one sets it for the
+        // batch; a call that acts with none standing is told what to pass.
+        const eng = engines.get(session);
+        if (eng) {
+            if (args.objective !== undefined)
+                eng.setObjective(args.objective);
+            if (needsObjective(label) && !eng.hasObjective)
+                return Promise.resolve(text(objectiveRefusal(label), session));
+        }
         const exec = async () => {
             writeStatus(session, "running", label, timeoutMs);
             try {
@@ -312,6 +359,18 @@ const sessionParam = z
     .max(40)
     .optional()
     .describe("Target this session directly instead of the active one — pass it explicitly when dispatching to MULTIPLE sessions in one turn (e.g. two scout_click calls with different `session`), which then run CONCURRENTLY rather than queueing. Omit for single-session sequential use.");
+/**
+ * What the batch of actions this call belongs to is for. Required by the tools
+ * that act (objective.ts) unless one is already standing; shown to whoever is
+ * watching the run, beside the session's task.
+ */
+const objectiveParam = z
+    .string()
+    .max(OBJECTIVE_MAX)
+    .optional()
+    .describe("One short sentence naming what this batch of actions is for, in the words you would use to tell a colleague " +
+    '("Sign in as QA_Team and check where it lands"). It stays set until you pass a different one, and is shown live to the person watching. ' +
+    "Required on the tools that act unless a journey or an earlier call already set one.");
 // The method, for every client that has no skill loader. It is read per call,
 // not cached: a source checkout's skill file can change under a running server.
 server.registerTool(PLAYBOOK_TOOL, {
@@ -549,6 +608,7 @@ server.registerTool("scout_run_plan", {
         }))
             .min(1)
             .max(20),
+        objective: objectiveParam,
         session: sessionParam,
     },
 }, serializedPerSession("scout_run_plan", async ({ steps }, session) => {
@@ -564,6 +624,7 @@ server.registerTool("scout_click", {
     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)"),
+        objective: objectiveParam,
         session: sessionParam,
     },
 }, serializedPerSession("scout_click", async ({ ref, clicks }, session) => {
@@ -584,6 +645,7 @@ server.registerTool("scout_type", {
         value: z.string().optional().describe("Alias for `textValue`."),
         pressEnter: z.boolean().default(false).describe("Press Enter after typing"),
         replace: z.boolean().default(false).describe("Clear the field before typing instead of appending to existing content"),
+        objective: objectiveParam,
         session: sessionParam,
     },
 }, serializedPerSession("scout_type", async ({ ref, textValue, value, pressEnter, replace }, session) => {
@@ -618,6 +680,7 @@ server.registerTool("scout_upload", {
             .optional()
             .describe("Generated fixture kind; default: inferred from the input's accept attribute (pdf when there is none, or none we can generate)"),
         name: z.string().min(1).max(512).optional().describe("Filename override (default scenescout-fixture.<kind>, or the disk file's own name)"),
+        objective: objectiveParam,
         session: sessionParam,
     },
 }, serializedPerSession("scout_upload", async ({ ref, filePath, fixture, name }, session) => {
@@ -641,7 +704,7 @@ server.registerTool("scout_hover", {
 }));
 server.registerTool("scout_select", {
     description: "Select an option in a <select> by ref.",
-    inputSchema: { ref: z.string(), value: z.string().describe("Option value or label"), session: sessionParam },
+    inputSchema: { ref: z.string(), value: z.string().describe("Option value or label"), objective: objectiveParam, session: sessionParam },
 }, serializedPerSession("scout_select", async ({ ref, value }, session) => {
     try {
         return text(await engineFor(session).select(ref, value), session);
@@ -652,7 +715,7 @@ 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.",
-    inputSchema: { target: z.string().describe("Absolute URL or path like /settings"), session: sessionParam },
+    inputSchema: { target: z.string().describe("Absolute URL or path like /settings"), objective: objectiveParam, session: sessionParam },
 }, serializedPerSession("scout_navigate", async ({ target }, session) => {
     try {
         return text(await engineFor(session).navigate(target), session);
@@ -663,7 +726,7 @@ server.registerTool("scout_navigate", {
 }));
 server.registerTool("scout_back", {
     description: "Go back in browser history (tests back-button resilience).",
-    inputSchema: { session: sessionParam },
+    inputSchema: { objective: objectiveParam, session: sessionParam },
 }, serializedPerSession("scout_back", async (_args, session) => {
     try {
         return text(await engineFor(session).goBack(), session);
@@ -693,7 +756,7 @@ server.registerTool("scout_scroll", {
 }));
 server.registerTool("scout_press", {
     description: "Press a keyboard key (e.g. Escape, Tab, Enter) — useful for closing modals and testing keyboard navigation.",
-    inputSchema: { key: z.string(), session: sessionParam },
+    inputSchema: { key: z.string(), objective: objectiveParam, session: sessionParam },
 }, serializedPerSession("scout_press", async ({ key }, session) => {
     try {
         return text(await engineFor(session).press(key), session);
@@ -976,6 +1039,8 @@ server.registerTool("scout_close", {
             for (const e of engines.values())
                 if (e.memory?.dir)
                     dirs.add(e.memory.dir);
+            for (const e of engines.values())
+                keepReport(e);
             for (const name of engines.keys())
                 live?.dropSession(name);
             await Promise.allSettled([...engines.values()].map((e) => e.close()));
@@ -991,6 +1056,7 @@ server.registerTool("scout_close", {
         const eng = engines.get(name);
         if (!eng)
             return text(`No live session "${name}".`, name);
+        keepReport(eng);
         live?.dropSession(name);
         await eng.close();
         const saveError = eng.memory?.lastSaveError;

package/package.json

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

@@ -37,10 +37,12 @@ You are the brain of an exploratory UI tester. The SceneScout MCP server gives y
 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.
 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.
 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. **Design-connoisseur pass without pixels: `scout_design_audit`.** Run it once per representative page (dashboard, a form, a detail view, a data table). Its output has two tiers: **⚠ measurable defects** (WCAG contrast, tiny targets, clipped text, aspect-distorted images, horizontal overflow, keyboard tab stops with no visible focus indicator — sampled with real Tab presses) and **→ craft suggestions** (line measure and line-height rhythm, spacing-grid adherence, typography entropy, gray census and accent-hue count, pure-#000 body text, elevation/control consistency, heading structure, indistinguishable links, AI-slop tells like gradient text/glassmorphism/side-stripe borders/identical card grids), closing with a SYSTEM SUMMARY of design-system coherence. Judge every line with product context (dense tables legitimately have small targets; a chart page legitimately uses many hues). File ⚠ defects as `visual`/`a11y`, and genuine → opportunities as `ux-polish` findings **quoting the concrete numbers** — "~142 characters per line (65–75 ideal)" beats "text feels wide". Every audit ends with a **PAGE SCORE** (0–100 overall + a11y/craft/consistency/task-clarity subscores) persisted per route — the report ranks pages worst-first, so re-runs show whether pages got better or worse. Separately, every `scout_snapshot` runs an **overlay/modal probe** automatically: an empty dialog over a grayed page, a backdrop with no dialog, a far-off-centre dialog leaving a blank band, or a dialog extending unreachably below the viewport appear as OVERLAY lines in GEOMETRY issues — treat these as high-value findings (the user is visually stuck). This is where "how could this page be better" gets answered, not just "is it broken".
-8. **Measure task EASE with `scout_journey`, not just correctness.** Wrap each module's primary task (`{action:"start", goal:"Create an order"}` → do it → `{action:"end", completed:…}`). Navigate by CLICKING like a first-time user — typing a known deep URL shortcuts the very thing being measured (a route you can only reach by editing the address bar is itself a finding). The result gives interaction count, distinct screens, the path taken, and BACKTRACKS — returning to a screen already left is the clearest evidence the next step wasn't discoverable. An abandoned journey (`completed:false`) is a high-severity finding: the task is blocked or undiscoverable, which no passing e2e suite would ever reveal.
-9. **Walk the auth surface too — anonymously.** Attach a second session WITHOUT a storage-state file (a fresh logged-out profile) and exercise signup, login failure states, and forgot/reset-password **as far as they physically go**. The mailbox wall is expected — reaching "check your email" IS the success condition; everything before it is what you're testing: does submit actually fire (a dead signup button is a high finding), are errors specific and actionable, can the user resend or recover from a typo, does the flow dead-end. Use plausible synthetic identities only (invent `qa-<runid>@example.com`-style addresses, never a real person's), submit each form valid AND invalid, and judge the feedback. Two classic findings live here: a forgot-password that answers "no account with that email" is an **account-enumeration leak** (file as security; "if an account exists, we sent a link" is the correct shape), and a signup that accepts the form then lands on a blank or logged-out page with no guidance is a **journey dead-end**. Signup creates a record, so what this pass may do depends on the mode. In `observe`, fill and submit the auth forms for their CLIENT-SIDE behaviour only: the engine blocks signup, password change and reset, and lets only a login itself go out. Disclose the server-side half as a gap. Actually creating an account needs the user's explicit okay and safe-write mode; the engine tracks the created account like any other creation.
-10. **`scout_coverage` decides what's next** — it lists unvisited routes and unexercised elements. Trust it over your memory. Prefer reaching routes by clicking real navigation; fall back to direct URLs for coverage completeness and re-verification, and say which you used when it affects the finding (see the provenance rule below).
+7. **Say what you are doing: `objective` is required before a tool acts.** 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 an `objective`: one short sentence naming what this batch of actions is FOR, in the words you would use to tell a colleague ("Sign in as QA_Team and check where it lands", "Fill the deviation form with invalid dates", "Walk the approval queue as a manager"). It STAYS SET until you pass a different one, so a batch costs one sentence, not one per call — pass a fresh one whenever you move on to something else, and keep it true rather than letting it describe what you finished ten calls ago. Acting with none standing is refused: the person watching the live view would otherwise see a session clicking through their app with nothing to say why. `scout_journey {action:"start", goal:…}` sets it too and outranks it while it runs — use a journey when you are MEASURING a whole user task, the parameter for everything else.
+
+8. **Design-connoisseur pass without pixels: `scout_design_audit`.** Run it once per representative page (dashboard, a form, a detail view, a data table). Its output has two tiers: **⚠ measurable defects** (WCAG contrast, tiny targets, clipped text, aspect-distorted images, horizontal overflow, keyboard tab stops with no visible focus indicator — sampled with real Tab presses) and **→ craft suggestions** (line measure and line-height rhythm, spacing-grid adherence, typography entropy, gray census and accent-hue count, pure-#000 body text, elevation/control consistency, heading structure, indistinguishable links, AI-slop tells like gradient text/glassmorphism/side-stripe borders/identical card grids), closing with a SYSTEM SUMMARY of design-system coherence. Judge every line with product context (dense tables legitimately have small targets; a chart page legitimately uses many hues). File ⚠ defects as `visual`/`a11y`, and genuine → opportunities as `ux-polish` findings **quoting the concrete numbers** — "~142 characters per line (65–75 ideal)" beats "text feels wide". Every audit ends with a **PAGE SCORE** (0–100 overall + a11y/craft/consistency/task-clarity subscores) persisted per route — the report ranks pages worst-first, so re-runs show whether pages got better or worse. Separately, every `scout_snapshot` runs an **overlay/modal probe** automatically: an empty dialog over a grayed page, a backdrop with no dialog, a far-off-centre dialog leaving a blank band, or a dialog extending unreachably below the viewport appear as OVERLAY lines in GEOMETRY issues — treat these as high-value findings (the user is visually stuck). This is where "how could this page be better" gets answered, not just "is it broken".
+9. **Measure task EASE with `scout_journey`, not just correctness.** Wrap each module's primary task (`{action:"start", goal:"Create an order"}` → do it → `{action:"end", completed:…}`). Navigate by CLICKING like a first-time user — typing a known deep URL shortcuts the very thing being measured (a route you can only reach by editing the address bar is itself a finding). The result gives interaction count, distinct screens, the path taken, and BACKTRACKS — returning to a screen already left is the clearest evidence the next step wasn't discoverable. An abandoned journey (`completed:false`) is a high-severity finding: the task is blocked or undiscoverable, which no passing e2e suite would ever reveal.
+10. **Walk the auth surface too — anonymously.** Attach a second session WITHOUT a storage-state file (a fresh logged-out profile) and exercise signup, login failure states, and forgot/reset-password **as far as they physically go**. The mailbox wall is expected — reaching "check your email" IS the success condition; everything before it is what you're testing: does submit actually fire (a dead signup button is a high finding), are errors specific and actionable, can the user resend or recover from a typo, does the flow dead-end. Use plausible synthetic identities only (invent `qa-<runid>@example.com`-style addresses, never a real person's), submit each form valid AND invalid, and judge the feedback. Two classic findings live here: a forgot-password that answers "no account with that email" is an **account-enumeration leak** (file as security; "if an account exists, we sent a link" is the correct shape), and a signup that accepts the form then lands on a blank or logged-out page with no guidance is a **journey dead-end**. Signup creates a record, so what this pass may do depends on the mode. In `observe`, fill and submit the auth forms for their CLIENT-SIDE behaviour only: the engine blocks signup, password change and reset, and lets only a login itself go out. Disclose the server-side half as a gap. Actually creating an account needs the user's explicit okay and safe-write mode; the engine tracks the created account like any other creation.
+11. **`scout_coverage` decides what's next** — it lists unvisited routes and unexercised elements. Trust it over your memory. Prefer reaching routes by clicking real navigation; fall back to direct URLs for coverage completeness and re-verification, and say which you used when it affects the finding (see the provenance rule below).
 
 ## Levels (completion contracts — the engine ENFORCES them via `scout_report {level}`)