scenescout 1.1.0 → 1.3.0

package/dist/installer.js

@@ -9,16 +9,23 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { engineOf } from "./browsers.js";
 export const SKILL_NAME = "scenescout";
 export const MCP_NAME = "scenescout";
 /** Names this tool's skill and MCP server had before renames; cleaned up on install so the old slash command and a duplicate tool set do not linger. */
 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 });
-    const missing = r.error?.code === "ENOENT";
-    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? (r.error ? String(r.error.message) : ""), missing };
+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");
+    // 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";
@@ -243,16 +250,103 @@ 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}`);
     return isCheckout
-        ? { setup: "npm run setup", build: "npm run build" }
-        : { setup: "npx -y scenescout install", build: "npx -y scenescout@latest install   (the installed package is incomplete; fetch it again)" };
+        ? {
+            setup: "npm run setup",
+            build: "npm run build",
+            browser: (target) => (browserFlags(target) ? `node dist/cli.js install${browserFlags(target)}` : "npm run setup"),
+        }
+        : {
+            setup: "npx -y scenescout install",
+            build: "npx -y scenescout@latest install   (the installed package is incomplete; fetch it again)",
+            browser: (target) => `npx -y scenescout install${browserFlags(target)}`,
+        };
 }
 /** Everything a working setup needs, each with the command that repairs it. */
 export function diagnose(opts) {
@@ -262,12 +356,12 @@ export function diagnose(opts) {
     checks.push({ name: "node >= 20", ok: major >= 20, detail: opts.nodeVersion, fix: "install Node 20 or newer" });
     const server = path.join(opts.packageRoot, "dist", "mcp-server.js");
     checks.push({ name: "engine built", ok: fs.existsSync(server), detail: server, fix: repair.build });
-    const chromiumOk = !!opts.chromiumPath && fs.existsSync(opts.chromiumPath);
+    const browser = opts.defaultBrowser;
     checks.push({
-        name: "chromium downloaded",
-        ok: chromiumOk,
-        detail: opts.chromiumPath ?? "playwright could not name a browser path",
-        fix: `${repair.setup}   (or: npx playwright install chromium)`,
+        name: `browser downloaded (${browser.target})`,
+        ok: browser.path !== null,
+        detail: browser.path ?? (browser.expected ? `not found at ${browser.expected}` : "playwright could not name a browser path"),
+        fix: `${repair.browser(browser.target)}   (or: npx playwright install ${browser.target})`,
     });
     if (opts.scope === "engine")
         return checks;

package/dist/mcp-server.js

@@ -21,19 +21,25 @@
  * - 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";
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { BrowserEngine } from "./engine/browser.js";
 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";
 /** Live sessions: each name owns an independent BrowserEngine (browser + auth). */
 const engines = new Map();
@@ -71,7 +77,8 @@ const PKG_VERSION = (() => {
         return "0.0.0";
     }
 })();
-const server = new McpServer({ name: "scenescout", version: PKG_VERSION });
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const server = new McpServer({ name: "scenescout", version: PKG_VERSION }, { instructions: SERVER_INSTRUCTIONS });
 function text(t, session) {
     const eng = engines.get(session);
     const prefix = engines.size > 1 ? `[session ${session}${eng ? ` · ${eng.role}` : ""}]\n` : "";
@@ -83,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) {
@@ -129,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
@@ -167,6 +312,48 @@ const sessionParam = z
     .max(40)
     .optional()
     .describe("Target this session directly instead of the active one — pass it explicitly when dispatching to MULTIPLE sessions in one turn (e.g. two scout_click calls with different `session`), which then run CONCURRENTLY rather than queueing. Omit for single-session sequential use.");
+// The method, for every client that has no skill loader. It is read per call,
+// not cached: a source checkout's skill file can change under a running server.
+server.registerTool(PLAYBOOK_TOOL, {
+    description: "Return the SceneScout testing method: setup order, write modes, how to explore, what counts as done, how to report. " +
+        "Call this ONCE before the first scout_attach in a conversation, then follow it. " +
+        "If this client offers a SceneScout skill, load that instead — it is the same text, so never read both. Takes no input and touches no browser.",
+    // No inputSchema on purpose: with one, a call that carries no `arguments` field is rejected as invalid.
+}, async () => {
+    try {
+        return { content: [{ type: "text", text: loadPlaybook(PACKAGE_ROOT) }] };
+    }
+    catch (err) {
+        return errorText(err);
+    }
+});
+// The same method as a prompt, for clients that list server prompts as commands.
+// Registered on the protocol server directly: the SDK's prompt helper rejects a
+// request that carries no `arguments` object, which is exactly what a client
+// sends when the person typed none, and every argument here is optional.
+server.server.registerCapabilities({ prompts: {} });
+server.server.setRequestHandler(ListPromptsRequestSchema, () => ({
+    prompts: [
+        {
+            name: PLAYBOOK_PROMPT,
+            title: "Explore a web app with SceneScout",
+            description: "Start an exploratory test session: loads the SceneScout method and states the target.",
+            arguments: EXPLORE_PROMPT_ARGUMENTS,
+        },
+    ],
+}));
+server.server.setRequestHandler(GetPromptRequestSchema, (request) => {
+    if (request.params.name !== PLAYBOOK_PROMPT)
+        throw new McpError(ErrorCode.InvalidParams, `Unknown prompt: ${request.params.name}`);
+    let message;
+    try {
+        message = explorePrompt(loadPlaybook(PACKAGE_ROOT), request.params.arguments);
+    }
+    catch (err) {
+        throw new McpError(ErrorCode.InvalidParams, err instanceof Error ? err.message : String(err));
+    }
+    return { messages: [{ role: "user", content: { type: "text", text: message } }] };
+});
 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") },
@@ -179,7 +366,7 @@ server.registerTool("scout_scan", {
     }
 }));
 server.registerTool("scout_attach", {
-    description: "Launch a browser and attach to a running web app. Write policy is enforced at the NETWORK layer: mode='observe' blocks EVERY request that is not a GET (login and token refresh excepted) — choose it for a target that holds real data, where even an ordinary form submission would create a record; mode='read-only' (default) blocks destructive-labeled elements AND all PUT/PATCH/DELETE + destructive POSTs, but lets ordinary form POSTs through; mode='safe-write' allows creating data and permits updates/deletes ONLY on resources this session created (use when the user wants create/edit flows tested); mode='destructive' allows everything — ONLY when the user explicitly confirmed a disposable/seeded environment. Pass a Playwright storage-state JSON to explore as an authenticated role. Pass `session` to keep MULTIPLE roles alive at once (one browser each, genuinely concurrent) for collaboration testing — target each directly with every tool's `session` param, or use scout_session to set which one is the default; coverage and findings merge into one project memory.",
+    description: "Launch a browser and attach to a running web app. First attach in this conversation and you have read neither the SceneScout skill nor scout_playbook? Call scout_playbook before this. Write policy is enforced at the NETWORK layer: mode='observe' blocks EVERY request that is not a GET (login and token refresh excepted) — choose it for a target that holds real data, where even an ordinary form submission would create a record; mode='read-only' (default) blocks destructive-labeled elements AND all PUT/PATCH/DELETE + destructive POSTs, but lets ordinary form POSTs through; mode='safe-write' allows creating data and permits updates/deletes ONLY on resources this session created (use when the user wants create/edit flows tested); mode='destructive' allows everything — ONLY when the user explicitly confirmed a disposable/seeded environment. Pass a Playwright storage-state JSON to explore as an authenticated role. Pass `session` to keep MULTIPLE roles alive at once (one browser each, genuinely concurrent) for collaboration testing — target each directly with every tool's `session` param, or use scout_session to set which one is the default; coverage and findings merge into one project memory.",
     inputSchema: {
         url: z.string().describe("Base URL of the running app, e.g. http://localhost:3000"),
         projectPath: z.string().describe("Absolute path to the project (memory + report live in .scenescout/ here)"),
@@ -189,15 +376,24 @@ server.registerTool("scout_attach", {
             .default("read-only")
             .describe("Write policy (see tool description). Never choose 'destructive' yourself — user opt-in only."),
         headed: z.boolean().default(false).describe("Show the browser window"),
+        browser: z
+            .enum(["chromium", "firefox", "webkit"])
+            .optional()
+            .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, viewportWidth, viewportHeight, session, }) => {
+}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, browser, viewportWidth, viewportHeight, task, session, }) => {
     try {
         const target = session ?? activeName;
         if (session) {
@@ -258,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, 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);
@@ -286,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);
         }
@@ -769,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/.` +
@@ -795,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/dist/playbook.js

