scenescout 3.1.1 → 3.3.0

package/dist/engine/verify.js

@@ -0,0 +1,142 @@
+/**
+ * Re-testing findings a previous run left open.
+ *
+ * The report has always carried two kinds of finding and been honest that they
+ * are not the same thing: what this run saw, and what some earlier run saw.
+ * The second kind is labelled historical and unverified, which is accurate and
+ * almost useless — a reader cannot tell a bug fixed three weeks ago from one
+ * that is still costing users money today, and neither can the next run.
+ *
+ * Closing that gap by hand is possible and nobody does it. It means opening
+ * the report, copying each finding's route and evidence, re-walking them one
+ * at a time, and calling `scout_resolve` on the ones that are gone — per
+ * finding, for as many as the history holds. One project's history held over
+ * three hundred.
+ *
+ * So the campaign is a tool. Asked for a worklist, it hands back the open
+ * findings in the order a run should re-test them: by severity, grouped so a
+ * route is walked once rather than once per finding, each with the evidence
+ * that identifies it and the steps that produced it. Asked to record a
+ * verdict, it stamps what was seen and when, so the next report can say
+ * "confirmed still present" with a date instead of "unverified".
+ *
+ * Pure, so the ordering and the wording can be table-tested.
+ */
+import { normalizePath } from "./fingerprint.js";
+/** What a re-test found. */
+export const VERDICTS = ["gone", "present", "changed"];
+export const VERDICT_MEANING = {
+    gone: "re-tested and the evidence no longer reproduces — resolved",
+    present: "re-tested and still reproduces exactly as filed",
+    changed: "re-tested and something is different — still broken, but not as described",
+};
+/** Most findings a single campaign hands over at once. A worklist longer than this is a plan nobody follows. */
+export const MAX_WORKLIST = 25;
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
+function item(f) {
+    return {
+        id: f.id,
+        severity: f.severity,
+        category: f.category,
+        title: f.title,
+        route: normalizePath(f.url),
+        url: f.url,
+        evidence: f.evidence ?? "",
+        repro: f.repro ?? [],
+        foundAt: f.foundAt,
+        runs: f.runs ?? 1,
+        ...(f.verdict ? { lastVerdict: f.verdict } : {}),
+        ...(f.verifiedAt ? { lastVerifiedAt: f.verifiedAt } : {}),
+    };
+}
+/**
+ * The findings to re-test, in the order to do it.
+ *
+ * Severity decides what matters; route groups what is cheap, because walking
+ * one route and checking four findings on it costs a fraction of walking four
+ * routes. Within a route, a finding never verified comes before one verified
+ * before — re-checking the same finding twice while another has never been
+ * looked at is the failure mode this ordering exists to prevent.
+ */
+export function verifyWorklist(findings, ids) {
+    const wanted = ids && ids.length > 0 ? new Set(ids) : null;
+    const open = findings.filter((f) => (f.status ?? "open") !== "resolved").filter((f) => (wanted ? wanted.has(f.id) : true));
+    // The severity of a route is its worst finding: a route carrying a high is
+    // walked before one carrying three mediums.
+    const worst = new Map();
+    for (const f of open) {
+        const route = normalizePath(f.url);
+        const rank = SEVERITY_ORDER[f.severity] ?? 3;
+        worst.set(route, Math.min(worst.get(route) ?? 9, rank));
+    }
+    return open
+        .map(item)
+        .sort((a, b) => (worst.get(a.route) ?? 9) - (worst.get(b.route) ?? 9) ||
+        a.route.localeCompare(b.route) ||
+        (SEVERITY_ORDER[a.severity] ?? 3) - (SEVERITY_ORDER[b.severity] ?? 3) ||
+        Number(Boolean(a.lastVerifiedAt)) - Number(Boolean(b.lastVerifiedAt)) ||
+        (a.lastVerifiedAt ?? "").localeCompare(b.lastVerifiedAt ?? "") ||
+        a.id.localeCompare(b.id))
+        .slice(0, MAX_WORKLIST);
+}
+/** Ids the caller asked for that no open finding matches — a silently short worklist is worse than a named miss. */
+export function unknownIds(findings, ids) {
+    const open = new Set(findings.filter((f) => (f.status ?? "open") !== "resolved").map((f) => f.id));
+    return ids.filter((id) => !open.has(id));
+}
+/** The campaign brief the agent works down. */
+export function formatWorklist(items, missing = []) {
+    if (items.length === 0) {
+        return missing.length > 0
+            ? `Nothing to verify. No OPEN finding matches: ${missing.join(", ")}. They may already be resolved, or belong to another project's memory.`
+            : "Nothing to verify — no open findings in this project's memory.";
+    }
+    const lines = [
+        `VERIFY CAMPAIGN — ${items.length} open finding(s) to re-test, worst route first.`,
+        `Re-test each one, then record what you saw: scout_verify { id, verdict: "gone" | "present" | "changed", note }.`,
+        `"gone" resolves it. "present" stamps it confirmed, so the report stops calling it unverified. "changed" keeps it open and says what differs.`,
+        ``,
+    ];
+    let route = "";
+    for (const it of items) {
+        if (it.route !== route) {
+            route = it.route;
+            lines.push(`── ${route} ──`);
+        }
+        const seen = it.lastVerifiedAt ? ` · last re-tested ${it.lastVerifiedAt.slice(0, 10)} (${it.lastVerdict})` : " · never re-tested";
+        lines.push(`[${it.severity}] ${it.id} ${it.title}`);
+        lines.push(`  ${it.category} · found ${it.foundAt.slice(0, 10)} · ${it.runs} run(s)${seen}`);
+        if (it.evidence)
+            lines.push(`  evidence: ${it.evidence}`);
+        if (it.repro.length > 0)
+            lines.push(`  repro: ${it.repro.slice(0, 6).join(" → ")}`);
+        lines.push(`  at: ${it.url}`);
+    }
+    if (missing.length > 0)
+        lines.push(``, `No OPEN finding matches: ${missing.join(", ")}.`);
+    return lines.join("\n");
+}
+/** Whether a verdict resolves the finding it is recorded against. */
+export function resolvesFinding(verdict) {
+    return verdict === "gone";
+}
+/** What the agent reads back after recording one. */
+export function describeVerdict(f, verdict, note) {
+    const tail = note ? `\n  ${note}` : "";
+    if (verdict === "gone")
+        return `Resolved by re-test: [${f.severity}] ${f.title} (${f.id}).${tail}`;
+    if (verdict === "present")
+        return `Confirmed still present: [${f.severity}] ${f.title} (${f.id}). It stays open, and the report now dates the confirmation instead of calling it unverified.${tail}`;
+    return `Still open and changed: [${f.severity}] ${f.title} (${f.id}). Re-file the difference as its own finding if the behaviour is now a different bug.${tail}`;
+}
+/** How a verified finding reads in the report, or nothing when it was never re-tested. */
+export function sayVerification(f) {
+    if (!f.verdict || !f.verifiedAt)
+        return "";
+    const on = f.verifiedAt.slice(0, 10);
+    if (f.verdict === "present")
+        return ` · confirmed still present on ${on}`;
+    if (f.verdict === "changed")
+        return ` · re-tested ${on}, behaviour has changed since it was filed`;
+    return ` · re-tested ${on}`;
+}

