scenescout 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # scenescout
 
+## 3.0.0
+
+### Major Changes
+
+- c7c4811: **A session now says two things, and the second is required.** Its **objective** is the whole remit it was given, set once at `scout_attach {objective}` — "Admin lane: §2 registers, §7 plan gating". Its **task** is what it is doing right now, and every tool that acts on the app — `scout_navigate`, `scout_back`, `scout_click`, `scout_type`, `scout_select`, `scout_press`, `scout_upload`, `scout_run_plan` — takes one: a few words for the batch in front of it ("Filtering the documents register by status"). It stays set until a different one is passed, `scout_journey` sets it while a journey runs, and reading the page needs none. A call that acts with no task standing is refused, with what to pass and why.
+  
+  This exists because both were 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. Stating a task also marks the action log, so the close-up's feed groups and tints the actions that follow it, as it already did for a journey's.
+  
+  Breaking, in two ways. An agent that never states a task now gets a refusal instead of a click. And the two names swapped to match what they mean: `scout_attach {task}` is now `scout_attach {objective}`, and the per-call `objective` of 2.0 is now `task`. Both old names are still accepted, so a caller written against 2.0 keeps working.
+
 ## 2.0.0
 
 ### Major Changes

package/dist/engine/browser.js

@@ -2,8 +2,8 @@ import { chromium, firefox, webkit } from "playwright";
 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 { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore, TASK_SET } from "./memory.js";
