scenescout 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # scenescout
 
+## 3.2.0
+
+### Minor Changes
+
+- a3c7ed4: Parallel lanes hand their results back as one typed lane report, not prose. A new `scout_lane_report` tool serves both halves: without a reply it returns the paragraph to put in a lane's prompt (verdict, severity and category from closed sets, a calibrated confidence per decision, a bounded evidence signature, routes covered, what blocked the lane), and with one it parses what the lane handed back and returns the one-line fold or the reason the reply was refused. The instruction is generated from the same constants the parser checks and states every limit the parser enforces. The finding categories now live in one list shared by `scout_finding`, the lane report and the skill text. The skill's parallel-agents section tells the planner to use the tool and to run lanes at medium effort, the pick from a benchmark under `scripts/bench/` that measured both reply shapes at every effort level the CLI accepts.
+
+### Patch Changes
+
+- 0b99401: The read-only write policy no longer refuses a control because of a destructive word in its description. A card or tile that is a button carries prose in its accessible name, a title then a sentence about it, and a word in that sentence describes what the thing is for rather than what the click does. A label that is prose, longer than six words and containing a sentence, is now judged by its first six words, where the verb lives; every other label is still judged whole, so a long confirm button stays refused. The pattern still sees the whole label, so exemptions that look ahead ("reset filters") keep working. This is what refused the manager card on a sign-in page whose sentence mentioned orders that need sign-off. Separately, "sign off" is now read as the noun when the word before it says so ("Needs sign-off", "Awaiting sign-off", "Send for sign-off"), so those short labels are no longer refused either.
+
+## 3.1.1
+
+### Patch Changes
+
+- 99562e7: The run's page now notices when the engine behind it has exited.
+  
+  That address is served by a process. Once the process is gone, reloading it
+  gets the browser's own "site can't be reached" and the tab is lost, although
+  everything on the page was still readable a moment earlier. The served copy
+  now watches the engine, and when it goes says so in place: the page is still
+  good, reloading will not reach anything, and the copy that survives — with its
+  frames — is at the path it names, ready to copy. Leaving the page from then on
+  asks first, so a reflexive refresh cannot throw it away.
+  
+  A browser will not follow a `file://` link from a served page, so the saved
+  copy cannot be opened from there; the path is offered instead. The copy on
+  disk carries none of this and stays a plain document with no script in it.
+
 ## 3.1.0
 
 ### Minor Changes

package/dist/engine/lane.js

