scenescout 1.2.0 → 1.4.0

package/dist/installer.js

@@ -16,14 +16,16 @@ export const MCP_NAME = "scenescout";
 const LEGACY_SKILL_NAMES = ["frontend-tester", "scenecraft"];
 const LEGACY_MCP_NAMES = ["scenecraft"];
 /** Real runner. `missing` separates "the binary is not installed" from "it ran and failed". */
-export const spawnRunner = (command, args) => {
-    const r = spawnSync(command, args, { encoding: "utf8", timeout: 60_000 });
+export const spawnRunner = (command, args, opts) => {
+    const r = spawnSync(command, args, { encoding: "utf8", timeout: 60_000, cwd: opts?.cwd });
     const code = r.error?.code;
     // On Windows node refuses to start a .cmd or .bat file directly (EINVAL). For
     // the caller that is the same situation as a missing binary: nothing ran, and
     // the command has to be handed to the person instead.
     const missing = code === "ENOENT" || (process.platform === "win32" && code === "EINVAL");
-    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? (r.error ? String(r.error.message) : ""), missing };
+    // With `encoding` set, a command that never ran still yields "" for stderr: the error is the only account of it.
+    const stderr = r.stderr || (code === "ETIMEDOUT" ? "npm did not finish within 60 s" : r.error ? String(r.error.message) : "");
+    return { status: r.status, stdout: r.stdout ?? "", stderr, missing };
 };
 /** Written into a copy-mode install so a later install can tell its own copy from a user's directory. */
 const OWNERSHIP_MARKER = ".installed-by-scenescout";
@@ -248,13 +250,89 @@ export function parseRegistration(listing) {
     const field = (name) => new RegExp(`^[ \\t]*${name}:[ \\t]*(\\S.*?)[ \\t]*$`, "m").exec(listing)?.[1] ?? null;
     return { command: field("Command"), serverPath: field("Args") };
 }