+import { normalizeTask } from "./task.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";
@@ -204,28 +204,32 @@ export class BrowserEngine {
     designAuditCount = 0;
     /** Active task-efficiency measurement (scout_journey), if any. */
     journey = null;
-    /** The session's task, from scout_attach. Empty when the agent gave none. */
-    task = "";
+    /** The session's objective: the whole remit the agent was given at scout_attach. Empty when none was given. */
+    sessionObjective = "";
     /**
-     * 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.
+     * The batch of actions running right now. Required before a tool may act
+     * (task.ts), stated by the agent on the call or by a journey, and kept
+     * until it is replaced — a batch costs a few words, not one per click.
      */
-    objective = null;
+    currentTask = null;
     /** Set what this session is doing now. An empty value clears it. */
-    setObjective(text) {
-        const clean = normalizeObjective(text);
+    setTask(text) {
+        const clean = normalizeTask(text);
         if (!clean) {
-            this.objective = null;
+            this.currentTask = null;
             return;
         }
-        if (this.objective?.text === clean)
+        if (this.currentTask?.text === clean)
             return;
-        this.objective = { text: clean, since: Date.now() };
+        this.currentTask = { text: clean, since: Date.now() };
+        // Logged so the feed can group the actions that follow under it, the way
+        // it groups a journey's — the trail is where a watcher reads what
+        // happened, and an ungrouped one says nothing about why.
+        this.logAction({ action: TASK_SET, target: clean, url: this.page?.url() ?? "" });
     }
-    /** Whether anything is standing that the live view could show as the objective. */
-    get hasObjective() {
-        return this.journey !== null || this.objective !== null;
+    /** Whether anything is standing that the live view could show as the task. */
+    get hasTask() {
+        return this.journey !== null || this.currentTask !== null;
     }
     /**
      * Begin measuring a user JOURNEY — the interaction cost of completing one
@@ -347,7 +351,7 @@ export class BrowserEngine {
             throw new Error(`storageStatePath does not exist: ${opts.storageStatePath}`);
         }
         this.mode = opts.mode ?? "read-only";
-        this.task = (opts.task ?? "").trim().replace(/\s+/g, " ").slice(0, 300);
+        this.sessionObjective = (opts.objective ?? "").trim().replace(/\s+/g, " ").slice(0, 300);
         this.headed = opts.headed ?? false;
         this.blockedRequests = [];
         this.pendingCreations = new Set();
@@ -2021,13 +2025,13 @@ export class BrowserEngine {
             mode: this.mode,
             browser: this.engineName,
             headed: this.headed,
-            ...(this.task ? { task: this.task } : {}),
-            // A journey is a whole user task being measured, so its goal outranks
-            // the batch objective while it runs.
+            ...(this.sessionObjective ? { objective: this.sessionObjective } : {}),
+            // A journey is a whole user task being measured, so its goal is what the
+            // session is doing 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() }
+                ? { task: this.journey.goal, taskSince: new Date(this.journey.startedAt).toISOString() }
+                : this.currentTask
+                    ? { task: this.currentTask.text, taskSince: new Date(this.currentTask.since).toISOString() }
                     : {}),
         };
     }

package/dist/engine/live-page.js

@@ -180,11 +180,11 @@ export const LIVE_PAGE = `<!doctype html>
   <div class="lower">
     <div class="feed" id="focus-feed" data-testid="live-focus-feed"></div>
     <aside class="brief" aria-label="What this session is doing" data-testid="live-focus-brief">
-      <h3>Task</h3>
-      <p id="focus-task" data-testid="live-focus-task"></p>
-      <h3 id="focus-objective-head">Current objective</h3>
+      <h3>Objective</h3>
       <p id="focus-objective" data-testid="live-focus-objective"></p>
-      <p class="since" id="focus-objective-since"></p>
+      <h3 id="focus-task-head">Doing now</h3>
+      <p id="focus-task" data-testid="live-focus-task"></p>
+      <p class="since" id="focus-task-since"></p>
     </aside>
   </div>
 </div>
@@ -200,7 +200,7 @@ export const LIVE_PAGE = `<!doctype html>
   var events = null;
   var eventsKey = '';
   var frames = {};
-  var hoverObjective = null;
+  var hoverTask = null;
   var reportOpen = false;
   var reportTimer = null;
   var reportProblem = null;
@@ -306,9 +306,9 @@ export const LIVE_PAGE = `<!doctype html>
     var badge = el('span', 'badge idle');
     top.appendChild(nameEl); top.appendChild(role); top.appendChild(badge);
     var task = el('div', 'task');
-    task.setAttribute('data-testid', 'live-card-task-' + name);
+    task.setAttribute('data-testid', 'live-card-objective-' + name);
     var doing = el('div', 'doing');
-    doing.setAttribute('data-testid', 'live-card-objective-' + name);
+    doing.setAttribute('data-testid', 'live-card-task-' + name);
     var tool = el('div', 'line');
     var url = el('div', 'line');
     var shot = el('button', 'shot');
@@ -519,18 +519,18 @@ export const LIVE_PAGE = `<!doctype html>
     node.textContent = '';
     if (!lines || !lines.length) { node.appendChild(el('div', 'none', 'nothing recorded yet')); return; }
     var group = null;
-    var groupObjective = null;
+    var groupTask = null;
     var groups = 0;
     lines.forEach(function (line) {
-      var objective = line.objective || '';
-      if (!group || objective !== groupObjective) {
-        group = el('div', 'group' + (objective ? ' g' + (groups % 4) : ''));
-        if (objective) { groups += 1; group.title = objective; }
+      var task = line.task || '';
+      if (!group || task !== groupTask) {
+        group = el('div', 'group' + (task ? ' g' + (groups % 4) : ''));
+        if (task) { groups += 1; group.title = task; }
         if (onGroup) {
-          group.addEventListener('mouseenter', function () { onGroup(objective); });
+          group.addEventListener('mouseenter', function () { onGroup(task); });
           group.addEventListener('mouseleave', function () { onGroup(null); });
         }
-        groupObjective = objective;
+        groupTask = task;
         node.appendChild(group);
       }
       var row = el('div', 'row');
@@ -550,15 +550,15 @@ export const LIVE_PAGE = `<!doctype html>
     var d = describe(s);
     card.root.className = 'card' + (s.state === 'stuck' ? ' stuck' : '');
     card.role.textContent = s.role === 'anonymous' ? '' : s.role;
-    card.task.textContent = s.task || '';
-    card.task.title = s.task || '';
-    card.task.hidden = !s.task;
+    card.task.textContent = s.objective || '';
+    card.task.title = s.objective || '';
+    card.task.hidden = !s.objective;
     // 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.doing.textContent = s.task || 'not said yet';
+    card.doing.title = s.task || '';
+    card.doing.className = 'doing' + (s.task ? '' : ' unset');
     card.badge.className = 'badge ' + s.state;
     card.badge.textContent = d.badge;
     card.tool.textContent = d.tool;
@@ -574,8 +574,8 @@ export const LIVE_PAGE = `<!doctype html>
     document.getElementById('focus-img').alt = 'Live view of ' + name;
     document.getElementById('focus-img').src = frames[name] || shotUrl(name);
     document.getElementById('focus').classList.add('open');
-    hoverObjective = null;
-    renderFeed(document.getElementById('focus-feed'), (latest[name] || {}).feed, showObjective);
+    hoverTask = null;
+    renderFeed(document.getElementById('focus-feed'), (latest[name] || {}).feed, showTask);
     syncEvents();
     loadFullFeed(name);
     paintFocus();
@@ -592,7 +592,7 @@ export const LIVE_PAGE = `<!doctype html>
   function loadFullFeed(name) {
     fetch('api/activity?session=' + encodeURIComponent(name), { cache: 'no-store' })
       .then(function (r) { return r.ok ? r.json() : null; })
-      .then(function (d) { if (d && focused === d.session) renderFeed(document.getElementById('focus-feed'), d.feed, showObjective); })
+      .then(function (d) { if (d && focused === d.session) renderFeed(document.getElementById('focus-feed'), d.feed, showTask); })
       .catch(function () { /* the short feed from the last poll stays on screen */ });
   }
 