@@ -0,0 +1,169 @@
+/**
+ * The lane report: what an agent exploring one area in parallel hands back to
+ * the agent that split the work, as typed decisions rather than prose.
+ *
+ * A parallel run has one planning agent and several lanes, each driving its
+ * own browser. A lane used to come back with a page of markdown, which the
+ * planner then had to read, re-judge and re-type into findings: a model pass
+ * over every lane's output, with nothing stopping a lane from inventing a
+ * category or writing "Low-Medium" as a severity.
+ *
+ * This module is the alternative, borrowed from decision-only models: every
+ * answer is a value from a closed set, carries a calibrated confidence, and
+ * is checked by a schema on arrival. The planner folds a report with a
+ * function call, not a reading.
+ *
+ * Both halves are reached through the scout_lane_report tool: with no reply
+ * it returns the instruction the planner puts in a lane's prompt, with one it
+ * parses it. The instruction is generated from the same constants the parser
+ * checks, and a table test asserts every value and every cap the parser
+ * enforces is in the text, because a limit the lane is not told refuses good
+ * replies: three of the first ten real replies were lost that way.
+ *
+ * Pure logic, no browser, so every rule here is table-tested.
+ */
+import { z } from "zod";
+import { FINDING_CATEGORIES } from "./memory.js";
+/** Upper bound on the decisions and routes arrays, so a report is always small enough to hold whole. */
+export const LANE_MAX_ITEMS = 255;
+/** A signature such as "GET /api/things 500", not a sentence. */
+export const LANE_EVIDENCE_MAX = 160;
+/** A lane names its own observations, and a name that says what was seen needs more than forty characters. */
+export const LANE_OBSERVATION_MAX = 64;
+/** One line saying what blocked the lane; the detail belongs in a finding. */
+export const LANE_BLOCKED_BY_MAX = 200;
+/** The planner chooses the lane name, so this cap is on the planner's side; it is stated all the same. */
+export const LANE_NAME_MAX = 40;
+/** A route as the lane saw it, query string included. */
+export const LANE_ROUTE_MAX = 200;
+export const LANE_SEVERITIES = ["high", "medium", "low"];
+/** The same set scout_finding accepts, so a lane can report every finding it filed. */
+export const LANE_CATEGORIES = FINDING_CATEGORIES;
+export const LANE_VERDICTS = ["defect", "not_a_defect", "unsure"];
+export const LANE_STATUSES = ["complete", "partial", "blocked"];
+const Confidence = z.number().min(0).max(1);
+/**
+ * One observation judged: is it a defect, how bad, of what kind, and how sure
+ * the lane is. A non-defect may still carry a category and a signature: an
+ * "unsure" with a tentative category tells the planner where to look.
+ */
+export const LaneDecision = z
+    .object({
+    /** A short id the lane assigns, unique within the report, so a decision can be traced back to what the lane saw. */
+    observation: z.string().min(1).max(LANE_OBSERVATION_MAX),
+    verdict: z.enum(LANE_VERDICTS),
+    severity: z.enum(LANE_SEVERITIES).nullable(),
+    category: z.enum(LANE_CATEGORIES).nullable(),
+    confidence: Confidence,
+    /** The same machine signature scout_finding takes as its cross-run dedup key. */
+    evidence: z.string().min(1).max(LANE_EVIDENCE_MAX).nullable(),
+})
+    .strict()
+    .superRefine((d, ctx) => {
+    if (d.verdict === "defect" && (d.severity === null || d.category === null)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a defect needs a severity and a category" });
+    }
+});
+export const LaneReport = z
+    .object({
+    lane: z.string().min(1).max(LANE_NAME_MAX),
+    status: z.enum(LANE_STATUSES),
+    decisions: z.array(LaneDecision).max(LANE_MAX_ITEMS),
+    /** The routes the lane covered, as it saw them; the planner normalises when it compares them with the split. */
+    routes: z.array(z.string().min(1).max(LANE_ROUTE_MAX)).max(LANE_MAX_ITEMS),
+    /** Required when the status is "blocked"; a "partial" lane may use it to say what cut it short; a "complete" one has nothing to put there. */
+    blocked_by: z.string().min(1).max(LANE_BLOCKED_BY_MAX).nullable(),
+})
+    .strict()
+    .superRefine((r, ctx) => {
+    if (r.status === "blocked" && r.blocked_by === null) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a blocked lane must say what blocked it", path: ["blocked_by"] });
+    }
+    if (r.status === "complete" && r.blocked_by !== null) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a complete lane cannot also have been blocked", path: ["blocked_by"] });
+    }
+    const seen = new Set();
+    r.decisions.forEach((d, i) => {
+        if (seen.has(d.observation)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `observation "${d.observation}" is judged twice`, path: ["decisions", i, "observation"] });
+        }
+        seen.add(d.observation);
+    });
+});
+const FENCE_OPEN = /^```[a-z]*\s*\n/i;
+const FENCE_CLOSE = /\n?```\s*$/;
+/**
+ * The reply is one JSON object and nothing else. A fenced block around it is
+ * tolerated, because every model has been trained to add one; text before or
+ * after it is not, because the point is that no one has to read the reply.
+ * The reason names what was wrong, since the planner relays it to the lane.
+ *
+ * With `expectedLane`, a report that names another lane is refused: the
+ * planner joins reports to the split by name, and a reply that carries the
+ * wrong one would be folded into the wrong lane.
+ */
+export function parseLaneReport(text, expectedLane) {
+    let body = text.trim();
+    if (FENCE_OPEN.test(body)) {
+        if (!FENCE_CLOSE.test(body))
+            return { ok: false, reason: "the closing ``` must end the reply, with no text after it" };
+        body = body.replace(FENCE_OPEN, "").replace(FENCE_CLOSE, "").trim();
+    }
+    if (!body.startsWith("{"))
+        return { ok: false, reason: "the reply must be one JSON object, with no text before it" };
+    let raw;
+    try {
+        raw = JSON.parse(body);
+    }
+    catch (e) {
+        const message = e.message;
+        const trailing = /after JSON|Unexpected non-whitespace/i.test(message);
+        return { ok: false, reason: trailing ? "the reply must be one JSON object, with no text after it" : `not valid JSON: ${message}` };
+    }
+    const result = LaneReport.safeParse(raw);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const at = issue.path.length ? ` at ${issue.path.join(".")}` : "";
+        return { ok: false, reason: `${issue.message}${at}` };
+    }
+    if (expectedLane !== undefined && result.data.lane !== expectedLane) {
+        return { ok: false, reason: `the report names lane "${result.data.lane}", but this reply was asked of lane "${expectedLane}"` };
+    }
+    return { ok: true, report: result.data };
+}
+/**
+ * The paragraph the planner puts in every lane's prompt. It is generated from
+ * the same constants the parser checks, so it can never list a value the
+ * parser would refuse, and it states every cap the parser enforces.
+ */
+export function laneReportInstruction(lane) {
+    return [
+        "Reply with ONE JSON object and nothing else — no prose before or after it, no explanation, no headings. A fenced ```json block is fine.",
+        `Shape: {"lane":${JSON.stringify(lane)},"status":<${quoteAll(LANE_STATUSES)}>,"decisions":[…],"routes":[…],"blocked_by":<string or null>}.`,
+        `Each decision: {"observation":<a short id for what was observed, unique in the report, at most ${LANE_OBSERVATION_MAX} characters>,"verdict":<${quoteAll(LANE_VERDICTS)}>,"severity":<${quoteAll(LANE_SEVERITIES)} or null>,"category":<${quoteAll(LANE_CATEGORIES)} or null>,"confidence":<0..1>,"evidence":<machine signature such as "GET /api/things 500", or null>}.`,
+        `A "defect" must carry a severity and a category. "evidence" is a signature, not a sentence: at most ${LANE_EVIDENCE_MAX} characters. "confidence" is how sure you are of the verdict, calibrated: 0.5 means a coin flip, 0.95 means you would bet on it.`,
+        `"routes" lists the routes you covered, each at most ${LANE_ROUTE_MAX} characters. "blocked_by" is one line of at most ${LANE_BLOCKED_BY_MAX} characters saying what stopped you: required when the status is "blocked", allowed with "partial", null with "complete"; the detail belongs in a finding. The lane name is at most ${LANE_NAME_MAX} characters. At most ${LANE_MAX_ITEMS} decisions and ${LANE_MAX_ITEMS} routes. Unknown keys are refused.`,
+        "The object IS your final report: whatever hands it back must hand back the object verbatim, not a summary of it.",
+    ].join(" ");
+}
+function quoteAll(values) {
+    return values.map((v) => `"${v}"`).join("|");
+}
+/** The planner's fold: one line per lane, with the numbers it decides on. */
+export function summarizeLaneReport(r) {
+    const defects = r.decisions.filter((d) => d.verdict === "defect");
+    const high = defects.filter((d) => d.severity === "high").length;
+    const unsure = r.decisions.filter((d) => d.verdict === "unsure").length;
+    const mean = r.decisions.length ? r.decisions.reduce((s, d) => s + d.confidence, 0) / r.decisions.length : 0;
+    const parts = [
+        r.status,
+        `${r.decisions.length} judged`,
+        `${defects.length} defects (${high} high)`,
+        `${unsure} unsure`,
+        `mean confidence ${mean.toFixed(2)}`,
+        `${r.routes.length} routes`,
+    ];
+    if (r.blocked_by)
+        parts.push(`blocked by ${r.blocked_by}`);
+    return `${r.lane}: ${parts.join(", ")}`;
+}