+/** The command the package's `bin` entry provides. */
+export const CLI_NAME = "scenescout";
+const isCheckoutRoot = (packageRoot) => fs.existsSync(path.join(packageRoot, "tsconfig.json")) && fs.existsSync(path.join(packageRoot, "src"));
+/**
+ * Where a command resolves in the user's own shell, or null.
+ *
+ * npm and npx put `node_modules/.bin` directories on PATH for the length of a
+ * run. Under `npx scenescout install` that makes the command appear installed
+ * when it will be gone the moment the run ends, so those entries are skipped.
+ */
+export function findOnUserPath(opts) {
+    const exists = opts.exists ?? fs.existsSync;
+    for (const dir of opts.pathValue.split(opts.delimiter ?? path.delimiter).filter(Boolean)) {
+        if (/[\\/]node_modules[\\/]\.bin[\\/]?$/.test(dir))
+            continue;
+        for (const name of opts.names) {
+            const candidate = path.join(dir, name);
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * What it takes for `scenescout` to work as a command in a terminal.
+ *
+ * The MCP registration never needed that: it stores an absolute launcher. But
+ * `scenescout status` and `scenescout watch` are typed by a person, and both a
+ * source checkout and an npx run leave nothing on PATH, so the commands the
+ * tool itself recommends answered "command not found".
+ *
+ * A checkout is linked, so the command always runs what was last built. Any
+ * other install gets the same version installed globally. A checkout takes the
+ * name over from another copy, the way it takes over the MCP registration; a
+ * packaged install leaves an existing command alone.
+ */
+export function planCommand(opts) {
+    const checkout = isCheckoutRoot(opts.packageRoot);
+    const manual = checkout ? `npm link   (run in ${opts.packageRoot})` : `npm install -g ${CLI_NAME}@${opts.version}`;
+    if (opts.resolved !== null) {
+        const mine = samePath(opts.resolved, path.join(opts.packageRoot, "dist", "cli.js"));
+        if (mine || !checkout)
+            return { action: "present", at: opts.resolved };
+    }
+    // npm on Windows is a .cmd shim, which node cannot start directly.
+    if (opts.platform === "win32")
+        return { action: "manual", manual, why: "this step cannot start npm on Windows" };
+    const beside = path.join(path.dirname(opts.nodePath), "npm");
+    // The npm beside the running node installs into that node's prefix, which is
+    // the one whose bin directory the shell that started us already has on PATH.
+    const npm = fs.existsSync(beside) ? beside : "npm";
+    return checkout
+        ? { action: "run", how: "link", command: npm, args: ["link"], cwd: opts.packageRoot, manual, replaces: opts.resolved }
+        : { action: "run", how: "global", command: npm, args: ["install", "-g", `${CLI_NAME}@${opts.version}`], manual, replaces: null };
+}
+export function ensureCommand(plan, run) {
+    if (plan.action === "present")
+        return { status: "present", at: plan.at };
+    if (plan.action === "manual")
+        return { status: "failed", manual: plan.manual, detail: plan.why };
+    const r = run(plan.command, plan.args, { cwd: plan.cwd });
+    if (r.missing)
+        return { status: "failed", manual: plan.manual, detail: "npm was not found" };
+    if (r.status !== 0) {
+        // A system-wide node owns its prefix as root; that is the usual reason, and
+        // the last line of npm's output names it. With no output at all (a timeout,
+        // a kill) the exit is all there is to say.
+        const lines = (r.stderr || r.stdout).trim().split("\n");
+        return {
+            status: "failed",
+            manual: plan.manual,
+            detail: lines.find((l) => /EACCES|EPERM|ERR!/.test(l))?.trim() || lines[lines.length - 1] || `npm exited ${r.status ?? "without finishing"}`,
+        };
+    }
+    return { status: "installed", how: plan.how, replaced: plan.replaces };
+}
 /**
  * The command that repairs a setup, for THIS kind of install. A source checkout
  * has `npm run setup`; someone who installed from npm has no such script, and
  * telling them to run it sends them looking for a package.json they never had.
  */
 export function repairCommands(packageRoot) {
-    const isCheckout = fs.existsSync(path.join(packageRoot, "tsconfig.json")) && fs.existsSync(path.join(packageRoot, "src"));
+    const isCheckout = isCheckoutRoot(packageRoot);
     // Installing "chromium" brings the headless shell with it, so the plain
     // setup command already repairs either Chromium build.
     const browserFlags = (target) => (engineOf(target) === "chromium" ? "" : ` --browser-only --browsers ${target}`);

package/dist/mcp-server.js

@@ -21,7 +21,9 @@
  * - Self-healing: orphaned browser processes from crashed runs are reaped at
  *   startup and on launch failure; attach retries once after reaping.
  * - Observable: .scenescout/status.json in the tested project always shows
- *   what each session is doing right now (`scenescout status <project>`).
+ *   what EVERY session is doing right now (`scenescout status <project>`), and
+ *   a loopback-only live view shows what each one is looking at
+ *   (`scenescout watch <project>`, engine/live.ts, ADR 7).
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -35,6 +37,7 @@ import { reapOrphanBrowsers } from "./engine/reaper.js";
 import { MemoryStore, redactSecrets } from "./engine/memory.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 { computeGaps, formatRouteCoverage, generateReport } from "./engine/report.js";
 import { EXPLORE_PROMPT_ARGUMENTS, explorePrompt, loadPlaybook, PLAYBOOK_PROMPT, PLAYBOOK_TOOL, SERVER_INSTRUCTIONS } from "./playbook.js";
 import { formatScan, scanProject } from "./scan.js";
@@ -87,32 +90,170 @@ function errorText(err) {
         isError: true,
     };
 }
+/** One entry per live session: what status.json and the live view both read. */
+const board = new StatusBoard();
+/** The session whose call wrote status last. The top-level fields of status.json describe it, as they always have. */
+let lastWriter = null;
+let live = null;
+let liveAddress = null;
+/** Set while the server is starting and kept afterwards, so every caller awaits the same start. */
+let liveStart = null;
+/** Project directories holding this process's token file, so shutdown can take it back. */
+const liveDirs = new Set();
+/** Token writes in flight, so shutdown waits for them instead of racing a file that appears after the rm. */
+const liveTokenWrites = new Map();
+let liveTokenWarned = false;
+/** Why the live view could not start, when it could not: told to the agent and written to status.json. */
+let liveError = null;
+const liveProvider = {
+    snapshot: () => ({ pid: process.pid, version: PKG_VERSION, at: new Date().toISOString(), sessions: board.list() }),
+    // The engine holds no reasoning — it never sees one — so the feed is what the
+    // session DID: the action log, which is the same trail a finding's repro uses.
+    activity: (session, limit) => feedForSession(engines.get(session)?.memory?.actionLog ?? [], session, limit, redactSecrets),
+    // The same document scout_report writes at the end, rendered now and not
+    // written: what the run has found so far, its scores and its gap ledger.
+    // Findings and coverage are project-wide; the route, audit and mode figures
+    // are the session's that wrote status last, so in a multi-session run they
+    // can shift between polls.
+    report: () => {
+        const eng = (lastWriter && engines.get(lastWriter.session)) ?? engines.values().next().value;
+        if (!eng?.memory)
+            return null;
+        const { markdown } = generateReport(eng.memory, eng.oracleLog.all, reportExtras(eng), { write: false });
+        return { markdown: redactSecrets(markdown), at: new Date().toISOString() };
+    },
+    // Both go around the session queue on purpose: a viewer must never wait
+    // behind the agent's calls, and a session that is stuck is the one most
+    // worth looking at.
+    screenshot: async (session) => (await engines.get(session)?.liveShot()) ?? null,
+    startStream: async (session, onFrame, onEnd) => (await engines.get(session)?.startScreencast(onFrame, onEnd)) ?? null,
+};
+/** What the report needs to know beyond memory: the one place it is built, so the live view and scout_report cannot drift apart. */
+function reportExtras(eng) {
+    const unvisited = eng.unvisitedKnownRoutes();
+    const all = eng.allKnownRoutes();
+    return {
+        routesVisited: all.length - unvisited.length,
+        routesTotal: all.length,
+        designAudits: eng.designAuditCount,
+        createdResources: eng.createdResources,
+        unvisitedRoutes: unvisited,
+        mode: eng.mode,
+        policyAttributed: eng.oracleLog.policyAttributed,
+    };
+}
+/** 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);
+    const write = fs.promises
+        .writeFile(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(() => {
+        liveDirs.add(dir);
+    })
+        .catch((err) => {
+        // A file with the wrong bits, or none: either way nothing to take back later.
+        void fs.promises.rm(file, { force: true }).catch(() => { });
+        if (!liveTokenWarned)
+            console.error(`[scenescout] could not write the live view's token file in ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+        liveTokenWarned = true;
+    })
+        .finally(() => liveTokenWrites.delete(dir));
+    liveTokenWrites.set(dir, write);
+}
+/**
+ * Started with the first attach rather than at boot: a server nobody attaches
+ * to should not open a port. Never rejects — observability is best-effort, and
+ * a port that will not open must not cost the run anything.
+ */
+async function ensureLive(dir) {
+    if (process.env[LIVE_ENV] === "off")
+        return;
+    if (liveAddress)
+        return publishLiveToken(dir);
+    liveStart ??= startLiveServer();
+    await liveStart;
+    if (!liveAddress)
+        return;
+    publishLiveToken(dir);
+    // The port is new, so a reader polling status.json needs it rewritten.
+    flushStatus(dir);
+}
+function startLiveServer() {
+    const starting = new LiveServer(liveProvider);
+    return starting
+        .start()
+        .then((address) => {
+        live = starting;
+        liveAddress = address;
+        liveError = null;
+    })
+        .catch((err) => {
+        // Say why, once, and let a later attach try again.
+        const reason = err instanceof Error ? err.message : String(err);
+        if (liveError !== reason)
+            console.error(`[scenescout] the live view could not start: ${reason}`);
+        liveError = reason;
+        liveStart = null;
+    });
+}
+/**
+ * The line that hands the live view to the person running the agent. The
+ * address holds the token, and a tool result lands in the client's transcript;
+ * that is accepted (ADR 7) because the address answers on this machine only.
+ */
+function liveLine() {
+    if (!liveAddress)
+        return liveError ? `\nLive view unavailable: ${liveError}` : "";
+    return (`\nLive view: http://127.0.0.1:${liveAddress.port}/${liveAddress.token}/ — give this address to the user so they can watch every session ` +
+        `(current tool, page thumbnail, optional live stream). It opens on this machine only and cannot act on the run.`);
+}
+function flushStatus(dir) {
+    // Fire-and-forget: status is best-effort observability on every tool call's
+    // hot path and must never add blocking filesystem latency. The writer
+    // queues writes per directory and lands each by rename, so a reader never
+    // sees a torn file.
+    void writeStatusFile(dir, JSON.stringify({
+        pid: process.pid,
+        phase: lastWriter?.phase ?? "idle",
+        tool: lastWriter?.tool ?? "",
+        session: lastWriter?.session ?? "",
+        role: lastWriter?.role ?? "anonymous",
+        sessions: [...engines.keys()],
+        url: lastWriter?.url ?? "",
+        at: new Date().toISOString(),
+        // Everything above describes one session. This is all of them.
+        detail: board.list(),
+        ...(liveAddress ? { live: { port: liveAddress.port } } : liveError ? { live: { error: liveError } } : {}),
+    }, null, 2));
+}
 /**
  * Live status for the tested project (`scenescout status <project>` or any
- * supervising layer reads this): which session/tool is running right now.
+ * supervising layer reads this): what every session is doing right now.
  * Best-effort — observability must never break the tool call itself.
  */
-function writeStatus(session, phase, tool) {
-    const dir = engines.get(session)?.memory?.dir;
-    if (!dir)
+function writeStatus(session, phase, tool, budgetMs) {
+    const eng = engines.get(session);
+    const dir = eng?.memory?.dir;
+    if (!eng || !dir)
         return;
-    // Fire-and-forget async write: status is best-effort observability and runs
-    // on every tool call's hot path — it must never add blocking filesystem
-    // latency. Two sessions writing concurrently is a benign last-write-wins on
-    // this one project-level file; each session's OWN status still reaches disk.
-    void fs.promises
-        .writeFile(path.join(dir, "status.json"), JSON.stringify({
-        pid: process.pid,
+    // status.json is a poll target that gets pasted into bug reports.
+    const { task, objective, ...described } = eng.liveDescription;
+    lastWriter = board.update(session, {
+        role: eng.role,
         phase,
         tool,
-        session,
-        role: engines.get(session)?.role ?? "anonymous",
-        sessions: [...engines.keys()],
-        // status.json is a poll target that gets pasted into bug reports.
-        url: redactSecrets(engines.get(session)?.currentUrl ?? ""),
-        at: new Date().toISOString(),
-    }, null, 2))
-        .catch(() => { });
+        url: redactSecrets(eng.currentUrl),
+        ...(budgetMs ? { budgetMs } : {}),
+        ...described,
+        ...(task ? { task: redactSecrets(task) } : {}),
+        ...(objective ? { objective: redactSecrets(objective) } : {}),
+    });
+    void ensureLive(dir);
+    flushStatus(dir);
 }
 /** The watchdog's timeout answer — a diagnosable result, not a hang. */
 function watchdogTimeout(label, ms) {
@@ -133,7 +274,7 @@ function serializedPerSession(label, fn, timeoutMs = 60_000) {
     return (args) => {
         const session = args.session ?? activeName;
         const exec = async () => {
-            writeStatus(session, "running", label);
+            writeStatus(session, "running", label, timeoutMs);
             try {
                 const out = await withWatchdog(label, fn(args, session), timeoutMs, watchdogTimeout);
                 // `activeName` is process-global and every scout_attach moves it. With
@@ -241,13 +382,18 @@ server.registerTool("scout_attach", {
             .describe("Browser to drive. Default: the SCENESCOUT_BROWSER environment variable, else chromium. firefox and webkit must be downloaded first (scenescout install --browser-only --browsers firefox). Use them for a cross-browser pass; stay on chromium otherwise."),
         viewportWidth: z.number().int().min(320).max(3840).optional().describe("Viewport width (default 1280); use e.g. 390 for a mobile pass"),
         viewportHeight: z.number().int().min(480).max(2400).optional().describe("Viewport height (default 900)"),
+        task: z
+            .string()
+            .max(300)
+            .optional()
+            .describe("What this session is for, in one sentence (e.g. 'Approve and reject orders as a manager'). Shown to the person watching the live view, next to the goal of whatever scout_journey is active. Worth setting whenever more than one session is running."),
         session: z
             .string()
             .max(40)
             .optional()
             .describe("Session name for multi-role runs (e.g. 'admin', 'qa'). Creates/replaces that session's browser and makes it the default. Default: 'default'."),
     },
-}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, browser, viewportWidth, viewportHeight, session, }) => {
+}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, browser, viewportWidth, viewportHeight, task, session, }) => {
     try {
         const target = session ?? activeName;
         if (session) {
@@ -308,9 +454,16 @@ server.registerTool("scout_attach", {
             /* conflict detection is best-effort */
         }
         const viewport = viewportWidth && viewportHeight ? { width: viewportWidth, height: viewportHeight } : undefined;
-        const out = await eng.attach({ url, projectDir: projectPath, storageStatePath, mode, headed, browser, viewport, memoryStore: store });
+        const out = await eng.attach({ url, projectDir: projectPath, storageStatePath, mode, headed, browser, viewport, task, memoryStore: store });
         eng.role = storageStatePath ? path.basename(storageStatePath).replace(/\.json$/i, "") : "anonymous";
-        return text(out + conflictNote + (engines.size > 1 ? `\n${sessionLines()}` : ""), target);
+        // Put the session on the board now, so the live view shows it before its
+        // first tool call. liveLine() needs the port, so the server is awaited
+        // here rather than started in the background by writeStatus.
+        if (eng.memory?.dir) {
+            await ensureLive(eng.memory.dir);
+            writeStatus(target, "idle", "scout_attach");
+        }
+        return text(out + conflictNote + (engines.size > 1 ? `\n${sessionLines()}` : "") + liveLine(), target);
     }
     catch (err) {
         return errorText(err);
@@ -336,7 +489,7 @@ server.registerTool("scout_session", {
     try {
         name = name ?? session;
         if (!name)
-            return text(sessionLines(), activeName);
+            return text(sessionLines() + liveLine(), activeName);
         if (!engines.has(name)) {
             return text(`No session named "${name}" yet — create it with scout_attach { session: "${name}", … }.\n${sessionLines()}`, activeName);
         }
@@ -819,19 +972,35 @@ server.registerTool("scout_close", {
             const names = [...engines.keys()];
             // Closes are independent per-browser — run them in parallel so N wedged
             // sessions cost one 8s teardown cap total, not N of them.
+            const dirs = new Set();
+            for (const e of engines.values())
+                if (e.memory?.dir)
+                    dirs.add(e.memory.dir);
+            for (const name of engines.keys())
+                live?.dropSession(name);
             await Promise.allSettled([...engines.values()].map((e) => e.close()));
             engines.clear();
             sessionQueue.clear();
+            board.clear();
+            lastWriter = null;
+            for (const dir of dirs)
+                flushStatus(dir);
             return text(`All sessions closed (${names.join(", ") || "none were live"}). Memory and reports remain in .scenescout/.`, activeName);
         }
         const name = session ?? activeName;
         const eng = engines.get(name);
         if (!eng)
             return text(`No live session "${name}".`, name);
+        live?.dropSession(name);
         await eng.close();
         const saveError = eng.memory?.lastSaveError;
         engines.delete(name);
         sessionQueue.forget(name);
+        board.remove(name);
+        if (lastWriter?.session === name)
+            lastWriter = null;
+        if (eng.memory?.dir)
+            flushStatus(eng.memory.dir);
         if (activeName === name)
             activeName = engines.keys().next().value ?? "default";
         return text(`Session "${name}" closed. Memory and report remain in .scenescout/.` +
@@ -845,13 +1014,34 @@ server.registerTool("scout_close", {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // A client that exits by closing the pipe sends no signal. Without this the
+    // process, its port, its browsers and its token file all outlived the run.
+    const clientGone = () => {
+        void shutdown().finally(() => process.exit(0));
+    };
+    transport.onclose = clientGone;
+    // The transport reports a closed pipe on some platforms and not others, and
+    // on Windows the SIGTERM a client sends next is a plain kill that runs no
+    // handler. stdin ending is the one signal every platform gives.
+    process.stdin.once("end", clientGone);
+    process.stdin.once("close", clientGone);
     // Self-heal across restarts: browsers whose parent crashed/was killed can
     // linger and have been observed to wedge fresh launches. After connect —
     // the stdio handshake must not wait on a full process-table scan.
     setImmediate(() => reapOrphanBrowsers());
 }
 async function shutdown() {
-    await Promise.allSettled([...engines.values()].map((e) => e.close()));
+    // The token outlives nothing: a file left behind would name a port some other process may get next.
+    await Promise.allSettled(liveTokenWrites.values());
+    for (const dir of liveDirs) {
+        try {
+            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)}`);
+        }
+    }
+    await Promise.allSettled([live?.stop(), ...[...engines.values()].map((e) => e.close())]);
 }
 process.on("SIGINT", () => {
     void shutdown().finally(() => process.exit(0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "1.2.0",
+  "version": "1.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 memory-test && npm run install-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 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",
@@ -81,6 +81,8 @@
     "contract-test": "tsx --test scripts/contract-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"
   },
   "dependencies": {

package/skills/scenescout/SKILL.md

@@ -48,7 +48,7 @@ You are the brain of an exploratory UI tester. The SceneScout MCP server gives y
 |---|---|---|
 | `minimal` | Every known route visited (crawl does this) + ≥1 design audit + 1–2 primary journeys as plans + crawl-flagged problems triaged. The report DISCLOSES remaining gaps in its Gap Ledger — minimal is honest-but-fast, not silent. | 1 crawl + 2–4 plans + a few snapshots |
 | `medium` (default) | minimal + design audits on several distinct routes (gate: ≥ min(3, visited/10)) + every unexercised interactable class exercised once + every form submitted valid AND invalid | + interactive passes per module |
-| `extensive` | medium + fuzzing (empty, 1000-char, unicode, `<script>`; for uploads, `scout_upload {name}` with a wrong extension against `accept`, a 255-char name, unicode), back/refresh/deep-link resilience, keyboard-only pass, **an `scout_journey` per module's primary task**, **the impatient-user pass** (below), **≥2 roles compared**, **the anonymous auth-surface pass** (signup / forgot-password walked to the mailbox wall, step 8 above), and source-grounding for every absence-claim. **`scout_report {level:'extensive'}` REFUSES while the Gap Ledger is non-empty** — that refusal IS the completeness guarantee: an extensive report can only exist when every known route is visited, exercised, audited, journey-measured, and role-compared. | budget-capped by user |
+| `extensive` | medium + fuzzing (empty, 1000-char, unicode, and markup such as `<script>` or `<img src=x onerror=…>` — the engine remembers every markup-shaped value you type and reports a `dom_injection` violation when it later renders as an element on any page, which is a stored or reflected XSS: file it as `security`, high, naming the field and the page; for uploads, `scout_upload {name}` with a wrong extension against `accept`, a 255-char name, unicode), back/refresh/deep-link resilience, keyboard-only pass, **an `scout_journey` per module's primary task**, **the impatient-user pass** (below), **≥2 roles compared**, **the anonymous auth-surface pass** (signup / forgot-password walked to the mailbox wall, step 8 above), and source-grounding for every absence-claim. **`scout_report {level:'extensive'}` REFUSES while the Gap Ledger is non-empty** — that refusal IS the completeness guarantee: an extensive report can only exist when every known route is visited, exercised, audited, journey-measured, and role-compared. | budget-capped by user |
 
 **Levels in `observe` mode.** No form submission reaches the server, so "every form submitted valid AND invalid" means submitted and observed client-side; the unsubmitted-forms gap stays in the ledger, worded as the mode's doing. `extensive` refuses while any gap remains, so an `observe` run tops out at `medium` — say so rather than forcing the report.
 
@@ -68,6 +68,7 @@ Some flows need a TEAM — a document one role submits and another approves, a r
 - While roles are NOT collaborating, use each one productively where its permissions matter (admin in /admin surfaces, low-privilege probing for permission leaks) — same coverage contract, different vantage points.
 - **Infer the PERSONA behind each role, and write it down.** From what a role can see and do (its nav, its dashboard, the capability matrix in the report), state what this person is FOR: "qa = reviewer — approves orders, assigns reviewers, no admin" / "user = front-line user — reads documents, completes reviews, raises orders". Record it with `scout_note {section:'roles'}`. Then test the persona's WORLD, not just the permissions: does the operator's landing page serve an operator? Is anything they need N clicks deep? The capability matrix's divergent rows are questions, not verdicts — each is either a correct boundary or a gap ("should this role be able to do this?"); say which you believe it is and why.
 - `scout_close {all: true}` at the end of a multi-role run; `scout_close {session}` to drop one role early.
+- **Several agents in parallel** (subagents or a workflow, each driving its own session): each agent attaches its session when it STARTS and closes it by name when it FINISHES. Never open sessions ahead for agents that have not started, and never hand an open session from one agent to the next: an agent waiting for its turn should hold no browser. Give each session a `task` when you attach it (`scout_attach {session, task:"Approve and reject orders as a manager"}`) and wrap each goal in `scout_journey`: the live view shows the task and the active journey's goal beside the session's feed, which is how the person watching knows what every agent is for. Keep that goal TRUE: one journey per goal, one goal per thing you are checking ("Save a settings change as the auditor", not "Check every page"), ended the moment it is decided and the next one started before you move on. A journey that outlives its goal shows the viewer an objective the session left behind minutes ago. Run roughly as many agents at once as the machine has cores, less two, since each drives a real browser; beyond that they only queue. Exploring one area is well within a mid-tier model, so run these agents on one (Sonnet or its equivalent in your client) unless the user names a model; keep the larger model for the agent that plans the split and writes the report. No agent may call `scout_close {all: true}` while others run — only the last step, once every agent has finished.
 
 ## The impatient-user pass (extensive)
 
@@ -78,7 +79,7 @@ Polite, precise testing misses how real users behave. Once per module's key flow
 - **Wrong-order behaviour:** press Enter mid-form before required fields are filled; go `scout_back` mid-wizard and return; submit, then immediately back-button. State should survive all three without data loss or duplicate records.
 - Keep attribution honest: these are deliberate probes — say so in findings ("under rapid double-click…"), so a developer can reproduce exactly.
 
-The engine is self-healing (orphaned browsers reaped, wedged calls time out with guidance instead of hanging) and observable: `.scenescout/status.json` + `scenescout status <project>` show what it's doing right now — point the user there if they ask for live progress.
+The engine is self-healing (orphaned browsers reaped, wedged calls time out with guidance instead of hanging) and observable: `.scenescout/status.json` + `scenescout status <project>` show what every session is doing right now, and there is a live view for the person running you: one card per session with its current tool, how long it has been there, a thumbnail of its page, a feed of the actions it just took, and a stream they can switch on. It works for headless runs too. **`scout_attach` returns its address on a `Live view:` line: pass that address to the user in your next message, once, so they can watch.** `scout_session` with no arguments repeats it if they ask again, and `scenescout watch <project>` opens it from a terminal. It is for the person watching: you do not need to open it, and a session shown as stuck there is one to re-attach.
 
 ## Judgment (what the engine can't do)