@@ -604,24 +604,24 @@ export const LIVE_PAGE = `<!doctype html>
 
   // The pointer is over a group of the close-up's feed: the brief shows the
   // objective those actions served. It goes back to the current one on leaving.
-  function showObjective(objective) {
-    hoverObjective = objective;
+  function showTask(task) {
+    hoverTask = task;
     paintBrief();
   }
   function paintBrief() {
     var s = focused && latest[focused];
     // The engine sees tool calls, not reasoning: both of these are the agent's own words, or nothing.
-    setBrief('focus-task', s && s.task, 'Not given. An agent sets it when it attaches the session.');
-    var head = document.getElementById('focus-objective-head');
-    if (hoverObjective !== null) {
-      head.textContent = 'Objective for these actions';
-      setBrief('focus-objective', hoverObjective, 'No journey was running.');
-      document.getElementById('focus-objective-since').textContent = '';
+    setBrief('focus-objective', s && s.objective, 'Not given. An agent sets it when it attaches the session.');
+    var head = document.getElementById('focus-task-head');
+    if (hoverTask !== null) {
+      head.textContent = 'Doing, for these actions';
+      setBrief('focus-task', hoverTask, 'Nothing was stated for these.');
+      document.getElementById('focus-task-since').textContent = '';
     } else {
-      head.textContent = 'Current objective';
-      setBrief('focus-objective', s && s.objective, 'No journey running. An agent starts one with scout_journey.');
-      document.getElementById('focus-objective-since').textContent =
-        s && s.objective && s.objectiveSince ? 'for ' + held(Date.now() + skew - Date.parse(s.objectiveSince)) : '';
+      head.textContent = 'Doing now';
+      setBrief('focus-task', s && s.task, 'Nothing stated yet.');
+      document.getElementById('focus-task-since').textContent =
+        s && s.task && s.taskSince ? 'for ' + held(Date.now() + skew - Date.parse(s.taskSince)) : '';
     }
   }
   // Once a second, from the status poll: the bar, the brief, and every third time the long feed.
@@ -700,7 +700,7 @@ export const LIVE_PAGE = `<!doctype html>
   });
   document.getElementById('focus-close').addEventListener('click', closeFocus);
   // A re-rendered feed replaces the group under the pointer without a mouseleave; leaving the feed itself still resets.
