scenescout 3.4.0 → 3.6.0

package/dist/engine/pace.js

@@ -4,7 +4,7 @@
  * counting them inflates the action count and drags the median gap toward
  * zero. One real run logged 325 entries of which 107 were stated tasks.
  */
-const MARKER_ACTIONS = new Set(["task", "attach", "created-resource", "journey:start", "journey:end", "record:full", "record:failed"]);
+const MARKER_ACTIONS = new Set(["task", "attach", "close", "lane-report", "created-resource", "journey:start", "journey:end", "record:full", "record:failed"]);
 /** Whether a log entry represents work the browser actually did. */
 export function isActing(action) {
     return !MARKER_ACTIONS.has(action);
@@ -27,23 +27,41 @@ function median(sorted) {
 export function measurePace(log, nowMs, attached = []) {
     const stillOpen = new Set(attached);
     const bySession = new Map();
+    const lifecycle = new Map();
     for (const entry of log) {
-        if (!isActing(entry.action))
-            continue;
         const name = entry.session ?? "default";
-        const list = bySession.get(name);
+        const into = isActing(entry.action)
+            ? bySession
+            : entry.action === "attach" || entry.action === "close" || entry.action === "lane-report"
+                ? lifecycle
+                : null;
+        if (!into)
+            continue;
+        const list = into.get(name);
         if (list)
             list.push(entry);
         else
-            bySession.set(name, [entry]);
+            into.set(name, [entry]);
     }
+    // A session that attached and never acted still held a browser.
+    for (const name of lifecycle.keys())
+        if (!bySession.has(name))
+            bySession.set(name, []);
     const sessions = [];
     let first = Number.POSITIVE_INFINITY;
     let last = 0;
     for (const [session, entries] of bySession) {
-        const times = entries.map((e) => Date.parse(e.at)).filter((t) => Number.isFinite(t));
-        if (times.length === 0)
+        const times = entries
+            .map((e) => Date.parse(e.at))
+            .filter((t) => Number.isFinite(t))
+            .sort((a, b) => a - b);
+        const edge = edges(lifecycle.get(session) ?? [], times, nowMs, stillOpen.has(session));
+        if (times.length === 0) {
+            if (edge.leadInMs > 0) {
+                sessions.push({ session, actions: 0, spanMs: 0, medianGapMs: 0, maxGapMs: 0, idleShare: 0, quietMs: 0, framed: 0, ...edge });
+            }
             continue;
+        }
         times.sort((a, b) => a - b);
         first = Math.min(first, times[0]);
         last = Math.max(last, times[times.length - 1]);
@@ -61,10 +79,20 @@ export function measurePace(log, nowMs, attached = []) {
             idleShare: spanMs > 0 ? idleMs / spanMs : 0,
             quietMs: Math.max(0, nowMs - times[times.length - 1]),
             framed: entries.filter((e) => e.frame).length,
+            ...edge,
         });
     }
     sessions.sort((a, b) => b.actions - a.actions);
+    const folds = sessions.filter((s) => s.afterFoldMs !== null);
+    const waiting = {
+        workingMs: sessions.reduce((sum, s) => sum + s.spanMs, 0),
+        workingIdleMs: sessions.reduce((sum, s) => sum + s.idleShare * s.spanMs, 0),
+        leadInMs: sessions.reduce((sum, s) => sum + s.leadInMs, 0),
+        afterFinishMs: sessions.reduce((sum, s) => sum + s.afterFinishMs, 0),
+        afterFoldMs: folds.length > 0 ? folds.reduce((sum, s) => sum + (s.afterFoldMs ?? 0), 0) : null,
+    };
     return {
+        waiting,
         sessions,
         spanMs: sessions.length > 0 ? last - first : 0,
         actions: sessions.reduce((sum, x) => sum + x.actions, 0),
@@ -75,6 +103,46 @@ export function measurePace(log, nowMs, attached = []) {
         quiet: sessions.filter((s) => s.quietMs > STALE_SESSION_MS && stillOpen.has(s.session)).map((s) => s.session),
     };
 }
+/**
+ * Time at the edges of each attach: attach to first action (lead-in), and last
+ * action to close (after finishing). An attach with no close after it ends at
+ * the next attach, or at now while the session is still open. A log written
+ * before close was recorded has no close marker; its closed sessions count no
+ * trailing time, because when they closed is unknown. A fold marker after the
+ * last action splits the trailing time at the moment the browser stopped being
+ * needed.
+ */
+function edges(markers, actionTimes, nowMs, stillOpen) {
+    const events = markers
+        .map((m) => ({ kind: m.action, at: Date.parse(m.at) }))
+        .filter((e) => Number.isFinite(e.at))
+        .sort((a, b) => a.at - b.at);
+    let leadInMs = 0;
+    let afterFinishMs = 0;
+    let afterFoldMs = null;
+    for (let i = 0; i < events.length; i += 1) {
+        if (events[i].kind !== "attach")
+            continue;
+        const start = events[i].at;
+        const next = events.slice(i + 1).find((e) => e.kind === "attach" || e.kind === "close");
+        const end = next ? next.at : stillOpen ? nowMs : null;
+        const inside = actionTimes.filter((t) => t >= start && (end === null || t <= end));
+        if (inside.length === 0) {
+            if (end !== null)
+                leadInMs += end - start;
+            continue;
+        }
+        leadInMs += inside[0] - start;
+        if (end === null)
+            continue;
+        const lastAction = inside[inside.length - 1];
+        afterFinishMs += end - lastAction;
+        const fold = events.filter((e) => e.kind === "lane-report" && e.at >= lastAction && e.at <= end).at(-1);
+        if (fold)
+            afterFoldMs = (afterFoldMs ?? 0) + (end - fold.at);
+    }
+    return { leadInMs: Math.max(0, leadInMs), afterFinishMs: Math.max(0, afterFinishMs), afterFoldMs };
+}
 /** Milliseconds as a person says them: 45s, 4m12s, 1h03m. */
 export function sayDuration(ms) {
     const total = Math.max(0, Math.round(ms / 1000));
@@ -93,16 +161,28 @@ export function sayDuration(ms) {
 export function formatPace(pace) {
     if (pace.sessions.length === 0)
         return [];
+    const w = pace.waiting;
+    const pct = (part, whole) => (whole > 0 ? `${Math.round((part / whole) * 100)}%` : "0%");
     const lines = [
         `## How the run was paced`,
         ``,
-        `${pace.actions} action(s) over ${sayDuration(pace.spanMs)}. Stated tasks and attaches are not counted: they take no time. Idle share is time the browser stood still waiting for the agent, not time the engine spent working.`,
+        `${pace.actions} action(s) over ${sayDuration(pace.spanMs)}. Stated tasks and attaches are not counted: they take no time.`,
+        ``,
+        `**While working** — first action to last, ${sayDuration(w.workingMs)} across sessions — ${pct(w.workingIdleMs, w.workingMs)} was spent in gaps over ${sayDuration(IDLE_GAP_MS)}, the agent thinking at length. That is how closely the sessions kept working.`,
+        ``,
+        `**After finishing**, sessions held their browsers for a further ${sayDuration(w.afterFinishMs)}` +
+            (w.afterFoldMs !== null ? `, ${sayDuration(w.afterFoldMs)} of it after their report was already folded` : ``) +
+            (w.afterFoldMs !== null
+                ? `. That is time waiting to be collected and closed: it grows with the number of lanes and with the slowest one, not with how well any lane worked. Closing each lane as soon as its report is folded removes it.`
+                : `: time from the last action to close.`) +
+            ` (Before the first action: ${sayDuration(w.leadInMs)}.)`,
         ``,
-        `| Session | Actions | Span | Median gap | Longest gap | Idle | Frames |`,
-        `|---|---:|---:|---:|---:|---:|---:|`,
+        `| Session | Actions | Working | Median gap | Longest gap | Idle while working | After finishing | Frames |`,
+        `|---|---:|---:|---:|---:|---:|---:|---:|`,
     ];
     for (const s of pace.sessions) {
-        lines.push(`| ${s.session} | ${s.actions} | ${sayDuration(s.spanMs)} | ${sayDuration(s.medianGapMs)} | ${sayDuration(s.maxGapMs)} | ${Math.round(s.idleShare * 100)}% | ${s.framed} |`);
+        const after = sayDuration(s.afterFinishMs) + (s.afterFoldMs !== null ? ` (${sayDuration(s.afterFoldMs)} after fold)` : ``);
+        lines.push(`| ${s.session} | ${s.actions} | ${sayDuration(s.spanMs)} | ${sayDuration(s.medianGapMs)} | ${sayDuration(s.maxGapMs)} | ${Math.round(s.idleShare * 100)}% | ${after} | ${s.framed} |`);
     }
     lines.push(``);
     if (pace.quiet.length > 0) {

package/dist/engine/policy.js

@@ -185,3 +185,43 @@ export function allowsWrite(mode, method, destructiveWire, owned) {
     // PUT/PATCH/DELETE: only in safe-write, only on this run's own records.
     return mode === "safe-write" && owned;
 }
+/**
+ * Which blocked requests the write policy answers rather than drops.
+ *
+ * A dropped request tells the page nothing it would ever meet in production:
+ * `fetch` rejects with a network error, and the code that handles a refusal —
+ * the branch that should say "couldn't save" — never runs. Answering a script's
+ * request with a refusal keeps the server untouched and exercises that branch,
+ * so a page that reports a refused save as saved is caught. A navigation (a
+ * native form post) is still dropped: answering it would replace the page the
+ * user was on with the stand-in body.
+ */
+export function answersWithRefusal(resourceType) {
+    return resourceType === "fetch" || resourceType === "xhr";
+}
+/** Header on every refusal the policy writes, so the stand-in can be told from the server's own answer. */
+export const POLICY_REFUSAL_HEADER = "x-scenescout-policy";
+/**
+ * The response the write policy sends in the server's place. 403, because the
+ * request is forbidden, not failed: a 5xx invites retries, and a 401 is what
+ * many apps read as "signed out". The CORS headers let a cross-origin API
+ * call read the refusal instead of failing as a network error, which would
+ * drop it all over again. `origin` is the request's own Origin header, echoed
+ * only when there is one.
+ */
+export function policyRefusal(mode, method, pathname, origin) {
+    const headers = { "content-type": "application/json", [POLICY_REFUSAL_HEADER]: `refused; mode=${mode}` };
+    if (origin) {
+        headers["access-control-allow-origin"] = origin;
+        headers["access-control-allow-credentials"] = "true";
+        headers["access-control-expose-headers"] = POLICY_REFUSAL_HEADER;
+    }
+    return {
+        status: 403,
+        headers,
+        body: JSON.stringify({
+            error: "Forbidden",
+            message: `${method} ${pathname} was refused by the tester's ${mode} write policy. The server never received it.`,
+        }),
+    };
+}

package/dist/engine/report.js

@@ -415,7 +415,7 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
         lines.push(`| Route coverage | ${extras.routesVisited}/${extras.routesTotal} |`);
     lines.push(`| States explored | ${cov.states} |`);
     if (extras)
-        lines.push(`| Design audits this session | ${extras.designAudits} |`);
+        lines.push(`| Design audits this run (all sessions) | ${extras.designAudits} |`);
     lines.push(`| Oracle violations this session | ${oracleLog.length} |`);
     if (extras?.policyAttributed) {
         lines.push(`| Errors caused by the tester's own write-policy blocks (not counted above) | ${extras.policyAttributed} |`);

package/dist/engine/request.js

@@ -22,6 +22,7 @@
  * Everything in this file is pure so it can be table-tested; the one
  * `page.evaluate` lives in browser.ts.
  */
+import { POLICY_REFUSAL_HEADER } from "./policy.js";
 /** Methods a session may replay. Anything else is refused before it reaches the page. */
 export const REPLAYABLE_METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
 /** Most of a response body that reaches the agent. A JSON list can be megabytes; the signature is in the first lines. */
@@ -114,6 +115,7 @@ export function toReplayResult(raw) {
         truncated: raw.full > BODY_MAX,
         ms: raw.ms,
         url: raw.url,
+        refusedByPolicy: raw.headers[POLICY_REFUSAL_HEADER] ?? null,
     };
 }
 /** The signature a finding carries for this call: the line that dedups the same refusal across runs. */
@@ -128,8 +130,19 @@ export function replaySignature(method, url, status) {
     }
     return `${method} ${path} ${status}`;
 }
-/** What the agent reads back. Leads with the signature, because that is what a finding quotes. */
+/**
+ * What the agent reads back. Leads with the signature, because that is what a
+ * finding quotes — except when the write policy answered, where there is no
+ * server signature to quote. Printing the stand-in's 403 as one would read as
+ * the server enforcing a permission it was never asked about.
+ */
 export function formatReplay(method, result) {
+    if (result.refusedByPolicy) {
+        const path = replaySignature(method, result.url, result.status).replace(/ \d+$/, "");
+        return (`REFUSED by the write policy (${result.refusedByPolicy}): ${path} never reached the server.\n` +
+            `This is the engine's safety net, not the server's answer, so it says nothing about whether the server enforces this rule. ` +
+            `To test that, re-attach in a mode that allows the request on a record this session owns, or leave it out of the finding.`);
+    }
     const lines = [replaySignature(method, result.url, result.status) + (result.statusText ? ` ${result.statusText}` : ""), `took ${result.ms} ms`];
     const headers = Object.entries(result.headers);
     if (headers.length > 0)

package/dist/mcp-server.js

@@ -36,6 +36,7 @@ import { BrowserEngine } from "./engine/browser.js";
 import { reapOrphanBrowsers } from "./engine/reaper.js";
 import { FINDING_CATEGORIES, MemoryStore, redactSecrets } from "./engine/memory.js";
 import { LANE_NAME_MAX, laneReportInstruction, parseLaneReport, summarizeLaneReport } from "./engine/lane.js";
+import { MAX_UNFILED_NAMED, unfiledDefects } from "./engine/calibration.js";
 import { SessionQueue, withWatchdog } from "./engine/dispatch.js";
 import { FIXTURE_KINDS } from "./engine/fixtures.js";
 import { feedForSession, LIVE_ENV, writeStatusFile, LIVE_TOKEN_FILE, liveEngines, liveTokenFileName, pidAlive, statusFileName, LiveServer, StatusBoard, } from "./engine/live.js";
@@ -238,7 +239,7 @@ function reportExtras(eng) {
     return {
         routesVisited: all.length - unvisited.length,
         routesTotal: all.length,
-        designAudits: eng.designAuditCount,
+        designAudits: eng.memory?.auditsThisRun ?? eng.designAuditCount,
         createdResources: eng.createdResources,
         unvisitedRoutes: unvisited,
         mode: eng.mode,
@@ -545,6 +546,9 @@ server.registerTool("scout_lane_report", {
         // already closed makes that the ordinary case, not an edge one.
         const owner = engines.get(lane)?.memory;
         const at = new Date().toISOString();
+        // Marks the moment the lane's browser stopped being needed, so the pace
+        // section can tell a lane still reporting from one waiting to be closed.
+        owner?.logAction({ action: "lane-report", url: engines.get(lane)?.currentUrl ?? "", session: lane });
         const kept = owner
             ? owner.addLaneDecisions(lane, parsed.report.decisions.map((d) => ({ ...d, lane, at })))
             : 0;
@@ -555,8 +559,23 @@ server.registerTool("scout_lane_report", {
         // makes a later calibration section look wrong rather than absent.
         const note = kept > 0
             ? ` (${kept} decision(s) kept for calibration)`
-            : ` (nothing kept for calibration — session ${JSON.stringify(lane)} is not attached here, so there is no project memory to write to. Fold a lane report before closing that lane's session.)`;
-        return { content: [{ type: "text", text: `Lane report accepted — ${summarizeLaneReport(parsed.report)}${note}` }] };
+            : ` (nothing kept for calibration, and no check that its defects were filed — session ${JSON.stringify(lane)} is not attached here, so there is no project memory to write to or read. Fold a lane report before closing that lane's session.)`;
+        // Follow-through: a defect judged and never filed never reaches the
+        // report. Checked against every finding on the lane's project, so one
+        // the planner or another lane filed counts. Only that project's: the
+        // same reason decisions are kept only there.
+        const unfiled = owner ? unfiledDefects(parsed.report.decisions, owner.findings) : [];
+        const followUp = unfiled.length > 0
+            ? `\n⚠ ${unfiled.length} judged defect(s) have no finding with matching evidence yet:\n` +
+                unfiled
+                    .slice(0, MAX_UNFILED_NAMED)
+                    .map((u) => `  · ${u}`)
+                    .join("\n") +
+                (unfiled.length > MAX_UNFILED_NAMED ? `\n  … +${unfiled.length - MAX_UNFILED_NAMED} more` : "") +
+                `\nFile each with scout_finding (the same evidence), or confirm which finding already covers it, before closing the lane's session. A judged defect that is never filed is not in the report.`
+            : "";
+        const around = parsed.aroundIgnored ? `\n(The text around the report's JSON block was discarded unread.)` : "";
+        return { content: [{ type: "text", text: `Lane report accepted — ${summarizeLaneReport(parsed.report)}${note}${around}${followUp}` }] };
     }
     catch (err) {
         return errorText(err);
@@ -680,6 +699,12 @@ server.registerTool("scout_attach", {
         catch {
             /* conflict detection is best-effort */
         }
+        // Moving this session to another project leaves its old one; if it was
+        // the last session there, that run is over. Re-attaching to the SAME
+        // project is the same run, and keeps what the run has learned.
+        const previous = eng.memory;
+        if (previous && previous !== store && ![...engines.values()].some((e) => e !== eng && e.memory === previous))
+            previous.endRun();
         const viewport = viewportWidth && viewportHeight ? { width: viewportWidth, height: viewportHeight } : undefined;
         const out = await eng.attach({
             url,
@@ -1185,8 +1210,11 @@ server.registerTool("scout_report", {
                 (unvisited.length > 30 ? `\n  … +${unvisited.length - 30} more` : "") +
                 `\n→ Run scout_crawl (no args) to cover them in one call.`);
         }
-        if (eng.designAuditCount === 0) {
-            gates.push(`No scout_design_audit was run this session — run it on at least one representative page (visual/a11y coverage is part of every level).`);
+        // Counted across every session on this project, not just the one
+        // asking: in a parallel run the lanes audit and the planner reports.
+        const auditsThisRun = eng.memory.auditsThisRun;
+        if (auditsThisRun === 0) {
+            gates.push(`No scout_design_audit was run in this run, by any session — run it on at least one representative page (visual/a11y coverage is part of every level).`);
         }
         const lvl = level ?? "medium";
         const auditedRoutes = Object.values(eng.memory.routeFacts).filter((f) => f.audited).length;
@@ -1201,7 +1229,7 @@ server.registerTool("scout_report", {
         const gapList = computeGaps(eng.memory, {
             routesVisited: all.length - unvisited.length,
             routesTotal: all.length,
-            designAudits: eng.designAuditCount,
+            designAudits: auditsThisRun,
             unvisitedRoutes: unvisited,
             mode: eng.mode,
         });
@@ -1221,11 +1249,13 @@ server.registerTool("scout_report", {
             history,
             routesVisited: all.length - unvisited.length,
             routesTotal: all.length,
-            designAudits: eng.designAuditCount,
+            designAudits: auditsThisRun,
             createdResources: eng.createdResources,
             unvisitedRoutes: unvisited,
             mode: eng.mode,
             policyAttributed: eng.oracleLog.policyAttributed,
+            // Which sessions are still open decides whether a quiet one is holding a browser, and how long its trailing idle runs.
+            attachedSessions: [...engines.keys()],
         });
         void p;
         return text(summary, session);
@@ -1312,8 +1342,11 @@ server.registerTool("scout_close", {
                 keepReport(e);
             for (const name of engines.keys())
                 live?.dropSession(name);
+            const stores = new Set([...engines.values()].map((e) => e.memory).filter((m) => m !== null && m !== undefined));
             await Promise.allSettled([...engines.values()].map((e) => e.close()));
             engines.clear();
+            for (const store of stores)
+                store.endRun();
             sessionQueue.clear();
             board.clear();
             lastWriter = null;
@@ -1330,6 +1363,9 @@ server.registerTool("scout_close", {
         await eng.close();
         const saveError = eng.memory?.lastSaveError;
         engines.delete(name);
+        // The last session on this project ends its run.
+        if (eng.memory && ![...engines.values()].some((e) => e.memory === eng.memory))
+            eng.memory.endRun();
         sessionQueue.forget(name);
         board.remove(name);
         if (lastWriter?.session === name)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.4.0",
+  "version": "3.6.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 pace-test && npm run request-test && npm run settle-test && npm run claims-test && npm run verify-test && npm run brief-test && npm run lane-test && npm run calibration-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 pace-test && npm run request-test && npm run settle-test && npm run claims-test && npm run verify-test && npm run brief-test && npm run lane-test && npm run calibration-test && npm run bench-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",
@@ -91,7 +91,9 @@
     "claims-test": "tsx --test scripts/claims-test.ts",
     "verify-test": "tsx --test scripts/verify-test.ts",
     "brief-test": "tsx --test scripts/brief-test.ts",
-    "calibration-test": "tsx --test scripts/calibration-test.ts"
+    "calibration-test": "tsx --test scripts/calibration-test.ts",
+    "bench": "tsx scripts/bench.ts",
+    "bench-test": "tsx --test scripts/bench-test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",

package/skills/scenescout/SKILL.md

@@ -25,7 +25,7 @@ You are the brain of an exploratory UI tester. The SceneScout MCP server gives y
    - `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.
    - `destructive` (`--allow-destructive` only): everything allowed. Requires the user to explicitly confirm the environment is disposable/seeded. Never decide this yourself.
-   A `🛡 WRITE-POLICY blocked` notice in a tool result is the engine's safety net, NOT an app bug — never file a finding for the error UI it causes; note it and move on (or suggest the user re-run with a laxer mode if that flow matters).
+   A `🛡 WRITE-POLICY blocked` notice in a tool result is the engine's safety net, NOT an app bug — never file a finding for the error UI it causes; note it and move on (or suggest the user re-run with a laxer mode if that flow matters). The page's own requests are answered with a 403 in the server's place, so the page's handling of a refusal is real: an error message after a block is correct behaviour, but a page that claims the change was saved or deleted is lying to its user — the engine reports that as `false_success`, and it IS a finding.
    **`⚠ AUTH FAILED` on attach means the storage state is stale** — its token has expired and the browser is sitting on a login page. Stop and ask the user to regenerate it (usually their Playwright auth-setup project); do not explore, and do not file findings from a logged-out session. The message quotes whatever an earlier run wrote down about regenerating it, so relay that first rather than asking from scratch — and the moment the user tells you what actually worked, write it down with `scout_note {section:'setup', note}` (the exact command, what has to be on PATH, how long a token lasts). A login state expires on a timer nobody remembers, and this is the single learning a run most reliably pays for and then forgets. Mid-run, `⚠ SESSION AUTH LOST` means the same thing happened after N navigations: everything since is meaningless, so re-attach rather than pressing on. Routes bounced this way are recorded as NOT covered, so the gap ledger will still show them.
 6. **`scout_note {action:'read'}` immediately after attaching.** ASSUMPTIONS.md is the run-over-run written memory: what the app is, who each role is FOR, constraints discovered the hard way ("an order can only ship once approved"). Starting without reading it means re-learning what a previous run already paid to find out. Throughout the run, `scout_note {action:'add'}` every DURABLE learning the moment you confirm it — app model, role personas, conventions, constraints, risks, glossary. Not session facts (ids, counts); knowledge a future run should start with.
 
@@ -72,9 +72,9 @@ 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 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.
-- **Let the engine divide the app: `scout_lane_brief {lanes, goal}`.** Call it after the first crawl, when route knowledge is complete. It splits the known routes into whole modules — everything under `/orders` goes to one lane, so that lane carries state between its own steps instead of re-learning the app on every route — deals the modules out so the lanes come out within a route or two of each other, and returns each lane's session name, the `objective` to attach it with, and the routes it owns. Pass `routes` to split a subset instead. Hand each brief to its agent verbatim. Dividing by hand fails in two ways that a finished run cannot tell apart from success: two lanes audit the same register while a third module is never opened, and route coverage reads complete either way; and lanes launch without an objective, so the person watching sees browsers clicking through their app with nothing to say why.
-- **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, and keeps each decision so the confidence the lane stated can be checked against what the run went on to file — the report's calibration section is built from that, and it only appears once enough decisions exist to mean something. **So the confidence is worth stating honestly**: a lane that writes 0.95 on everything makes the section say so. 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.
+- **Several agents in parallel** (subagents or a workflow, each driving its own session): each agent attaches its session when it STARTS, and the PLANNER closes it by name once it has folded that lane's report. A lane must NOT close its own session before reporting: `scout_lane_report` keeps its decisions against that session's project memory, so a lane that closes first hands back decisions with nowhere to write — the tool says so rather than accepting silently, and the run's calibration section ends up with nothing to measure. Fold, then close. 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.
+- **Let the engine divide the app: `scout_lane_brief {lanes, goal}`.** Call it after the first crawl, when route knowledge is complete. It splits the known routes into whole modules — everything under `/orders` goes to one lane, so that lane carries state between its own steps instead of re-learning the app on every route — deals the modules out so the lanes come out within a route or two of each other, and returns each lane's session name, the `objective` to attach it with, the routes it owns, the route it lands on (its own first route: lanes that all attached on the home page all met its defects first, and several filed the same one), and the rules each lane must follow — file each defect as it is judged, check a list's request status before calling it empty or stuck, submit one markup value on a create form and open where it is listed, probe a withheld control's endpoint, check coverage, and leave the session open for you to fold. Pass `routes` to split a subset instead. Hand each brief to its agent verbatim. Dividing by hand fails in two ways that a finished run cannot tell apart from success: two lanes audit the same register while a third module is never opened, and route coverage reads complete either way; and lanes launch without an objective, so the person watching sees browsers clicking through their app with nothing to say why.
+- **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, and keeps each decision so the confidence the lane stated can be checked against what the run went on to file — the report's calibration section is built from that, and it only appears once enough decisions exist to mean something. **So the confidence is worth stating honestly**: a lane that writes 0.95 on everything makes the section say so. The fold also lists every defect the lane judged that no finding on the project matches yet: have the lane file each with the same `evidence` (a finding filed without evidence cannot be matched), or name the finding that covers it, before you close its session, because a defect that is only in a lane report never reaches the run's report. Prose around ONE fenced JSON block is discarded unread and the report accepted; anything less clear-cut is 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)
 
@@ -89,10 +89,10 @@ The engine is self-healing (orphaned browsers reaped, wedged calls time out with
 
 ## Judgment (what the engine can't do)
 
-- **A hidden or disabled control proves nothing: `scout_request` is how a refusal becomes evidence.** Any finding that a role CANNOT do something must show the server refusing it, not just the UI withholding the button — a control hidden client-side is a decision the browser made, and the endpoint behind it may answer 200 to anyone who asks. `scout_request {session, method, path}` calls the app's own API as that session, with the UI bypassed: it runs inside the page, so it carries the session's cookies, replays the Authorization header the app itself last sent, and meets the same write policy a click does (in safe-write a mutation on a record the session did not create is refused here too, which is the engine's safety net and never a finding). It returns the signature to quote (`GET /api/admin/users 403`), the timing, the headers that decide whether two responses are genuinely identical, and the body. Use it for every permission boundary, for comparing one route across roles, and for confirming a 402/403 the UI turned into a friendly empty state. Paths are fenced to the attached origin. Unlike a shell call, every request is recorded in the run's trail and shows up in the report.
+- **A hidden or disabled control proves nothing: `scout_request` is how a refusal becomes evidence.** Any finding that a role CANNOT do something must show the server refusing it, not just the UI withholding the button — a control hidden client-side is a decision the browser made, and the endpoint behind it may answer 200 to anyone who asks. `scout_request {session, method, path}` calls the app's own API as that session, with the UI bypassed: it runs inside the page, so it carries the session's cookies, replays the Authorization header the app itself last sent, and meets the same write policy a click does (in safe-write a mutation on a record the session did not create is refused here too, and the result says `REFUSED by the write policy` instead of a status: the server was never asked, so it is not evidence either way and never a finding). It returns the signature to quote (`GET /api/admin/users 403`), the timing, the headers that decide whether two responses are genuinely identical, and the body. Use it for every permission boundary, for comparing one route across roles, and for confirming a 402/403 the UI turned into a friendly empty state. Paths are fenced to the attached origin. Unlike a shell call, every request is recorded in the run's trail and shows up in the report.
 - **Ground absence-claims in the source before filing.** Black-box behaviour tells you what happened, never *why*. Any finding asserting a control is MISSING ("no permission check", "no validation", "no segregation of duties", "not implemented") must be checked against the codebase first — you have Read/Grep/Bash, use them. Three outcomes, all valuable: (1) genuinely absent → file it with the file:line you checked, which makes it actionable instead of speculative; (2) implemented but not reached on your path → you found a *routing/config* bug, a different and often better finding; (3) implemented elsewhere in the same codebase but not here → **the strongest kind of finding**, an inconsistency against the team's own established pattern, with the reference implementation attached as the fix. A grep costs seconds and is the difference between "I think this is wrong" and "here is the line". Behaviour-only findings (a crash, a 500, a dead end) need no such check — the evidence is self-contained.
 - Oracle violations are *evidence* — reproduce/contextualize, then `scout_finding`. **Severity anchors:** crash, data loss, security/permission breach, or a flow the user cannot complete or escape (infinite spinner, no-way-out page, broken primary journey) = **high** — a dead end is high even without a crash. Broken but recoverable = medium. Polish/friction = low.
-- **A `refused_empty` or `false_success` violation is the highest-value thing the engine hands you — file it, always.** Both mean the page CONTRADICTED the server. `refused_empty`: a list request was refused (401/403/5xx) and the page showed its empty state with no error, so the user is told they have nothing when the truth is that nothing could be loaded — this is how a permission regression ships without anyone noticing, and it is a `data-inconsistency` or `security` finding at **high**, not a cosmetic one. `false_success`: a save was refused and the page said it worked, so the user walks away believing their change was kept — **high**, `data-inconsistency`. The engine only raises either when a request genuinely failed AND the page admitted nothing, so do not re-litigate whether the refusal happened; reproduce it, name the endpoint and the message the user saw, and read the handler in the source to say which branch swallowed the response. A page that shows an error is correct behaviour and never raises these — quote that contrast in the finding, since it is usually the fix.
+- **A `refused_empty` or `false_success` violation is the highest-value thing the engine hands you — file it, always.** Both mean the page CONTRADICTED the server. `refused_empty`: a list request was refused (401/403/5xx) and the page showed its empty state with no error, so the user is told they have nothing when the truth is that nothing could be loaded — this is how a permission regression ships without anyone noticing, and it is a `data-inconsistency` or `security` finding at **high**, not a cosmetic one. `false_success`: a save was refused and the page said it worked, so the user walks away believing their change was kept — **high**, `data-inconsistency`. The engine only raises either when a request genuinely failed AND the page admitted nothing, so do not re-litigate whether the refusal happened; reproduce it, name the endpoint and the message the user saw, and read the handler in the source to say which branch swallowed the response. A page that shows an error is correct behaviour and never raises these — quote that contrast in the finding, since it is usually the fix. When the violation says the refusal was the write policy's **stand-in**, the server was never asked: the finding is about the page's handling of a refusal (`data-inconsistency`), not about the server's permissions, so never file it as a permission regression or `security`.
 - **Provenance for deep-link findings:** if you reached a state by direct URL (crawl or scout_navigate) and it looks broken (no app shell, dead end), check whether real users can reach it through the UI before filing — many apps render tab content at internal URLs that users only ever reach via `?tab=` links. Always state in the finding how the state was reached.
 - 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.