package/dist/mcp-server.js

@@ -34,12 +34,16 @@ 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";
+import { feedForSession, LIVE_ENV, writeStatusFile, LIVE_TOKEN_FILE, liveEngines, liveTokenFileName, pidAlive, statusFileName, LiveServer, StatusBoard, } from "./engine/live.js";
+import { formatBriefs, MAX_LANES, planLanes } from "./engine/brief.js";
 import { computeGaps, formatRouteCoverage, generateReport, replayDocument, reportEvidence } from "./engine/report.js";
+import { describeVerdict, formatWorklist, unknownIds, VERDICTS, verifyWorklist } from "./engine/verify.js";
 import { RECORD_MAX_FRAMES, resolveFrame } from "./engine/replay.js";
+import { describePace, normalizePace } from "./engine/settle.js";
 import { needsTask, taskRefusal, TASK_MAX } from "./engine/task.js";
 import { EXPLORE_PROMPT_ARGUMENTS, explorePrompt, loadPlaybook, PLAYBOOK_PROMPT, PLAYBOOK_TOOL, SERVER_INSTRUCTIONS } from "./playbook.js";
 import { formatScan, scanProject } from "./scan.js";
@@ -240,15 +244,20 @@ function reportExtras(eng) {
         mode: eng.mode,
         policyAttributed: eng.oracleLog.policyAttributed,
         version: PKG_VERSION,
+        attachedSessions: [...engines.keys()],
     };
 }
 /** Hand the live view's token to `scenescout watch` through a file only the owner can read. */
 function publishLiveToken(dir) {
     if (!liveAddress || liveDirs.has(dir) || liveTokenWrites.has(dir))
         return;
-    const file = path.join(dir, LIVE_TOKEN_FILE);
+    // Named for this process: two engines on one project would otherwise hand
+    // `watch` one token for two ports, and whichever wrote last would win.
+    const file = path.join(dir, liveTokenFileName(process.pid));
     const write = fs.promises
         .writeFile(file, liveAddress.token, { mode: 0o600 })
+        // The shared name stays too, for a `watch` from before per-pid files.
+        .then(() => fs.promises.writeFile(path.join(dir, LIVE_TOKEN_FILE), liveAddress.token, { mode: 0o600 }))
         // `mode` applies only when the file is created; a leftover one keeps its old bits.
         .then(() => fs.promises.chmod(file, 0o600))
         .then(() => {
@@ -483,6 +492,51 @@ 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.
+// Splitting the app between lanes: the other half of the parallel protocol.
+// scout_lane_report is how a lane hands its answers back; this is what the
+// planner hands it in the first place.
+server.registerTool("scout_lane_brief", {
+    description: "For a run split across parallel agents (lanes). Divides the app's known routes between N lanes and returns each lane's session name, the `objective` to attach it with, and the routes it owns — whole modules per lane, balanced by route count, so no two lanes audit the same area and none is left unopened. Call it after the first crawl, when route knowledge is complete. Touches no browser; pass the briefs to your lane agents, then use scout_lane_report for what they hand back.",
+    inputSchema: {
+        lanes: z.number().int().min(1).max(MAX_LANES).describe(`How many lanes to split across (1–${MAX_LANES})`),
+        goal: z.string().max(200).optional().describe("What the whole run is for; each lane's objective is written against it"),
+        routes: z.array(z.string()).max(500).optional().describe("Routes to split. Omit to split every route this project knows about."),
+        session: sessionParam,
+    },
+}, serializedPerSession("scout_lane_brief", async ({ lanes, goal, routes }, session) => {
+    try {
+        const eng = engineFor(session);
+        const all = routes && routes.length > 0 ? routes : eng.allKnownRoutes();
+        return text(formatBriefs(planLanes(all, lanes, { goal, mode: eng.mode, role: eng.role }), { goal, mode: eng.mode, role: eng.role }), session);
+    }
+    catch (err) {
+        return errorText(err);
+    }
+}));
+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") },
@@ -518,7 +572,18 @@ server.registerTool("scout_attach", {
             .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`."),
+        task: z
+            .string()
+            .max(300)
+            .optional()
+            .describe("What this session is doing right now, shown under its objective from the moment it appears, e.g. Signing in and taking stock. Passed alone it is read as the 2.0 spelling of `objective`. Defaults to a placeholder so a fresh card never reads as idle."),
+        paceMs: z
+            .number()
+            .int()
+            .min(0)
+            .max(60000)
+            .optional()
+            .describe("A floor between actions, in milliseconds, for when a person is watching and needs to keep up — following a flow, taking notes, demonstrating. Default 0: as fast as the page allows, which is what a run wants otherwise. Changeable mid-run with scout_session {paceMs}."),
         record: z
             .boolean()
             .default(false)
@@ -530,7 +595,7 @@ server.registerTool("scout_attach", {
             .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, objective, task, record, session, }) => {
+}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, browser, viewportWidth, viewportHeight, objective, task, record, paceMs, session, }) => {
     try {
         const target = session ?? activeName;
         if (session) {
@@ -599,8 +664,13 @@ server.registerTool("scout_attach", {
             headed,
             browser,
             viewport,
-            // `task` is what this was called in 2.0; it named the session's whole remit, which is the objective.
+            // `task` is what this was called in 2.0, where it named the session's
+            // whole remit. Alone it still means that. Given BESIDE an objective it
+            // means what it means everywhere else — what this session is doing
+            // right now — so the card says something from the moment it appears.
             objective: objective ?? task,
+            paceMs,
+            task: objective ? task : undefined,
             record,
             memoryStore: store,
         });
@@ -618,7 +688,7 @@ server.registerTool("scout_attach", {
         const recordNote = record && eng.memory?.dir
             ? `\n\n📸 RECORDING: a frame of the page after each action, under ${path.join(eng.memory.dir, "recordings", target)}/ (at most ${RECORD_MAX_FRAMES}). scout_report writes them into report.html beside report.md.`
             : "";
-        return text(out + conflictNote + recordNote + (engines.size > 1 ? `\n${sessionLines()}` : "") + liveLine(), target);
+        return text(out + conflictNote + recordNote + describePace(eng.pace) + (engines.size > 1 ? `\n${sessionLines()}` : "") + liveLine(), target);
     }
     catch (err) {
         return errorText(err);
@@ -639,10 +709,32 @@ server.registerTool("scout_session", {
         // costs nothing and removes a guaranteed first-try rejection, since all
         // schemas are additionalProperties:false and reject the near-miss hard.
         session: z.string().max(40).optional().describe("Alias for `name`."),
+        paceMs: z
+            .number()
+            .int()
+            .min(0)
+            .max(60000)
+            .optional()
+            .describe("Change how fast this session acts, mid-run: a floor between actions in milliseconds, for when a person is watching and needs to keep up. 0 restores full speed. With `name`, applies to that session; without, to every live session — which is what 'slow everything down so I can follow' means."),
     },
-}, serializedControl(async ({ name, session }) => {
+}, serializedControl(async ({ name, session, paceMs }) => {
     try {
         name = name ?? session;
+        // A pace with no session named is meant for the whole run: somebody is
+        // watching and wants to keep up with all of it, not one lane.
+        if (paceMs !== undefined && !name) {
+            const applied = [...engines.values()].map((e) => e.setPace(paceMs));
+            const at = applied[0] ?? normalizePace(paceMs);
+            return text((at > 0
+                ? `Every live session now waits at least ${at} ms between actions, so a person can follow along.`
+                : `Every live session is back to full speed: as fast as its page allows.`) + `\n${sessionLines()}`, activeName);
+        }
+        if (paceMs !== undefined && name) {
+            if (!engines.has(name))
+                return text(`No session named "${name}" yet — create it with scout_attach { session: "${name}", … }.\n${sessionLines()}`, activeName);
+            const at = engines.get(name).setPace(paceMs);
+            return text((at > 0 ? `${name} now waits at least ${at} ms between actions.` : `${name} is back to full speed.`) + `\n${sessionLines()}`, activeName);
+        }
         if (!name)
             return text(sessionLines() + liveLine(), activeName);
         if (!engines.has(name)) {
@@ -835,6 +927,28 @@ server.registerTool("scout_navigate", {
         return errorText(err);
     }
 }));
+server.registerTool("scout_request", {
+    description: "Call the app's own API as this session, with the UI bypassed — the check that turns a hidden or disabled control into a proven refusal. A button that is not shown proves nothing; the same action refused by the server does. The fetch runs IN the page, so it carries the session's cookies and replays the Authorization header the app itself last sent, and it passes through the same interception the write policy is enforced on: in safe-write a mutation on a record this session did not create is refused here exactly as it would be for a click, and that refusal is the engine's safety net, not a finding. Returns the status line, the timing, the headers that decide whether two responses are truly identical (content-type, location, www-authenticate, retry-after, cache-control), and the body. Unlike a shell call, every request is recorded in the run's trail and its signature is what a finding should quote. Paths are fenced to the attached origin: use another session to reach another host.",
+    inputSchema: {
+        path: z.string().min(1).max(2000).describe("Path on the attached origin, e.g. /api/things/12, or a full URL on that same origin"),
+        method: z.enum(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]).optional().describe("Default GET"),
+        body: z.string().max(20000).optional().describe("Request body, sent as application/json unless a content-type header is given"),
+        headers: z
+            .record(z.string().max(2000))
+            .optional()
+            .describe("Extra headers. One given here wins over the app's own, which is how a session tests a different or absent credential."),
+        task: taskParam,
+        objective: legacyObjectiveParam,
+        session: sessionParam,
+    },
+}, serializedPerSession("scout_request", async (args, session) => {
+    try {
+        return text(await engineFor(session).apiRequest({ method: args.method, path: args.path, body: args.body, headers: args.headers }), session);
+    }
+    catch (err) {
+        return errorText(err);
+    }
+}));
 server.registerTool("scout_back", {
     description: "Go back in browser history (tests back-button resilience).",
     inputSchema: { task: taskParam, objective: legacyObjectiveParam, session: sessionParam },
@@ -911,11 +1025,11 @@ server.registerTool("scout_journey", {
     }
 }));
 server.registerTool("scout_note", {
-    description: "Cumulative WRITTEN knowledge about the tested app — .scenescout/ASSUMPTIONS.md, in prose a human can read and correct. memory.json stores coverage; this stores UNDERSTANDING, so every run starts smarter than the last. READ it at the start of every session ({action:'read'}). ADD durable learnings as you go ({action:'add', section, note}): what the app is for (app-model), who each role is and what they're FOR — infer the persona from what the role can see and do, e.g. 'qa-role = reviewer: approves orders, cannot administer' (roles), UI patterns the app follows (conventions), rules discovered the hard way like 'an order can only ship once approved' (constraints), fragile areas worth re-testing every run (risks), domain terms (glossary). Notes are dated, attributed to the acting role, and deduplicated. Do NOT record session-specific facts (ids, counts) — only durable knowledge.",
+    description: "Cumulative WRITTEN knowledge about the tested app — .scenescout/ASSUMPTIONS.md, in prose a human can read and correct. memory.json stores coverage; this stores UNDERSTANDING, so every run starts smarter than the last. READ it at the start of every session ({action:'read'}). ADD durable learnings as you go ({action:'add', section, note}): what the app is for (app-model), who each role is and what they're FOR — infer the persona from what the role can see and do, e.g. 'qa-role = reviewer: approves orders, cannot administer' (roles), UI patterns the app follows (conventions), rules discovered the hard way like 'an order can only ship once approved' (constraints), fragile areas worth re-testing every run (risks), domain terms (glossary), and how to get the app testable at all — the command that regenerates an expired login state, what has to be running (setup), which the engine reads back to you the next time a storage state has expired. Notes are dated, attributed to the acting role, and deduplicated. Do NOT record session-specific facts (ids, counts) — only durable knowledge.",
     inputSchema: {
         action: z.enum(["read", "add"]).describe("'read' the accumulated knowledge, or 'add' one durable learning"),
         section: z
-            .enum(["app-model", "roles", "conventions", "constraints", "risks", "glossary"])
+            .enum(["app-model", "roles", "conventions", "constraints", "risks", "glossary", "setup"])
             .optional()
             .describe("For add: which knowledge section this belongs to"),
         note: z.string().max(500).optional().describe("For add: the learning, one or two sentences, written for a future reader with no context"),
@@ -955,27 +1069,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
@@ -1044,9 +1138,13 @@ server.registerTool("scout_report", {
             .enum(["minimal", "medium", "extensive"])
             .default("medium")
             .describe("Which completion contract to enforce — match the level the run was asked for"),
+        history: z
+            .enum(["index", "full"])
+            .default("index")
+            .describe("How much of the history to print. 'index' lists findings from earlier runs, and resolved ones, as a row each: id, severity, age, title. 'full' prints every one in full as before — on one project that was 1.75 MB against 113 KB, nearly half of it findings already fixed. Use 'full' when handing the document to someone who has no access to the memory."),
         session: sessionParam,
     },
-}, serializedPerSession("scout_report", async ({ force, level }, session) => {
+}, serializedPerSession("scout_report", async ({ force, level, history }, session) => {
     try {
         const eng = engineFor(session);
         if (!eng.memory)
@@ -1095,6 +1193,7 @@ server.registerTool("scout_report", {
                 `Then call scout_report again. Pass force=true ONLY if the user explicitly capped the budget.`, session);
         }
         const { path: p, summary } = generateReport(eng.memory, eng.oracleLog.all, {
+            history,
             routesVisited: all.length - unvisited.length,
             routesTotal: all.length,
             designAudits: eng.designAuditCount,
@@ -1135,6 +1234,39 @@ server.registerTool("scout_resolve", {
         return errorText(err);
     }
 }));
+server.registerTool("scout_verify", {
+    description: 'Re-test findings earlier runs left open. With no arguments, returns the open findings in the order to re-test them — worst route first, grouped so a route is walked once — each with its evidence and repro steps. Pass ids to narrow it to specific findings. After re-testing one, call again with id and verdict to record what you saw: "gone" resolves it, "present" stamps it confirmed so the report stops calling it unverified, "changed" keeps it open and says the behaviour differs. Use after a fix wave, or at the start of a run against an app this project has tested before.',
+    inputSchema: {
+        id: z.string().optional().describe("The finding being verified. Omit to get the worklist."),
+        verdict: z.enum(VERDICTS).optional().describe('What the re-test found: "gone", "present" or "changed". Requires id.'),
+        note: z.string().max(500).optional().describe("What you saw, in a sentence. Shown in the report beside the verdict."),
+        ids: z.array(z.string()).max(50).optional().describe("Narrow the worklist to these finding ids."),
+        session: sessionParam,
+    },
+}, serializedPerSession("scout_verify", async ({ id, verdict, note, ids }, session) => {
+    try {
+        const eng = engineFor(session);
+        if (!eng.memory)
+            throw new Error("Not attached.");
+        if (verdict && !id)
+            return text(`Pass the finding the verdict is about: scout_verify { id: "a1b2c3d4e5", verdict: "${verdict}" }.`, session);
+        if (id && !verdict) {
+            return text(`Pass what the re-test found: scout_verify { id: "${id}", verdict: "gone" | "present" | "changed" }.`, session);
+        }
+        if (id && verdict) {
+            const f = eng.memory.verifyFinding(id, verdict, note);
+            if (!f)
+                return text(`No finding with id ${id}.`, session);
+            return text(describeVerdict(f, verdict, note), session);
+        }
+        const findings = eng.memory.findings;
+        const missing = ids && ids.length > 0 ? unknownIds(findings, ids) : [];
+        return text(formatWorklist(verifyWorklist(findings, ids), missing), session);
+    }
+    catch (err) {
+        return errorText(err);
+    }
+}));
 server.registerTool("scout_close", {
     description: "Close a session's browser (memory persists on disk). Default: the DEFAULT session. Pass session to close a specific one, or all=true to close every live session at the end of a multi-role run.",
     inputSchema: {
@@ -1213,7 +1345,13 @@ async function shutdown() {
     await Promise.allSettled(liveTokenWrites.values());
     for (const dir of liveDirs) {
         try {
-            fs.rmSync(path.join(dir, LIVE_TOKEN_FILE), { force: true });
+            fs.rmSync(path.join(dir, liveTokenFileName(process.pid)), { force: true });
+            fs.rmSync(path.join(dir, statusFileName(process.pid)), { force: true });
+            // The shared names belong to whichever engine is still running, so they
+            // are only removed when this process is the last one holding them.
+            if (liveEngines(dir, pidAlive).filter((e) => e.pid !== process.pid).length === 0) {
+                fs.rmSync(path.join(dir, LIVE_TOKEN_FILE), { force: true });
+            }
         }
         catch (err) {
             console.error(`[scenescout] could not remove the live view's token file in ${dir}: ${err instanceof Error ? err.message : String(err)}`);

package/dist/scan.js

@@ -340,6 +340,49 @@ export function scanProject(projectDir) {
         notes,
     };
 }
+/**
+ * Whether a saved login is still good, read from the expiry inside its own
+ * token. A stale storage state is otherwise discovered only by attaching and
+ * being told AUTH FAILED, after a role has been chosen and a browser started —
+ * and in one project every one of 168 saved logins had expired.
+ *
+ * Best-effort by design: a state whose token cannot be read is reported as
+ * nothing rather than as a problem, because plenty of apps do not use JWTs.
+ */
+export function describeAuthAge(file, nowMs = Date.now()) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return "";
+    }
+    const exp = jwtExpiry(raw);
+    if (exp === null)
+        return "";
+    const left = Math.round((exp - nowMs) / 60_000);
+    if (left <= 0)
+        return " (EXPIRED)";
+    return left < 30 ? ` (${left}m left)` : "";
+}
+/** The soonest `exp` of any JWT-looking value in the file, as milliseconds. */
+function jwtExpiry(raw) {
+    let soonest = null;
+    for (const match of raw.matchAll(/eyJ[A-Za-z0-9_-]{4,}\.([A-Za-z0-9_-]{4,})\.[A-Za-z0-9_-]{4,}/g)) {
+        try {
+            const body = Buffer.from(match[1].replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8");
+            const exp = JSON.parse(body).exp;
+            if (typeof exp !== "number")
+                continue;
+            const ms = exp * 1000;
+            soonest = soonest === null ? ms : Math.min(soonest, ms);
+        }
+        catch {
+            // Not a token we can read; the next match may be.
+        }
+    }
+    return soonest;
+}
 export function formatScan(result) {
     const lines = [
         `Project: ${result.projectDir}`,
@@ -348,8 +391,11 @@ export function formatScan(result) {
         `Playwright config: ${result.hasPlaywright ? "yes" : "no"} · data-testid convention: ${result.usesTestids ? "yes" : "not detected"}`,
         `Auth storage states (${result.authStates.length}): ${result.authStates
             .slice(0, 8)
-            .map((p) => path.basename(p))
+            .map((p) => `${path.basename(p)}${describeAuthAge(p)}`)
             .join(", ") || "none"}`,
+        ...(result.authStates.length > 0 && result.authStates.every((p) => describeAuthAge(p) === " (EXPIRED)")
+            ? [`  ⚠ Every saved login listed here has expired. scout_attach would land on a login page; regenerate them before attaching.`]
+            : []),
         `Routes (${result.routes.length}):`,
         ...result.routes.slice(0, 60).map((r) => `  ${r}`),
         ...(result.routes.length > 60 ? [`  … and ${result.routes.length - 60} more`] : []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.1.1",
+  "version": "3.3.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 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 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,11 +79,18 @@
     "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",
     "demo-test": "tsx --test scripts/demo-test.ts",
-    "hygiene-test": "tsx --test scripts/hygiene-test.ts"
+    "hygiene-test": "tsx --test scripts/hygiene-test.ts",
+    "pace-test": "tsx --test scripts/pace-test.ts",
+    "request-test": "tsx --test scripts/request-test.ts",
+    "settle-test": "tsx --test scripts/settle-test.ts",
+    "claims-test": "tsx --test scripts/claims-test.ts",
+    "verify-test": "tsx --test scripts/verify-test.ts",
+    "brief-test": "tsx --test scripts/brief-test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",