-  document.getElementById('focus-feed').addEventListener('mouseleave', function () { showObjective(null); });
+  document.getElementById('focus-feed').addEventListener('mouseleave', function () { showTask(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);

package/dist/engine/live.js

@@ -27,7 +27,7 @@ import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
 import { LIVE_PAGE } from "./live-page.js";
-import { JOURNEY_END, JOURNEY_START } from "./memory.js";
+import { JOURNEY_END, JOURNEY_START, TASK_SET } from "./memory.js";
 /** Holds the live view's token, next to status.json. Written owner-only; removed when the engine shuts down. */
 export const LIVE_TOKEN_FILE = "live-token";
 /** `SCENESCOUT_LIVE=off` keeps the engine from opening the live view's port at all. */
@@ -47,32 +47,44 @@ export function feedForSession(log, session, limit, redact = (s) => s) {
         if (e && (e.session ?? session) === session)
             mine.push(e);
     }
-    let objective;
-    for (; i >= 0; i -= 1) {
+    // Two things can be standing when the window opens: a journey, and the
+    // stated task. Walk back until both are known — a journey is what the
+    // session is doing while it runs, exactly as the live view shows it.
+    let goal;
+    let batch;
+    let knowJourney = false;
+    let knowBatch = false;
+    for (; i >= 0 && !(knowJourney && knowBatch); i -= 1) {
         const e = log[i];
         if (!e || (e.session ?? session) !== session)
             continue;
-        if (e.action === JOURNEY_END)
-            break;
-        if (e.action === JOURNEY_START) {
-            objective = e.target;
-            break;
+        if (!knowJourney && (e.action === JOURNEY_END || e.action === JOURNEY_START)) {
+            if (e.action === JOURNEY_START)
+                goal = e.target;
+            knowJourney = true;
+        }
+        if (!knowBatch && e.action === TASK_SET) {
+            batch = e.target;
+            knowBatch = true;
         }
     }
     const lines = [];
     for (const e of mine.reverse()) {
         if (e.action === JOURNEY_START)
-            objective = e.target;
+            goal = e.target;
+        if (e.action === TASK_SET)
+            batch = e.target;
+        const task = goal ?? batch;
         const line = { at: e.at, action: e.action, url: redact(e.url) };
         if (e.target !== undefined)
             line.target = e.target;
         if (e.result !== undefined)
             line.result = e.result;
-        if (objective !== undefined)
-            line.objective = objective;
+        if (task !== undefined)
+            line.task = task;
         lines.push(line);
         if (e.action === JOURNEY_END)
-            objective = undefined;
+            goal = undefined;
     }
     return lines;
 }

package/dist/engine/memory.js

@@ -92,6 +92,8 @@ export function redactSecrets(text) {
 /** The action-log lines that open and close a journey (scout_journey). The feed reads them to tell which goal an action served. */
 export const JOURNEY_START = "journey:start";
 export const JOURNEY_END = "journey:end";
+/** Logged when a session states the task it is starting, so the feed can group the actions that follow under it. */
+export const TASK_SET = "task";
 const EMPTY = { version: 1, states: {}, findings: [] };
 /**
  * Fold another process's memory into ours, losing nothing from either side.

package/dist/engine/task.js

@@ -0,0 +1,65 @@
+/**
+ * The task: a few words saying what a session is DOING right now — the batch
+ * of actions it is performing on the page in front of it.
+ *
+ * It sits under the session's objective, which is the whole remit the agent
+ * was given at attach ("Admin lane: §2 registers, §7 plan gating"). The
+ * objective barely changes; the task changes every time the session moves on
+ * to something else, and it is what tells a person watching what is happening
+ * now.
+ *
+ * The engine sees tool calls, never the reasoning behind them, so it can only
+ * show a task the agent states. Left optional it was usually absent, 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 a few words, 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 a task; the live view shows one line. */
+export const TASK_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_TASK = new Set([
+    "scout_navigate",
+    "scout_back",
+    "scout_click",
+    "scout_type",
+    "scout_select",
+    "scout_press",
+    "scout_upload",
+    "scout_run_plan",
+]);
+export function needsTask(tool) {
+    return NEEDS_TASK.has(tool);
+}
+/**
+ * One line, whitespace collapsed, bounded. Empty input clears the task. A
+ * longer one is cut at a word where it can be and ends in an ellipsis, so a
+ * truncated task reads as truncated rather than as a sentence that stops
+ * mid-word.
+ */
+export function normalizeTask(text) {
+    const line = (text ?? "").replace(/\s+/g, " ").trim();
+    if (line.length <= TASK_MAX)
+        return line;
+    const cut = line.slice(0, TASK_MAX - 1);
+    const lastSpace = cut.lastIndexOf(" ");
+    return `${(lastSpace > TASK_MAX - 24 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}
+/**
+ * What a session is told when it acts with no task standing. It names the
+ * parameter, gives the shape of a good task and says the rule it satisfies —
+ * an agent that reads this once should not need it again.
+ */
+export function taskRefusal(tool) {
+    return (`${tool} needs a task: this session has none, so the live view cannot say what it is doing.\n` +
+        `Pass task:"…" on this call — a few words saying what you are DOING, not what you are checking. ` +
+        `"Filtering the documents register by status", "Filling the deviation form with invalid dates", "Signing in as QA_Team". ` +
+        `Not the acceptance criteria ("…narrows the set and is reflected in the URL"): that is the result you will judge, not the batch you are running. ` +
+        `It stays set until you pass a different one, so a batch costs a few words, 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

@@ -39,7 +39,7 @@ 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 { computeGaps, formatRouteCoverage, generateReport } from "./engine/report.js";
-import { needsObjective, objectiveRefusal, OBJECTIVE_MAX } from "./engine/objective.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";
 /** Live sessions: each name owns an independent BrowserEngine (browser + auth). */
@@ -278,7 +278,7 @@ function writeStatus(session, phase, tool, budgetMs) {
     if (!eng || !dir)
         return;
     // status.json is a poll target that gets pasted into bug reports.
-    const { task, objective, ...described } = eng.liveDescription;
+    const { objective, task, ...described } = eng.liveDescription;
     lastWriter = board.update(session, {
         role: eng.role,
         phase,
@@ -286,8 +286,8 @@ function writeStatus(session, phase, tool, budgetMs) {
         url: redactSecrets(eng.currentUrl),
         ...(budgetMs ? { budgetMs } : {}),
         ...described,
-        ...(task ? { task: redactSecrets(task) } : {}),
         ...(objective ? { objective: redactSecrets(objective) } : {}),
+        ...(task ? { task: redactSecrets(task) } : {}),
     });
     void ensureLive(dir);
     flushStatus(dir);
@@ -310,15 +310,17 @@ 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.
+        // Every acting tool passes through here, so the task 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. `objective`
+        // is the name this parameter had in 2.0 and still works.
         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 stated = args.task ?? args.objective;
+            if (stated !== undefined)
+                eng.setTask(stated);
+            if (needsTask(label) && !eng.hasTask)
+                return Promise.resolve(text(taskRefusal(label), session));
         }
         const exec = async () => {
             writeStatus(session, "running", label, timeoutMs);
@@ -360,17 +362,22 @@ const sessionParam = z
     .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.
+ * What the session is DOING right now. Required by the tools that act
+ * (task.ts) unless one is already standing; shown to whoever is watching the
+ * run, under the session's objective.
  */
-const objectiveParam = z
+const taskParam = z
     .string()
-    .max(OBJECTIVE_MAX)
+    .max(TASK_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. ' +
+    .describe("What you are DOING right now, in a few words: the action, not the acceptance criteria. " +
+    '"Filtering the documents register by status", "Filling the deviation form with invalid dates", "Signing in as QA_Team" — ' +
+    'NOT "§2.4 filtering narrows the set and the filter is reflected in the URL", which is what you are CHECKING, not what you are doing. ' +
+    'Naming the item you are on is fine ("§2.4: filtering the documents register"); keep the rest to what a colleague would see over your shoulder. ' +
+    "It stays set until you pass a different one, so a batch costs a few words, not one per call. " +
     "Required on the tools that act unless a journey or an earlier call already set one.");
+/** The name `task` had in 2.0. Still accepted, so a caller written against that release keeps working. */
+const legacyObjectiveParam = z.string().max(TASK_MAX).optional().describe("Old name for `task` (2.0). Prefer `task`.");
 // 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, {
@@ -441,18 +448,21 @@ server.registerTool("scout_attach", {
             .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."),
         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)"),
-        task: z
+        objective: z
             .string()
             .max(300)
             .optional()
-            .describe("What this session is for, in one sentence (e.g. 'Approve and reject orders as a manager'). Shown to the person watching the live view, next to the goal of whatever scout_journey is active. Worth setting whenever more than one session is running."),
+            .describe('This session\'s objective: the whole remit you were given, in one sentence ("Admin lane: §2 registers, §7 plan gating", ' +
+            '"Approve and reject orders as a manager"). It sits above the task, which is what the session is doing at any moment. ' +
+            "Shown to whoever is watching the run; worth setting whenever more than one session is live."),
+        task: z.string().max(300).optional().describe("Old name for `objective` (2.0). Prefer `objective`."),
         session: z
             .string()
             .max(40)
             .optional()
             .describe("Session name for multi-role runs (e.g. 'admin', 'qa'). Creates/replaces that session's browser and makes it the default. Default: 'default'."),
     },
-}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, browser, viewportWidth, viewportHeight, task, session, }) => {
+}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, browser, viewportWidth, viewportHeight, objective, task, session, }) => {
     try {
         const target = session ?? activeName;
         if (session) {
@@ -513,7 +523,18 @@ server.registerTool("scout_attach", {
             /* conflict detection is best-effort */
         }
         const viewport = viewportWidth && viewportHeight ? { width: viewportWidth, height: viewportHeight } : undefined;
-        const out = await eng.attach({ url, projectDir: projectPath, storageStatePath, mode, headed, browser, viewport, task, memoryStore: store });
+        const out = await eng.attach({
+            url,
+            projectDir: projectPath,
+            storageStatePath,
+            mode,
+            headed,
+            browser,
+            viewport,
+            // `task` is what this was called in 2.0; it named the session's whole remit, which is the objective.
+            objective: objective ?? task,
+            memoryStore: store,
+        });
         eng.role = storageStatePath ? path.basename(storageStatePath).replace(/\.json$/i, "") : "anonymous";
         // Put the session on the board now, so the live view shows it before its
         // first tool call. liveLine() needs the port, so the server is awaited
@@ -608,7 +629,8 @@ server.registerTool("scout_run_plan", {
         }))
             .min(1)
             .max(20),
-        objective: objectiveParam,
+        task: taskParam,
+        objective: legacyObjectiveParam,
         session: sessionParam,
     },
 }, serializedPerSession("scout_run_plan", async ({ steps }, session) => {
@@ -624,7 +646,8 @@ 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,
+        task: taskParam,
+        objective: legacyObjectiveParam,
         session: sessionParam,
     },
 }, serializedPerSession("scout_click", async ({ ref, clicks }, session) => {
@@ -645,7 +668,8 @@ 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,
+        task: taskParam,
+        objective: legacyObjectiveParam,
         session: sessionParam,
     },
 }, serializedPerSession("scout_type", async ({ ref, textValue, value, pressEnter, replace }, session) => {
@@ -680,7 +704,8 @@ 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,
+        task: taskParam,
+        objective: legacyObjectiveParam,
         session: sessionParam,
     },
 }, serializedPerSession("scout_upload", async ({ ref, filePath, fixture, name }, session) => {
@@ -704,7 +729,13 @@ 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"), objective: objectiveParam, session: sessionParam },
+    inputSchema: {
+        ref: z.string(),
+        value: z.string().describe("Option value or label"),
+        task: taskParam,
+        objective: legacyObjectiveParam,
+        session: sessionParam,
+    },
 }, serializedPerSession("scout_select", async ({ ref, value }, session) => {
     try {
         return text(await engineFor(session).select(ref, value), session);
@@ -715,7 +746,12 @@ 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"), objective: objectiveParam, session: sessionParam },
+    inputSchema: {
+        target: z.string().describe("Absolute URL or path like /settings"),
+        task: taskParam,
+        objective: legacyObjectiveParam,
+        session: sessionParam,
+    },
 }, serializedPerSession("scout_navigate", async ({ target }, session) => {
     try {
         return text(await engineFor(session).navigate(target), session);
@@ -726,7 +762,7 @@ server.registerTool("scout_navigate", {
 }));
 server.registerTool("scout_back", {
     description: "Go back in browser history (tests back-button resilience).",
-    inputSchema: { objective: objectiveParam, session: sessionParam },
+    inputSchema: { task: taskParam, objective: legacyObjectiveParam, session: sessionParam },
 }, serializedPerSession("scout_back", async (_args, session) => {
     try {
         return text(await engineFor(session).goBack(), session);
@@ -756,7 +792,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(), objective: objectiveParam, session: sessionParam },
+    inputSchema: { key: z.string(), task: taskParam, objective: legacyObjectiveParam, session: sessionParam },
 }, serializedPerSession("scout_press", async ({ key }, session) => {
     try {
         return text(await engineFor(session).press(key), session);

package/package.json

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

@@ -20,7 +20,7 @@ You are the brain of an exploratory UI tester. The SceneScout MCP server gives y
    - **Source available?** Use it beyond the scan: when you file a finding, read the component or handler behind it and name the file and the likely fix — that is the difference between "the save button does nothing" and a finding a developer can act on in one step.
 3. **Ensure the app is running.** Full-stack markers in the scan → do NOT launch the stack yourself; confirm the URL responds (you may curl it) or ask the user. Auto-launch only simple single-package frontends.
 4. **Pick auth.** `--role X` → pass that storage-state file. Unspecified → least-privileged role; say so.
-5. **`scout_attach`** with url, projectPath, storageStatePath, and the write **mode** — the DB behind the app may be live, so the engine enforces this at the network layer:
+5. **`scout_attach`** with url, projectPath, storageStatePath, an `objective` (this session's whole remit, shown live), and the write **mode** — the DB behind the app may be live, so the engine enforces this at the network layer:
    - `observe` (`--observe`): NOTHING but GET requests leaves the page (login and token refresh excepted) — no form submission reaches the server. **This is your default for a remote URL with no source** (see step 2): such a target is far more likely to hold real data, and in `read-only` every form you submit creates a record somebody has to clean up. Forms you fill cannot be submitted; the gap ledger says so and that is the honest result. Move to `read-only` only when the user says form submissions are acceptable there.
    - `read-only` (default when the source is here, i.e. a local or dev app): destructive labels blocked in the UI AND all PUT/PATCH/DELETE + destructive POSTs blocked on the wire. Ordinary form POSTs still go through. Use unless told otherwise.
    - `safe-write` (`--safe-write`, or the user asks to test creating/editing things): create freely — **prioritize testing CREATE flows** — then edit/delete ONLY the records you created (the engine tracks your creations and blocks mutations on anything else). Never attempt to clean up or modify pre-existing data.
@@ -37,7 +37,7 @@ 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. **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.
+7. **Say what you are doing: `task` is required before a tool acts.** A session shows two lines to whoever is watching. Its **objective** is the whole remit you were given, set once at `scout_attach {objective}` ("Admin lane: §2 registers, §7 plan gating", "Approve and reject orders as a manager"). Its **task** is what you are doing *right now*, and every tool that changes the app or the page — `scout_navigate`, `scout_back`, `scout_click`, `scout_type`, `scout_select`, `scout_press`, `scout_upload`, `scout_run_plan` — takes it: a few words for the batch in front of you ("Filtering the documents register by status", "Filling the deviation form with invalid dates", "Signing in as QA_Team"). Say what you are DOING, not what you are checking — "§2.4 filtering narrows the set and is reflected in the URL" is the acceptance criteria, which is the result you will judge, not the batch you are running; naming the item is fine ("§2.4: filtering the documents register"). The task STAYS SET until you pass a different one, so a batch costs a few words, not one per call — pass a fresh one whenever you move on. Acting with none standing is refused: the person watching would otherwise see a session clicking through their app with nothing to say why. `scout_journey {action:"start", goal:…}` sets the task too while it runs — use a journey when you are MEASURING a whole user task, the parameter for everything else.
 
 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.
@@ -70,7 +70,7 @@ Some flows need a TEAM — a document one role submits and another approves, a r
 - While roles are NOT collaborating, use each one productively where its permissions matter (admin in /admin surfaces, low-privilege probing for permission leaks) — same coverage contract, different vantage points.
 - **Infer the PERSONA behind each role, and write it down.** From what a role can see and do (its nav, its dashboard, the capability matrix in the report), state what this person is FOR: "qa = reviewer — approves orders, assigns reviewers, no admin" / "user = front-line user — reads documents, completes reviews, raises orders". Record it with `scout_note {section:'roles'}`. Then test the persona's WORLD, not just the permissions: does the operator's landing page serve an operator? Is anything they need N clicks deep? The capability matrix's divergent rows are questions, not verdicts — each is either a correct boundary or a gap ("should this role be able to do this?"); say which you believe it is and why.
 - `scout_close {all: true}` at the end of a multi-role run; `scout_close {session}` to drop one role early.
-- **Several agents in parallel** (subagents or a workflow, each driving its own session): each agent attaches its session when it STARTS and closes it by name when it FINISHES. Never open sessions ahead for agents that have not started, and never hand an open session from one agent to the next: an agent waiting for its turn should hold no browser. Give each session a `task` when you attach it (`scout_attach {session, task:"Approve and reject orders as a manager"}`) and wrap each goal in `scout_journey`: the live view shows the task and the active journey's goal beside the session's feed, which is how the person watching knows what every agent is for. Keep that goal TRUE: one journey per goal, one goal per thing you are checking ("Save a settings change as the auditor", not "Check every page"), ended the moment it is decided and the next one started before you move on. A journey that outlives its goal shows the viewer an objective the session left behind minutes ago. Run roughly as many agents at once as the machine has cores, less two, since each drives a real browser; beyond that they only queue. Exploring one area is well within a mid-tier model, so run these agents on one (Sonnet or its equivalent in your client) unless the user names a model; keep the larger model for the agent that plans the split and writes the report. No agent may call `scout_close {all: true}` while others run — only the last step, once every agent has finished.
+- **Several agents in parallel** (subagents or a workflow, each driving its own session): each agent attaches its session when it STARTS and closes it by name when it FINISHES. Never open sessions ahead for agents that have not started, and never hand an open session from one agent to the next: an agent waiting for its turn should hold no browser. Give each session an `objective` when you attach it (`scout_attach {session, objective:"Approve and reject orders as a manager"}`) and wrap each goal in `scout_journey`: the live view shows that objective and the task it is on beside the session's feed, which is how the person watching knows what every agent is for. Keep that goal TRUE: one journey per goal, one goal per thing you are checking ("Save a settings change as the auditor", not "Check every page"), ended the moment it is decided and the next one started before you move on. A journey that outlives its goal shows the viewer an objective the session left behind minutes ago. Run roughly as many agents at once as the machine has cores, less two, since each drives a real browser; beyond that they only queue. Exploring one area is well within a mid-tier model, so run these agents on one (Sonnet or its equivalent in your client) unless the user names a model; keep the larger model for the agent that plans the split and writes the report. No agent may call `scout_close {all: true}` while others run — only the last step, once every agent has finished.
 
 ## The impatient-user pass (extensive)
 

package/dist/engine/objective.js

@@ -1,49 +0,0 @@
-/**
- * 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.`);
-}