scenescout 3.2.0 → 3.4.0

package/dist/engine/settle.js

@@ -0,0 +1,97 @@
+/**
+ * How long to wait after an action before reading the page.
+ *
+ * This used to be a flat 400 ms sleep on every action, for a good reason:
+ * `waitForLoadState("networkidle")` latches once reached and then resolves
+ * instantly forever after, so it cannot be used to wait out the request an
+ * action just fired, and draining the oracles before that request lands would
+ * misattribute its violations to the next step.
+ *
+ * The floor was still the wrong shape. Measured against a demo app, a snapshot
+ * cost 740 ms of which 400 ms was the sleep — 54% of the wall time — and a run
+ * of 203 actions spent 81 seconds asleep. Meanwhile a page slower than 400 ms
+ * got cut off exactly when it mattered.
+ *
+ * The engine already intercepts every request, so it knows what is in flight.
+ * Waiting on THAT, with a quiet window after the last one starts, is both
+ * faster on a page that answers quickly and more patient with one that does
+ * not. The old constant survives as a ceiling rather than a floor.
+ *
+ * The same rule carries the deliberate slow-down: a run being watched by a
+ * person taking notes wants a fixed pace, not the fastest one. `paceMs` is a
+ * floor a session asks for; unset, a session goes as fast as its page allows.
+ */
+/** No request has started for this long and none is in flight: the page has settled. */
+export const QUIET_MS = 120;
+/** Longest to wait for requests to drain, however busy the page is. A page that never goes quiet must not stall the run. */
+export const SETTLE_CAP_MS = 2000;
+/** How often the wait re-checks. */
+export const SETTLE_TICK_MS = 20;
+/**
+ * Whether to keep waiting. Split out from the browser so the rule can be
+ * table-tested: it is the difference between a run that is fast and one that
+ * reads a page before it has finished changing.
+ */
+export function shouldKeepWaiting(state) {
+    // A pace a session asked for is a floor on the whole wait, and it is the
+    // only reason to wait once everything else says the page is ready.
+    if (state.elapsedMs < state.paceMs)
+        return true;
+    // Never longer than the cap, whatever the page is doing.
+    if (state.elapsedMs >= SETTLE_CAP_MS)
+        return false;
+    // Something is still out: wait for it, up to the cap.
+    if (state.inFlight > 0)
+        return true;
+    // Nothing in flight and nothing recent. The action itself is the last event
+    // that could still produce a request, so the quiet window runs from whichever
+    // of the two is later. Without this, an action whose request comes back
+    // through a hop — a click that posts to a service worker, which then fetches —
+    // is read while the page is between the two, and the request lands during the
+    // NEXT action, which is then blamed for it.
+    return Math.min(state.sinceLastStartMs, state.elapsedMs) < QUIET_MS;
+}
+/** A pace a session asked for, clamped. Negative or absurd values are a typo, not an instruction. */
+export const PACE_MAX_MS = 60_000;
+export function normalizePace(paceMs) {
+    if (typeof paceMs !== "number" || !Number.isFinite(paceMs) || paceMs <= 0)
+        return 0;
+    return Math.min(Math.round(paceMs), PACE_MAX_MS);
+}
+/** What the attach result says about a deliberate pace, or nothing when the session runs at full speed. */
+export function describePace(paceMs) {
+    if (paceMs <= 0)
+        return "";
+    return `\n⏱ PACE: at least ${paceMs} ms between actions, so a person can follow along. Unset it with paceMs: 0 to go as fast as the page allows.`;
+}
+/**
+ * Waiting for a client-side redirect that has not happened yet.
+ *
+ * A guard that redirects on a timer after hydration issues no request until it
+ * fires, so there is nothing for the request-based settle above to wait on:
+ * it goes quiet, the URL is read, and the page reports the route it was asked
+ * for rather than the login page it actually bounced to. The old flat 400 ms
+ * sleep covered this by accident, and removing it made the bounce invisible
+ * whenever a loaded machine delayed the timer past the quiet window.
+ *
+ * So where a BOUNCE VERDICT is about to be made — attach judging a storage
+ * state, navigate judging coverage — the URL is watched until it has held
+ * still, rather than read once. This is paid per navigation, not per action.
+ */
+/**
+ * How long the URL must hold still before a bounce verdict is believed.
+ *
+ * This is a window, not a guarantee: a guard slower than it still lands after
+ * the verdict. What it buys is the realistic case — a guard written to fire
+ * promptly, delayed by a loaded machine — which is the one that made this
+ * project's own CI fail intermittently on a 40 ms timer.
+ */
+export const URL_QUIET_MS = 400;
+/** Longest to watch. A page redirecting in a loop must not hold up the run. */
+export const URL_CAP_MS = 3000;
+/** Whether to keep watching the URL before judging where the page landed. */
+export function keepWatchingUrl(w) {
+    if (w.elapsedMs >= URL_CAP_MS)
+        return false;
+    return w.sinceChangeMs < URL_QUIET_MS;
+}

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

@@ -38,9 +38,12 @@ import { FINDING_CATEGORIES, MemoryStore, redactSecrets } from "./engine/memory.
 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";
@@ -241,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(() => {
@@ -487,6 +495,27 @@ server.server.setRequestHandler(GetPromptRequestSchema, (request) => {
 // 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.",
@@ -499,10 +528,35 @@ server.registerTool("scout_lane_report", {
         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 }] };
+        if (!parsed.ok) {
+            return {
+                content: [
+                    { type: "text", text: `Lane report REFUSED: ${parsed.reason}. Ask the lane once for the corrected object; do not re-judge its prose.` },
+                ],
+            };
+        }
+        // Keep what the lane decided, so the confidence it stated can be checked
+        // against what the run goes on to file. Best-effort: a lane report is
+        // still accepted if this project has no memory open yet, because the
+        // planner's fold must not depend on where the report was written.
+        // ONLY the lane's own session. Falling back to any engine with memory
+        // open put one project's decisions into another project's store whenever
+        // two sessions were attached to different apps — and the lane having
+        // already closed makes that the ordinary case, not an edge one.
+        const owner = engines.get(lane)?.memory;
+        const at = new Date().toISOString();
+        const kept = owner
+            ? owner.addLaneDecisions(lane, parsed.report.decisions.map((d) => ({ ...d, lane, at })))
+            : 0;
+        // Say when nothing was kept. Every lane closing its session before the
+        // planner folds its report is the order the method describes, and it
+        // leaves no memory to write to — reporting a bare "accepted" while the
+        // skill promises the decisions are kept is the kind of silence that
+        // 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}` }] };
     }
     catch (err) {
         return errorText(err);
@@ -543,7 +597,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)
@@ -555,7 +620,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) {
@@ -624,8 +689,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,
         });
@@ -643,7 +713,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);
@@ -664,10 +734,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)) {
@@ -860,6 +952,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 },
@@ -936,11 +1050,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"),
@@ -1049,9 +1163,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)
@@ -1100,6 +1218,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,
@@ -1140,6 +1259,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: {
@@ -1218,7 +1370,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.2.0",
+  "version": "3.4.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 lane-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 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",
@@ -84,7 +84,14 @@
     "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",
+    "calibration-test": "tsx --test scripts/calibration-test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",