package/dist/engine/memory.js

@@ -1,6 +1,30 @@
 import fs from "node:fs";
 import path from "node:path";
 import { normalizePath, shortHash } from "./fingerprint.js";
+/**
+ * The kinds a finding can be. One list: scout_finding's input schema, the lane
+ * report a parallel agent hands back, and the skill text all read it from
+ * here, so a category cannot exist in one and be refused by another.
+ */
+export const FINDING_CATEGORIES = [
+    "console-error",
+    "page-error",
+    "http-error",
+    "network",
+    "dead-end",
+    "ux-confusing",
+    "ux-polish",
+    "visual",
+    "a11y",
+    "permission-leak",
+    "data-inconsistency",
+    "stale-state",
+    "data-loss",
+    "performance",
+    "security",
+    "missing-testid",
+    "other",
+];
 /** An element class must appear on this many routes at minimum before it can count as shared chrome. */
 const CHROME_MIN_ROUTES = 4;
 /** …and on at least this share of all visited routes (a majority — "it's on every page"). */

package/dist/engine/policy.js

@@ -22,7 +22,11 @@ const DESTRUCTIVE_PATTERNS = [
     /\breset\b(?!\s+(filters?|zoom|search|view|sort|order|form|password|layout|columns?|selection|preferences?|defaults?))/i,
     /\bdiscard\b/i,
     /\bcancel subscription\b/i,
-    /\bsign(?: |-)?off\b/i,
+    // The verb: a control that signs the user off, alone or after another verb
+    // ("Save and sign off"). The noun is how approval apps label things, and it
+    // is told by the word before it ("Needs sign-off", "Awaiting sign-off",
+    // "Send for sign-off"); those destroy nothing. Same shape as the reset rule.
+    /(?<!\b(?:needs?|awaiting|awaits|pending|requires?|required|for|before|after|without|of|the|a|an|its|their|your|my)\s)\bsign(?: |-)?off\b/i,
     // The tool is generic — destructive labels come in many languages.
     /\b(eliminar|borrar|suprimir)\b/i, // es
     /\b(excluir|apagar|remover)\b/i, // pt
@@ -74,8 +78,55 @@ export function isDestructiveWire(url, body) {
 }
 /** Auth/session flows must work even under strict write policies (login, token refresh, logout). */
 export const AUTH_FLOW_RE = /\/(auth|login|logout|signin|sign-in|signup|sign-up|session|token|verify|oauth|sso|password)\b/i;
+/**
+ * A control's label is a verb phrase: "Delete", "Remove user", "Archive the
+ * project". A card or tile that is a button carries prose in its accessible
+ * name, the title then a sentence about it ("Manager Approves or rejects
+ * orders that need sign-off."), and a destructive word in that sentence
+ * describes what the thing is for; it is not the command the click sends, the
+ * same distinction the wire policy draws for words inside a POST body.
+ *
+ * So a label that is prose, longer than this many words AND containing a
+ * sentence, is judged by its head, the first few words, where the imperative
+ * lives: a match counts only when it STARTS there. The pattern still sees the
+ * whole label, so "reset filters" straddling the boundary keeps the context
+ * its exemption looks ahead at. Everything else is judged whole: a short
+ * label, a long one with no sentence in it ("Yes, I am sure I want to delete
+ * this"), a script written without spaces.
+ *
+ * A confirm button whose long label ends in a full stop and puts the verb
+ * late is the residue this lets through. The wire policy below still blocks
+ * the DELETE, PUT, PATCH or verb-path POST it would send; a plain POST to a
+ * neutral path passes in read-only, as it does for any control this list does
+ * not name.
+ */
+export const LABEL_HEAD_WORDS = 6;
+/** The head: up to LABEL_HEAD_WORDS whitespace-separated words from the start. */
+const HEAD_RE = new RegExp(`^\\s*(?:\\S+\\s+){0,${LABEL_HEAD_WORDS - 1}}\\S+`);
+/** A sentence ends in the label: a full stop, question or exclamation mark followed by space or the end. */
+const SENTENCE_RE = /[.!?](?:\s|$)/;
+/**
+ * Where a match must start to count: the end of the head for prose, the end
+ * of the label for everything else.
+ */
+function matchLimit(label) {
+    if (!SENTENCE_RE.test(label))
+        return label.length;
+    const head = HEAD_RE.exec(label);
+    if (!head || head[0].length === label.trimEnd().length)
+        return label.length;
+    return head[0].length;
+}
 export function isDestructive(...labels) {
-    return labels.some((label) => typeof label === "string" && label.length > 0 && DESTRUCTIVE_PATTERNS.some((re) => re.test(label)));
+    return labels.some((label) => {
+        if (typeof label !== "string" || label.length === 0)
+            return false;
+        const limit = matchLimit(label);
+        return DESTRUCTIVE_PATTERNS.some((re) => {
+            const m = re.exec(label);
+            return m !== null && m.index < limit;
+        });
+    });
 }
 export function destructiveRefusal(label, mode = "read-only") {
     return (`REFUSED by ${mode} policy: "${label}" matches a destructive-action pattern. ` +

package/dist/engine/replay.js

@@ -254,8 +254,8 @@ export function renderMarkdown(md, evidence = [], framePrefix = "", savedAt = ""
     return out.join("\n");
 }
 const STYLE = `
-:root { color-scheme: light dark; --bg:#f6f7f9; --panel:#fff; --line:#d9dde3; --text:#15181d; --muted:#5d6673; --accent:#2563eb; --bad:#b91c1c; }
-@media (prefers-color-scheme: dark) { :root { --bg:#0e1116; --panel:#161a21; --line:#2a303a; --text:#e6e9ee; --muted:#98a2b3; --accent:#7aa2ff; --bad:#fca5a5; } }
+:root { color-scheme: light dark; --bg:#f6f7f9; --panel:#fff; --line:#d9dde3; --text:#15181d; --muted:#5d6673; --accent:#2563eb; --bad:#b91c1c; --warn:#7c4a03; --warn-bg:#fef3c7; }
+@media (prefers-color-scheme: dark) { :root { --bg:#0e1116; --panel:#161a21; --line:#2a303a; --text:#e6e9ee; --muted:#98a2b3; --accent:#7aa2ff; --bad:#fca5a5; --warn:#fbbf24; --warn-bg:#3a2a08; } }
 * { box-sizing: border-box; }
 body { margin:0; background:var(--bg); color:var(--text); font:15px/1.55 system-ui,-apple-system,"Segoe UI",sans-serif; }
 header { position:sticky; top:0; z-index:2; display:flex; flex-wrap:wrap; gap:8px 16px; align-items:baseline; padding:14px 20px; background:var(--panel); border-bottom:1px solid var(--line); }
@@ -303,6 +303,13 @@ details.evidence > summary { cursor:pointer; color:var(--muted); font-size:13px;
 details.evidence .shots { display:flex; flex-wrap:wrap; gap:14px; margin-top:12px; }
 details.evidence figure { margin:0; max-width:min(100%,460px); }
 details.evidence img { width:100%; max-height:300px; object-fit:cover; object-position:top; border:1px solid var(--line); border-radius:6px; display:block; background:var(--panel); }
+#gone-bar { position:sticky; top:0; z-index:3; margin:0; padding:14px 22px; background:var(--warn-bg); color:var(--warn);
+  border-bottom:1px solid var(--line); }
+#gone-bar p { margin:0 0 6px; max-width:68ch; }
+#gone-bar .path { display:flex; flex-wrap:wrap; gap:10px; align-items:center; }
+#gone-bar code { font:12px/1.6 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; user-select:all; }
+#gone-bar button { font:inherit; padding:4px 10px; border:1px solid currentColor; border-radius:6px; background:transparent; color:inherit; cursor:pointer; }
+#gone-bar .why { margin:0; font-size:12px; opacity:.8; }
 .onDisk { display:block; margin-top:4px; color:var(--muted); font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
 header .served { flex:1 1 100%; margin:6px 0 0; color:var(--muted); font-size:12px; }
 header .served code { font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
@@ -312,6 +319,53 @@ figure.gone img, a.gone img { display:none; }
 a.frame.gone { display:block; max-width:min(100%,720px); }
 details.evidence figcaption { margin-top:4px; color:var(--muted); font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
 `;
+/**
+ * Only the SERVED copy carries this. It watches the engine, and the moment the
+ * engine is gone it says so, because from then on a refresh gets the browser's
+ * "site can't be reached" and the tab is lost for nothing — this page is still
+ * perfectly readable, and the copy on disk is the one that survives.
+ *
+ * A browser refuses to follow a `file://` link from an `http://` page, so the
+ * saved copy cannot be opened from here. The path is offered to copy instead.
+ *
+ * No template literals and no backticks: this whole module is one.
+ */
+function exitWatch(savedFile) {
+    return ("<script>(function () {\n" +
+        "  var saved = " +
+        JSON.stringify(savedFile) +
+        ";\n" +
+        "  var gone = false;\n" +
+        "  var bar = document.getElementById('gone-bar');\n" +
+        "  function ended() {\n" +
+        "    if (gone) return;\n" +
+        "    gone = true;\n" +
+        "    bar.hidden = false;\n" +
+        "    document.body.classList.add('engine-gone');\n" +
+        "  }\n" +
+        "  function check() {\n" +
+        "    fetch('api/status', { cache: 'no-store' })\n" +
+        "      .then(function (r) { if (!r.ok && r.status >= 500) ended(); })\n" +
+        "      .catch(ended);\n" +
+        "  }\n" +
+        "  setInterval(check, 5000);\n" +
+        "  check();\n" +
+        "  document.getElementById('gone-copy').addEventListener('click', function () {\n" +
+        "    var self = this;\n" +
+        "    function said(text) { self.textContent = text; setTimeout(function () { self.textContent = 'Copy the path'; }, 2000); }\n" +
+        "    if (navigator.clipboard && navigator.clipboard.writeText) {\n" +
+        "      navigator.clipboard.writeText(saved).then(function () { said('Copied'); }, function () { said('Select it and copy'); });\n" +
+        "    } else { said('Select it and copy'); }\n" +
+        "  });\n" +
+        "  // Refresh, close, back — all of them lose this page once the engine has\n" +
+        "  // exited, and none of them can be told apart here. Ask first.\n" +
+        "  window.addEventListener('beforeunload', function (e) {\n" +
+        "    if (!gone) return;\n" +
+        "    e.preventDefault();\n" +
+        "    e.returnValue = '';\n" +
+        "  });\n" +
+        "})();</script>");
+}
 /** The whole document: one file, no external assets, opens from the file system. */
 export function buildReplayHtml(input) {
     const framed = input.sessions.some((s) => s.steps.some((x) => x.frame));
@@ -333,6 +387,13 @@ export function buildReplayHtml(input) {
   ${savedAt ? `<p class="served">This page is served by the engine and goes when it does. The copy that stays is <code>${escapeHtml(savedAt)}/report.html</code>, beside the frames it shows.</p>` : ""}
   <nav><a href="#report">Report</a><a href="#steps">Steps</a></nav>
 </header>
+${savedAt
+        ? `<div id="gone-bar" role="alert" data-testid="run-engine-gone" hidden>
+  <p><b>The engine has exited.</b> Everything here is still readable, but reloading this address will not reach anything. The copy that survives, with its frames, is on disk:</p>
+  <p class="path"><code>${escapeHtml(savedAt)}/report.html</code> <button type="button" id="gone-copy" data-testid="run-copy-path">Copy the path</button></p>
+  <p class="why">A browser will not open a file from a served page, so it has to be opened from there.</p>
+</div>`
+        : ""}
 <main>
 <h2 id="report">Report</h2>
 ${renderMarkdown(input.markdown, input.evidence ?? [], prefix, savedAt)}
@@ -342,6 +403,7 @@ ${renderMarkdown(input.markdown, input.evidence ?? [], prefix, savedAt)}
         : "This run was not recorded, so there are no frames — attach with record:true to keep them."}</p>
 ${sessions || "<p>No session recorded any action.</p>"}
 </main>
+${savedAt ? exitWatch(`${savedAt}/report.html`) : ""}
 </body>
 </html>
 `;

package/dist/mcp-server.js

@@ -34,7 +34,8 @@ import { ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, McpError }
 import { z } from "zod";
 import { BrowserEngine } from "./engine/browser.js";
 import { reapOrphanBrowsers } from "./engine/reaper.js";
-import { MemoryStore, redactSecrets } from "./engine/memory.js";
+import { FINDING_CATEGORIES, MemoryStore, redactSecrets } from "./engine/memory.js";
+import { LANE_NAME_MAX, laneReportInstruction, parseLaneReport, summarizeLaneReport } from "./engine/lane.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";
@@ -483,6 +484,30 @@ server.server.setRequestHandler(GetPromptRequestSchema, (request) => {
     }
     return { messages: [{ role: "user", content: { type: "text", text: message } }] };
 });
+// The lane report: how a parallel agent hands its results back to the planner
+// as typed decisions. One tool for both halves, so the instruction a lane is
+// given and the parser its reply meets are the same code.
+server.registerTool("scout_lane_report", {
+    description: "For a run split across parallel agents (lanes). Without `reply`: returns the paragraph to put in a lane's prompt, telling it to hand back ONE typed JSON object (verdicts, severities and categories from closed sets, a calibrated confidence per decision, routes covered, what blocked it). " +
+        "With `reply`: parses what the lane handed back and returns the one-line fold (defects, highs, unsure, mean confidence, routes) or the reason it was refused, to relay to the lane once. Touches no browser.",
+    inputSchema: {
+        lane: z.string().min(1).max(LANE_NAME_MAX).describe("The lane's name, as used in its session"),
+        reply: z.string().optional().describe("The text the lane handed back; omit to get the instruction instead"),
+    },
+}, async ({ lane, reply }) => {
+    try {
+        if (reply === undefined)
+            return { content: [{ type: "text", text: laneReportInstruction(lane) }] };
+        const parsed = parseLaneReport(reply, lane);
+        const out = parsed.ok
+            ? `Lane report accepted — ${summarizeLaneReport(parsed.report)}`
+            : `Lane report REFUSED: ${parsed.reason}. Ask the lane once for the corrected object; do not re-judge its prose.`;
+        return { content: [{ type: "text", text: out }] };
+    }
+    catch (err) {
+        return errorText(err);
+    }
+});
 server.registerTool("scout_scan", {
     description: "Scan a project directory to discover the frontend workspace, framework, routes, dev command, Playwright auth storage states, and testid conventions. Run this first.",
     inputSchema: { projectPath: z.string().describe("Absolute path to the project root") },
@@ -955,27 +980,7 @@ server.registerTool("scout_finding", {
     description: "Record a structured finding (bug, UX issue, or improvement). Deduplicates across runs; automatically captures the recent action trace as the repro. Use for anything worth reporting: crashes, oracle violations you confirmed, dead ends, confusing UX, permission leaks, missing testids — and design-audit improvement opportunities (ux-polish) with their concrete measurements.",
     inputSchema: {
         severity: z.enum(["high", "medium", "low"]),
-        category: z
-            .enum([
-            "console-error",
-            "page-error",
-            "http-error",
-            "network",
-            "dead-end",
-            "ux-confusing",
-            "ux-polish",
-            "visual",
-            "a11y",
-            "permission-leak",
-            "data-inconsistency",
-            "stale-state",
-            "data-loss",
-            "performance",
-            "security",
-            "missing-testid",
-            "other",
-        ])
-            .describe("Pick the closest — use 'other' only when nothing fits"),
+        category: z.enum(FINDING_CATEGORIES).describe("Pick the closest — use 'other' only when nothing fits"),
         title: z.string().describe("One-line summary of the defect"),
         detail: z.string().describe("What happened, what was expected, and the evidence"),
         evidence: z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.1.0",
+  "version": "3.2.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",
@@ -71,7 +71,7 @@
     "mcp-check": "npm run build && npm run mcp-check:run",
     "mcp-check:run": "tsx scripts/mcp-check.ts",
     "test": "npm run build && npm run test:unit && npm run smoke:run && npm run mcp-check:run",
-    "test:unit": "npm run scan-test && npm run oracle-test && npm run policy-test && npm run fixture-test && npm run dispatch-test && npm run design-test && npm run contract-test && npm run memory-test && npm run install-test && npm run live-test && npm run demo-test && npm run hygiene-test",
+    "test:unit": "npm run scan-test && npm run oracle-test && npm run policy-test && npm run fixture-test && npm run dispatch-test && npm run design-test && npm run contract-test && npm run lane-test && npm run memory-test && npm run install-test && npm run live-test && npm run demo-test && npm run hygiene-test",
     "scan-test": "tsx scripts/scan-test.ts",
     "oracle-test": "tsx --test scripts/oracle-test.ts",
     "policy-test": "tsx --test scripts/policy-test.ts",
@@ -79,6 +79,7 @@
     "dispatch-test": "tsx --test scripts/dispatch-test.ts",
     "design-test": "tsx --test scripts/design-test.ts",
     "contract-test": "tsx --test scripts/contract-test.ts",
+    "lane-test": "tsx --test scripts/lane-test.ts",
     "memory-test": "tsx --test scripts/memory-test.ts",
     "install-test": "tsx --test scripts/install-test.ts",
     "live-test": "tsx --test scripts/live-test.ts",

package/skills/scenescout/SKILL.md

@@ -71,6 +71,7 @@ Some flows need a TEAM — a document one role submits and another approves, a r
 - **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 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.
+- **Lanes report in typed decisions, not prose.** Each lane files its findings with `scout_finding` as it goes, so the report already has them; what the lane hands BACK to the planner is one JSON object, the lane report, and nothing else. Get the paragraph to put in a lane's prompt from `scout_lane_report {lane}`: it names the shape (`status`, one decision per observation with `verdict`, `severity`, `category`, a calibrated `confidence` and a machine-signature `evidence`, the `routes` covered, `blocked_by`), every value's closed set (the categories are `scout_finding`'s) and every length limit, because a limit a lane is not told refuses good replies. When the lane hands back, pass its text to `scout_lane_report {lane, reply}`: it returns the one-line fold (defects, highs, unsure, mean confidence, routes, what blocked it) or the reason the reply was refused. Relay a refusal to the lane once and ask for the corrected object; never re-judge its prose yourself, and tell every lane that the object IS its final report, since a lane that writes the object and then hands back a summary of it has failed. The planner then folds lanes by counting, not by reading: a lane's reply is a few hundred tokens whatever it found, and a value the schema refuses is caught at the boundary instead of becoming a severity like "Low-Medium" in the report. Where the client lets you set a lane's reasoning effort, use **medium**: in this project's benchmark it judged as well as high in three-quarters of the time and under half of xhigh, low inflated severities, and max took three minutes per lane for no better agreement.
 
 ## The impatient-user pass (extensive)
 
@@ -91,7 +92,7 @@ The engine is self-healing (orphaned browsers reaped, wedged calls time out with
 - Tabs and views (`?tab=…`) are distinct states in coverage — prefer clicking the actual tab controls when testing a flow; deep-link only to re-verify.
 - **Lifecycle:** if the user says something is fixed, or the evidence no longer reproduces on a route you re-tested, mark it with `scout_resolve {id}` (spelled `findingId` if you prefer the long form). Historical findings in the report are unverified — don't re-report them as new.
 - **A `SHARED CHROME` block in a design audit is ONE finding, not one per page.** Those elements (sidebar, header, breadcrumb bar) are the app shell; the audit already excludes them from the page's score and reports them once. File a single finding for the shell and move on — filing per-page produced five separate tickets for two CSS declarations in a real run.
-- **`scout_finding` takes `severity`, `category`, `title`, `detail` and `evidence`.** `category` is the finding's kind — `http-error`, `console-error`, `dead-end`, `data-inconsistency`, `ux-confusing`, `ux-polish`, `visual`, `a11y`, `missing-testid`, `security`, `page-error`, `other` — and is what groups the report.
+- **`scout_finding` takes `severity`, `category`, `title`, `detail` and `evidence`.** `category` is the finding's kind — `console-error`, `page-error`, `http-error`, `network`, `dead-end`, `ux-confusing`, `ux-polish`, `visual`, `a11y`, `permission-leak`, `data-inconsistency`, `stale-state`, `data-loss`, `performance`, `security`, `missing-testid`, `other` — and is what groups the report.
 - **Always pass `evidence`** to `scout_finding` — a canonical machine signature like `GET /api/reports/dashboard 403` or `widget dashboard-summary-widget shows 0`. It's what deduplicates the same bug across runs when titles get rephrased.
 - File judgment findings too: confusing flows, no-feedback actions, state lost on refresh, permission leaks (low-privilege role reaching admin surface), `missing-testid` (low), unnamed interactables (a11y, low).
 - Respect refusals — never retry or route around a policy refusal; note it and move on.