@@ -0,0 +1,83 @@
+/**
+ * The testing method, served by the MCP server itself.
+ *
+ * The method lives in skills/scenescout/SKILL.md. Claude Code loads that file
+ * as a skill; no other client does, so an agent there gets the tools and none
+ * of the method: the setup order, the write modes, what counts as done. The
+ * server hands the same text to any client through a tool, a prompt and a short
+ * pointer in its instructions. One file, so the two can never disagree.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const PLAYBOOK_TOOL = "scout_playbook";
+export const PLAYBOOK_PROMPT = "explore";
+/** Where the method is kept, relative to the package root. It is in the package's `files`. */
+export const PLAYBOOK_RELATIVE_PATH = path.join("skills", "scenescout", "SKILL.md");
+/**
+ * Sent to every client when it connects. Short on purpose: clients cut long
+ * instructions, and one that is cut in the middle is worse than a pointer.
+ */
+export const SERVER_INSTRUCTIONS = `SceneScout explores a running web app in a real browser and reports bugs, UX problems and coverage. ` +
+    `The scout_* tools are deterministic; the method for using them well is a separate text. ` +
+    `If this client offers a SceneScout skill, load that. Otherwise call ${PLAYBOOK_TOOL} once, before the first scout_attach in a conversation, and follow what it returns. ` +
+    `They are the same text, so never read both. ` +
+    `Never choose mode="destructive" yourself: that needs the user's explicit opt-in.`;
+export const LEVELS = ["minimal", "medium", "extensive"];
+/** What the `explore` prompt accepts, as MCP lists it. Every argument is optional. */
+export const EXPLORE_PROMPT_ARGUMENTS = [
+    { name: "url", description: "URL of the running app, e.g. http://localhost:3000", required: false },
+    { name: "level", description: `How far to go: ${LEVELS.join(", ")}`, required: false },
+    { name: "focus", description: "An area or flow to concentrate on", required: false },
+];
+/** The skill file without its YAML front matter, which only a skill loader reads. */
+export function stripFrontMatter(markdown) {
+    // An editor may save the file with a byte-order mark; it would hide the opening fence.
+    const text = markdown.replace(/^\uFEFF/, "");
+    // The fences may hold nothing between them, and the closing one may be the last line of the file.
+    const m = /^---[ \t]*\r?\n(?:[\s\S]*?\r?\n)?---[ \t]*(?:\r?\n|$)/.exec(text);
+    // Leading blank LINES go; indentation on the first line of the body stays.
+    return (m ? text.slice(m[0].length) : text).replace(/^(?:[ \t]*\r?\n)+/, "");
+}
+/**
+ * The method text. Throws when the file is not where the package puts it: an
+ * agent told "here is the method" and handed an empty string would proceed
+ * without one and never say so.
+ */
+export function loadPlaybook(packageRoot) {
+    const file = path.join(packageRoot, PLAYBOOK_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        throw new Error(`The SceneScout playbook is missing from this install (${file}): ${err instanceof Error ? err.message : String(err)}. Reinstall the package.`);
+    }
+    const body = stripFrontMatter(raw);
+    if (body.trim().length === 0)
+        throw new Error(`The SceneScout playbook at ${file} is empty. Reinstall the package.`);
+    // Front matter that was not recognised would be served to the agent as if it were the method.
+    if (/^---[ \t]*(\r?\n|$)/.test(body))
+        throw new Error(`The SceneScout playbook at ${file} has front matter that could not be read. Reinstall the package.`);
+    return body;
+}
+/**
+ * The opening message of the `explore` prompt: the method, then what the person
+ * asked for. `args` is whatever the client sent, which may be nothing at all.
+ * A level the method does not know is refused, not passed on for the agent to guess at.
+ */
+export function explorePrompt(playbook, args) {
+    const given = (name) => {
+        const v = args?.[name];
+        return typeof v === "string" && v.trim() ? v.trim() : undefined;
+    };
+    const level = given("level");
+    if (level !== undefined && !LEVELS.includes(level)) {
+        throw new Error(`level "${level}" is not one the method knows. Use one of: ${LEVELS.join(", ")}.`);
+    }
+    const asks = [
+        given("url") ? `Target: ${given("url")}` : "Target: ask me for the URL of the running app, or find it from the project.",
+        level ? `Level: ${level}` : "",
+        given("focus") ? `Focus: ${given("focus")}` : "",
+    ].filter(Boolean);
+    return `${playbook}\n\n---\n\nRun an exploratory test session following the method above.\n${asks.join("\n")}`;
+}