scenescout 3.16.0 → 3.17.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # scenescout
 
+## 3.17.0
+
+### Minor Changes
+
+- b0709f0: `scenescout check` accepts `--ignore-path`: a path drops every rule filed on that route, and `rule:/path` drops that one rule there. A page meant to answer HTTP 500 can stay off the gate while the same status on another path still fails `--fail-on high`. The GitHub Action takes the same input.
+- 547d006: Add the `live` and `login` MCP prompts. `live` returns the current session's loopback live-view URL. `login` takes a role and tells the agent to call `scout_login`, with no password argument.
+- 7ba8712: Add `scout_status`, a run-status pane built as an MCP App (`io.modelcontextprotocol/ui`, specification 2026-01-26). In a client that renders MCP Apps it shows each session's objective and task, open findings by severity, coverage and a button for the live view, and refreshes itself every 2.5 seconds through the app-only `scout_status_poll` tool. Every other client gets the same as text, starting with the live view's loopback address. The pane's page loads nothing from outside and shows only what the live view already shows.
+
+### Patch Changes
+
+- 745a38e: On Windows, `scenescout install --client` starts an npm-installed client (a `.cmd` or `.bat` shim) through `cmd.exe`, so registration runs the client's own command instead of stopping and printing it to run by hand.
+
 ## 3.16.0
 
 ### Minor Changes

package/README.md

@@ -229,7 +229,7 @@ Before a parallel run, `scout_lane_brief` checks that the planner's saved login
 
 ## 📺 Watching a run live
 
-When a session attaches, the engine starts a small live view and hands the agent its address on a `Live view:` line, which the agent passes on to you. On a desktop the engine also opens it in your default browser, and opens the report when it is written; nothing opens in CI or over SSH, and `SCENESCOUT_OPEN=none` (or `live`, `report`, `both`) chooses otherwise. From a terminal, `scenescout watch` opens the same page. There is one card per session:
+When a session attaches, the engine starts a small live view and hands the agent its address on a `Live view:` line, which the agent passes on to you. On a local desktop it also opens that page in your default browser as the session attaches, and opens `report.html` when `scout_report` writes it, whether or not the browser window is shown. Nothing opens in CI, over SSH, or on Linux with no display. `SCENESCOUT_OPEN` (`live`, `report`, `both` or `none`) in the server's environment chooses otherwise, and `scout_attach {open}` wins over it. `scenescout ci` opens nothing unless `SCENESCOUT_OPEN` is set. From a terminal, `scenescout watch` opens the same page. There is one card per session:
 
 <p align="center"><img src="examples/screenshots/live-view.png" alt="The live view during a run of three parallel agents against the demo app: one card per session, each with its role and objective, the task it is on, the tool it is running, the page it is on, a live thumbnail, and a feed of the actions it just took, tinted one colour per task" width="880" /></p>
 
@@ -378,7 +378,7 @@ That refusal *is* the guarantee: an extensive report can only exist when nothing
 - 🟢 **`read-only` by default.** Destructive-labeled elements (delete/revoke/archive/…) **and** all `PUT/PATCH/DELETE` + destructive `POST`s are blocked at the network layer — see [`src/engine/policy.ts`](src/engine/policy.ts). Non-destructive `POST`s are allowed, because submitting forms is how a tester finds validation bugs — so read-only means *nothing existing is changed or removed*, not *nothing is ever created*.
 - 🟡 **`safe-write`** (`--safe-write`) lets the agent create data and edit/delete **only what it created** this run — never pre-existing records.
 - 🔴 **`destructive`** (`--allow-destructive`) allows everything, and only ever when *you* confirm the environment is disposable. The skill will never choose this itself.
-- 📂 Findings, memory, and reports live in a `.scenescout/` folder where you ran it. It ignores itself in git, so a stray `git add -A` never commits test data.
+- 📂 Findings, memory, and reports live in a `.scenescout/` folder in the project. A client with no project folder, such as a desktop chat, gets one folder per tested site under `Documents/SceneScout/<host>/` by default, and the attach says where; `SCENESCOUT_PROJECTS_DIR` moves it. The folder ignores itself in git, so a stray `git add -A` never commits test data.
 
 A `🛡 WRITE-POLICY blocked` notice is the safety net doing its job, not an app bug. The server never sees a blocked request, but a page's own `fetch` or XHR is answered with a `403` in its place rather than dropped, so the page's handling of a refusal really runs: a page that then claims success is reported as a `false_success` ([ADR 9](docs/adr/0009-a-refused-write-is-answered-not-dropped.md)).
 
@@ -388,6 +388,8 @@ A control is judged by its own label: a dropdown by the option picked, a row by
 
 ## 📋 What you get
 
+`.scenescout/report.md` and `report.html` open **In plain words**: a short summary, then each problem this run found, worst first, with its impact, the steps that led to it, what was expected, what happened and a picture when there is one. The technical detail (id, category, evidence, route) stays one click away.
+
 `.scenescout/report.md` — a deduplicated, worst-first report with:
 
 - 🐛 **Findings** with repro traces and generated Playwright regression-test skeletons.
@@ -398,9 +400,9 @@ A control is judged by its own label: a dropdown by the option picked, a row by
 - ⏱️ **How the run was paced** — how closely each session kept working, and apart from that, how long finished lanes held their browsers waiting to be collected, so neither hides the other.
 - 🎯 **How well the lanes judged** — on a parallel run, whether the confidence each lane stated matched what the project went on to file, beside what later re-tests found ([ADR 10](docs/adr/0010-a-confidence-is-checked-not-trusted.md)).
 
-`.scenescout/report.html` — the same report as one self-contained page, with every session's trail beside it, and on a [recorded run](#-recording-a-run-and-reading-it-back) the screenshots under each finding.
+`.scenescout/report.html` — the same report as one self-contained page, with every session's trail beside it. Each finding shows a picture of the element it is about, or of the page as it was. A [recorded run](#-recording-a-run-and-reading-it-back) also shows the screenshots around each finding.
 
-👀 Watch a run live: `node dist/cli.js status <project-path>`.
+👀 Watch a run live: `npx scenescout watch`, or `npx scenescout status <project-path>` for the same information as text.
 
 ---
 
@@ -787,6 +789,7 @@ The load-bearing choices are recorded as ADRs — read the relevant one before c
 - [11 · A gate is deterministic, and fails only on what it can prove](docs/adr/0011-a-gate-is-deterministic-and-fails-only-on-what-it-can-prove.md)
 - [12 · A check replays saved flows and re-tests open findings, within settings whose defaults do the least harm](docs/adr/0012-a-check-replays-saved-flows-and-reports-re-tests.md)
 - [13 · What depends on a project's convention is the project's to decide](docs/adr/0013-a-convention-is-the-projects-to-decide.md)
+- [21 · Update the docs in the same pull request, unless the change has no user-facing surface](docs/adr/0021-update-the-docs-in-the-pull-request.md)
 
 ---
 

package/dist/check-run.js

@@ -175,7 +175,7 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
         const measured = redactRoutes(routes.map(withoutOwnResponse));
         const flows = redactFlowRuns(flowRuns);
         const pictured = baselines ? redactBaselineRun(baselines) : null;
-        const { issues, worthALook } = checkFindings(measured, start.origin, options.ignore, flows, pictured);
+        const { issues, worthALook } = checkFindings(measured, start.origin, options.ignore, flows, pictured, options.ignorePaths);
         return {
             url: redactRoute(options.url),
             generatedAt: new Date().toISOString(),
@@ -188,6 +188,7 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
             unvisited: options.paths ? [] : engine.crawlableRoutes().map(redactRoute),
             ...(options.timeBudgetMs !== undefined ? { timeBudget: { ms: options.timeBudgetMs, reached: timeLimitReached } } : {}),
             ignored: options.ignore,
+            ignoredPaths: options.ignorePaths,
             flows,
             skippedFlows: inputs.skippedFlows ?? [],
             retest,

package/dist/cli.js

@@ -78,7 +78,8 @@ Usage:
                                     so it can gate a pull request. Writes report.md, check.sarif and check.json.
                                     (--fail-on high|medium|low|never (default high); --mode observe|read-only;
                                      --max-routes N (default 50); --paths /a,/b to check only those;
-                                     --ignore rule,rule; --storage-state file to check signed in;
+                                     --ignore rule,rule; --ignore-path /a,rule:/b to exempt a path, or one rule on it;
+                                     --storage-state file to check signed in;
                                      --project dir (default: here); --out dir (default: .scenescout/check);
                                      --browser chromium|firefox|webkit;
                                      --action-timeout-ms N (default 5000), --nav-timeout-ms N (default 20000;
@@ -482,10 +483,8 @@ async function install(flags) {
             }
             else {
                 failed = true;
-                // On Windows a client installed through npm is a .cmd shim, which node cannot start directly.
-                const windowsNote = process.platform === "win32" ? " (or it is installed as a .cmd shim, which cannot be started from here)" : "";
                 console.log(reg.status === "client-missing"
-                    ? `· ${label} was not found on this machine${windowsNote}, so nothing was registered with it.`
+                    ? `· ${label} was not found on this machine, so nothing was registered with it.`
                     : `✗ Registering with ${label} failed: ${reg.detail}`);
                 console.log(`  To do it by hand, ${reg.manual}\n`);
             }

package/dist/engine/check.js

@@ -210,14 +210,20 @@ export function geometryRule(line) {
  * dedup, and their fingerprint comes from the target, not the evidence: the
  * evidence carries this run's percentage, and the same target changing by a
  * different amount is still the same alert.
+ *
+ * `--ignore-path` drops a fact on the route it names, or one rule there,
+ * before the fact is filed. A fact also seen on a route that is not exempted
+ * stays, on that route alone.
  */
-export function checkFindings(routes, origin, ignore = [], flows = [], baselines = null) {
+export function checkFindings(routes, origin, ignore = [], flows = [], baselines = null, ignorePaths = []) {
     const byKey = new Map();
     const looks = new Map();
+    /** A route (and, when named, one rule on it) that --ignore-path exempts. */
+    const exempt = (rule, route) => ignorePaths.some((e) => e.path === route && (e.rule === undefined || e.rule === rule));
     /** Evidence as it is written: no origin, no secret, and bounded. */
     const cleanEvidence = (evidence) => redactSecrets(withoutOrigin(evidence, origin)).slice(0, 300);
     const add = (rule, evidence, route, opts = {}) => {
-        if (ignore.includes(rule))
+        if (ignore.includes(rule) || exempt(rule, route))
             return;
         const clean = cleanEvidence(evidence);
         const key = `${rule}\u0000${clean}`;
@@ -287,6 +293,8 @@ export function checkFindings(routes, origin, ignore = [], flows = [], baselines
     const visual = [];
     if (baselines && !ignore.includes(VISUAL_RULE)) {
         for (const r of baselines.results) {
+            if (exempt(VISUAL_RULE, r.path))
+                continue;
             const evidence = baselineEvidence(r, baselines);
             if (evidence === null)
                 continue;
@@ -305,8 +313,8 @@ export function checkFindings(routes, origin, ignore = [], flows = [], baselines
     };
 }
 /** The defect tier of `checkFindings`: what counts, and what the gate reads. */
-export function issuesFromRoutes(routes, origin, ignore = [], flows = []) {
-    return checkFindings(routes, origin, ignore, flows).issues;
+export function issuesFromRoutes(routes, origin, ignore = [], flows = [], ignorePaths = []) {
+    return checkFindings(routes, origin, ignore, flows, null, ignorePaths).issues;
 }
 /**
  * Why a check has nothing to give a verdict on, or null when it measured the
@@ -413,6 +421,7 @@ export const CHECK_OPTION_NAMES = [
     "max-routes",
     "paths",
     "ignore",
+    "ignore-path",
     "flows",
     "retest",
     "flow-writes",
@@ -507,6 +516,50 @@ export function parseCheckArgs(args, cwd) {
     const unknownRules = ignore.filter((r) => !CHECK_RULE_IDS.includes(r));
     if (unknownRules.length > 0)
         return { ok: false, error: `unknown rule(s) in --ignore: ${unknownRules.join(", ")}. Rules: ${CHECK_RULE_IDS.join(", ")}` };
+    const ignorePathList = list(flags.get("ignore-path"));
+    if (ignorePathList && ignorePathList.length === 0)
+        return { ok: false, error: "--ignore-path is empty" };
+    const ignorePaths = [];
+    const unknownPathRules = [];
+    const badPathEntries = [];
+    const ruleAfterPath = [];
+    for (const entry of ignorePathList ?? []) {
+        if (entry.startsWith("/")) {
+            // `/path:rule` would otherwise be a path that never matches. A colon is
+            // still allowed in a path when what follows it is not a rule id.
+            const suffix = entry.slice(entry.lastIndexOf(":") + 1);
+            if (entry.includes(":") && CHECK_RULE_IDS.includes(suffix)) {
+                ruleAfterPath.push(entry);
+                continue;
+            }
+            ignorePaths.push({ path: entry });
+            continue;
+        }
+        const colon = entry.indexOf(":");
+        const rule = colon > 0 ? entry.slice(0, colon) : "";
+        const path = colon > 0 ? entry.slice(colon + 1) : "";
+        if (path.startsWith("/") && CHECK_RULE_IDS.includes(rule)) {
+            ignorePaths.push({ path, rule: rule });
+            continue;
+        }
+        if (path.startsWith("/") && rule) {
+            unknownPathRules.push(rule);
+            continue;
+        }
+        badPathEntries.push(entry);
+    }
+    if (unknownPathRules.length > 0) {
+        return { ok: false, error: `unknown rule(s) in --ignore-path: ${unknownPathRules.join(", ")}. Rules: ${CHECK_RULE_IDS.join(", ")}` };
+    }
+    if (ruleAfterPath.length > 0) {
+        return { ok: false, error: `--ignore-path names a rule as rule:/path (got ${ruleAfterPath.join(", ")})` };
+    }
+    if (badPathEntries.length > 0) {
+        return {
+            ok: false,
+            error: `--ignore-path entries are paths starting with /, or one rule on a path as rule:/path (got ${badPathEntries.join(", ")})`,
+        };
+    }
     const retest = flags.get("retest") ?? "on";
     if (retest !== "on" && retest !== "off")
         return { ok: false, error: "--retest must be on or off" };
@@ -558,6 +611,7 @@ export function parseCheckArgs(args, cwd) {
             maxRoutes,
             ...(paths ? { paths } : {}),
             ignore: ignore,
+            ignorePaths,
             ...(flows !== undefined ? { flows: flows === "off" ? "off" : resolve(flows) } : {}),
             retest: retest === "on",
             flowWrites,
@@ -940,6 +994,10 @@ export function formatCheck(result) {
     }
     if (result.ignored.length > 0)
         lines.push("", `Rules ignored by --ignore: ${result.ignored.join(", ")}`);
+    if (result.ignoredPaths.length > 0) {
+        const shown = result.ignoredPaths.map((e) => (e.rule ? `${e.rule}:${e.path}` : e.path));
+        lines.push("", `Paths exempted by --ignore-path: ${shown.join(", ")}`);
+    }
     lines.push("", result.flows.length > 0
         ? "_A check visits pages, measures what loads and replays the flows saved for it. It does not explore, fill forms of its own accord or compare roles; an exploratory run does that._"
         : "_A check visits pages and measures what loads. It does not fill forms, click through flows or compare roles; an exploratory run does that. Flows saved in .scenescout/flows are replayed._");
@@ -968,6 +1026,7 @@ export function toSummaryJson(result, toolVersion) {
         unvisited: result.unvisited,
         ...(result.timeBudget ? { timeBudget: result.timeBudget } : {}),
         ignored: result.ignored,
+        ignoredPaths: result.ignoredPaths,
         flows: result.flows.map((f) => ({
             name: f.name,
             file: f.file,

package/dist/engine/status-pane-page.js

@@ -0,0 +1,441 @@
+/**
+ * The run-status pane's page: the `ui://` resource an MCP Apps host renders
+ * in a sandboxed iframe (SEP-1865, specification 2026-01-26).
+ *
+ * It speaks the extension's JSON-RPC over postMessage itself rather than
+ * bundling the ext-apps SDK, so it is one string with no external asset and
+ * the resource declares no outside origin: the host's restrictive default CSP
+ * applies. The handshake is the one the SDK's App.connect sends:
+ * `ui/initialize` with appInfo, appCapabilities and protocolVersion, then
+ * `ui/notifications/initialized`. Data comes from `tools/call` on the app-only
+ * poll tool every STATUS_POLL_MS, as the system-monitor example polls its own.
+ *
+ * Everything shown is untrusted (session names, tasks and objectives come from
+ * the agent, URLs from the app under test), so the script sets text with
+ * textContent and never builds markup from data. It accepts messages only from
+ * its parent window. Like live-page.ts, the client script avoids template
+ * literals because the page is one; status-pane tests check the script parses.
+ */
+import { MCP_APPS_PROTOCOL, STATUS_POLL_MS, STATUS_POLL_TOOL } from "./status-pane.js";
+export function statusPanePage(version) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<title>SceneScout run</title>
+<style>
+  /* The host may set any of these (the spec's standard variables); each has a default for one that does not. */
+  :root {
+    color-scheme: light dark;
+    --color-background-primary: light-dark(#ffffff, #171a1f);
+    --color-background-secondary: light-dark(#f5f6f8, #1f232a);
+    --color-text-primary: light-dark(#15181d, #e8ebef);
+    --color-text-secondary: light-dark(#5b6472, #9aa3b1);
+    --color-text-danger: light-dark(#b42318, #ff8a80);
+    --color-text-warning: light-dark(#9a5b00, #f5c065);
+    --color-text-info: light-dark(#1f5fbf, #8ab4ff);
+    --color-text-success: light-dark(#18794e, #6fd3a2);
+    --color-border-primary: light-dark(#d8dce2, #343a44);
+    --color-ring-primary: light-dark(#2563eb, #7aa2ff);
+    --font-sans: system-ui, -apple-system, "Segoe UI", sans-serif;
+    --font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+    --font-text-sm-size: 13px;
+    --font-text-md-size: 14px;
+    --border-radius-sm: 6px;
+    --border-radius-md: 8px;
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; }
+  body {
+    background: var(--color-background-primary); color: var(--color-text-primary);
+    font: var(--font-text-md-size)/1.45 var(--font-sans);
+    overflow-wrap: anywhere;
+  }
+  main { padding: 12px; display: grid; gap: 12px; max-width: 760px; }
+  header { display: flex; flex-wrap: wrap; align-items: center; gap: 8px 12px; }
+  h1 { margin: 0; font-size: 15px; font-weight: 650; flex: 1 1 auto; }
+  h2 { margin: 0 0 6px; font-size: var(--font-text-sm-size); font-weight: 600; color: var(--color-text-secondary); text-transform: uppercase; letter-spacing: .04em; }
+  .status { display: inline-flex; align-items: center; gap: 6px; color: var(--color-text-secondary); font-size: var(--font-text-sm-size); font-variant-numeric: tabular-nums; }
+  .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--color-text-secondary); flex: none; }
+  .dot.on { background: var(--color-text-success); }
+  .dot.err { background: var(--color-text-danger); }
+  .actions { display: flex; flex-wrap: wrap; gap: 6px; }
+  button {
+    font: inherit; font-size: var(--font-text-sm-size); color: var(--color-text-primary);
+    background: var(--color-background-secondary); border: 1px solid var(--color-border-primary);
+    border-radius: var(--border-radius-sm); padding: 4px 10px; cursor: pointer;
+  }
+  button:hover { border-color: var(--color-ring-primary); }
+  button:focus-visible { outline: 2px solid var(--color-ring-primary); outline-offset: 1px; }
+  button[disabled] { opacity: .55; cursor: default; }
+  .live { display: grid; gap: 4px; }
+  .url { font: 12px/1.4 var(--font-mono); color: var(--color-text-secondary); user-select: all; }
+  .note { margin: 0; color: var(--color-text-secondary); font-size: var(--font-text-sm-size); }
+  section { background: var(--color-background-secondary); border: 1px solid var(--color-border-primary); border-radius: var(--border-radius-md); padding: 10px 12px; }
+  .tiles { display: grid; grid-template-columns: repeat(auto-fit, minmax(60px, 1fr)); gap: 8px; }
+  .tile { display: grid; gap: 2px; }
+  .tile b { font-size: 22px; font-weight: 650; font-variant-numeric: tabular-nums; line-height: 1.1; }
+  .tile span { font-size: var(--font-text-sm-size); color: var(--color-text-secondary); }
+  .tile.high b { color: var(--color-text-danger); }
+  .tile.medium b { color: var(--color-text-warning); }
+  .tile.low b { color: var(--color-text-info); }
+  .sub { margin: 8px 0 0; font-size: var(--font-text-sm-size); color: var(--color-text-secondary); }
+  .bar { height: 6px; border-radius: 3px; background: var(--color-border-primary); overflow: hidden; margin: 4px 0 6px; }
+  .bar i { display: block; height: 100%; background: var(--color-ring-primary); width: 0; }
+  ul.sessions { list-style: none; margin: 0; padding: 0; display: grid; gap: 8px; }
+  ul.sessions li { display: grid; gap: 2px; padding-top: 8px; border-top: 1px solid var(--color-border-primary); }
+  ul.sessions li:first-child { border-top: 0; padding-top: 0; }
+  .who { display: flex; flex-wrap: wrap; gap: 4px 8px; align-items: baseline; }
+  .who strong { font-weight: 600; }
+  .state { font-size: 12px; padding: 0 6px; border-radius: 999px; border: 1px solid currentColor; }
+  .state.running { color: var(--color-text-warning); }
+  .state.idle { color: var(--color-text-secondary); }
+  .state.stuck { color: var(--color-text-danger); }
+  .line { font-size: var(--font-text-sm-size); color: var(--color-text-secondary); }
+  .line em { font-style: normal; color: var(--color-text-primary); }
+  .page { font: 12px/1.4 var(--font-mono); color: var(--color-text-secondary); }
+  [hidden] { display: none !important; }
+</style>
+</head>
+<body>
+<main id="main" data-testid="status-pane">
+  <header>
+    <h1>SceneScout run</h1>
+    <span class="status" role="status" aria-live="polite"><span id="dot" class="dot"></span><span id="status-text" data-testid="status-pane-updated">Connecting…</span></span>
+    <div class="actions">
+      <button type="button" id="open-live" data-testid="status-pane-live-open" disabled>Open live view</button>
+      <button type="button" id="toggle" data-testid="status-pane-poll-toggle" aria-pressed="false">Pause</button>
+    </div>
+  </header>
+  <div class="live">
+    <code id="live-url" class="url" data-testid="status-pane-live-url" hidden></code>
+    <p id="live-note" class="note" data-testid="status-pane-live-note" hidden></p>
+  </div>
+  <section aria-labelledby="findings-h" data-testid="status-pane-findings">
+    <h2 id="findings-h">Open findings</h2>
+    <div class="tiles">
+      <div class="tile high"><b id="f-high">–</b><span>high</span></div>
+      <div class="tile medium"><b id="f-medium">–</b><span>medium</span></div>
+      <div class="tile low"><b id="f-low">–</b><span>low</span></div>
+      <div class="tile"><b id="f-open">–</b><span>open</span></div>
+    </div>
+    <p id="f-sub" class="sub">No session has attached yet.</p>
+  </section>
+  <section aria-labelledby="coverage-h" data-testid="status-pane-coverage">
+    <h2 id="coverage-h">Coverage</h2>
+    <div id="routes" hidden>
+      <div class="line">Routes <em id="c-routes"></em></div>
+      <div class="bar" role="img" id="c-bar-wrap"><i id="c-bar"></i></div>
+    </div>
+    <div id="c-line" class="line">Nothing measured yet.</div>
+  </section>
+  <section aria-labelledby="sessions-h" data-testid="status-pane-sessions">
+    <h2 id="sessions-h">Sessions</h2>
+    <ul id="sessions" class="sessions"></ul>
+    <p id="no-sessions" class="note">No session is attached.</p>
+  </section>
+</main>
+<script>
+(function () {
+  "use strict";
+  var POLL_TOOL = ${JSON.stringify(STATUS_POLL_TOOL)};
+  var POLL_MS = ${STATUS_POLL_MS};
+  var PROTOCOL = ${JSON.stringify(MCP_APPS_PROTOCOL)};
+  var VERSION = ${JSON.stringify(version)};
+  var REQUEST_MS = 10000;
+
+  var nextId = 1;
+  var pending = {};
+  var connected = false;
+  var paused = false;
+  var timer = null;
+  var inFlight = false;
+  var liveUrl = null;
+  var canOpenLinks = false;
+  var openHint = "";
+  var observer = null;
+
+  function el(id) { return document.getElementById(id); }
+
+  // The view cannot know its host's origin, so it posts to its parent with "*",
+  // as the spec's own example and the SDK's transport do. Only the parent can
+  // receive it, and every message the view sends carries data the host gave it.
+  function post(message) { window.parent.postMessage(message, "*"); }
+
+  function request(method, params) {
+    var id = nextId++;
+    return new Promise(function (resolve, reject) {
+      var timeout = setTimeout(function () {
+        delete pending[id];
+        reject(new Error(method + " got no answer"));
+      }, REQUEST_MS);
+      pending[id] = { resolve: resolve, reject: reject, timeout: timeout };
+      post({ jsonrpc: "2.0", id: id, method: method, params: params });
+    });
+  }
+
+  function notify(method, params) {
+    var message = { jsonrpc: "2.0", method: method };
+    if (params !== undefined) message.params = params;
+    post(message);
+  }
+
+  function reply(id, result) { post({ jsonrpc: "2.0", id: id, result: result }); }
+
+  window.addEventListener("message", function (event) {
+    if (event.source !== window.parent || window.parent === window) return;
+    var m = event.data;
+    if (!m || m.jsonrpc !== "2.0") return;
+    if (m.method === undefined && m.id !== undefined && m.id !== null) {
+      var waiting = pending[m.id];
+      if (!waiting) return;
+      delete pending[m.id];
+      clearTimeout(waiting.timeout);
+      if (m.error) waiting.reject(new Error(m.error.message || "request failed"));
+      else waiting.resolve(m.result);
+      return;
+    }
+    if (typeof m.method !== "string") return;
+    if (m.id !== undefined && m.id !== null) {
+      if (m.method === "ui/resource-teardown") { tearDown(); reply(m.id, {}); return; }
+      if (m.method === "ping") { reply(m.id, {}); return; }
+      post({ jsonrpc: "2.0", id: m.id, error: { code: -32601, message: "Method not found" } });
+      return;
+    }
+    if (m.method === "ui/notifications/tool-result") {
+      var data = m.params && m.params.structuredContent;
+      if (data && typeof data === "object") render(data);
+    } else if (m.method === "ui/notifications/host-context-changed") {
+      applyContext(m.params || {});
+    }
+  });
+
+  function applyContext(ctx) {
+    var root = document.documentElement;
+    if (ctx.theme === "light" || ctx.theme === "dark") {
+      root.setAttribute("data-theme", ctx.theme);
+      root.style.colorScheme = ctx.theme;
+    }
+    var vars = ctx.styles && ctx.styles.variables;
+    if (vars && typeof vars === "object") {
+      Object.keys(vars).forEach(function (key) {
+        if (key.indexOf("--") === 0 && typeof vars[key] === "string") root.style.setProperty(key, vars[key]);
+      });
+    }
+    var inset = ctx.safeAreaInsets;
+    if (inset) {
+      var main = el("main");
+      main.style.paddingTop = (12 + (inset.top || 0)) + "px";
+      main.style.paddingRight = (12 + (inset.right || 0)) + "px";
+      main.style.paddingBottom = (12 + (inset.bottom || 0)) + "px";
+      main.style.paddingLeft = (12 + (inset.left || 0)) + "px";
+    }
+  }
+
+  // Report the content's size so a host with a flexible container can fit it, as the SDK's autoResize does.
+  function watchSize() {
+    var lastW = 0, lastH = 0, scheduled = false;
+    function send() {
+      if (scheduled) return;
+      scheduled = true;
+      requestAnimationFrame(function () {
+        scheduled = false;
+        var html = document.documentElement;
+        var before = html.style.height;
+        html.style.height = "max-content";
+        var h = Math.ceil(html.getBoundingClientRect().height);
+        html.style.height = before;
+        var w = Math.ceil(window.innerWidth);
+        if (w !== lastW || h !== lastH) {
+          lastW = w; lastH = h;
+          notify("ui/notifications/size-changed", { width: w, height: h });
+        }
+      });
+    }
+    send();
+    observer = new ResizeObserver(send);
+    observer.observe(document.documentElement);
+    observer.observe(document.body);
+  }
+
+  function setStatus(text, state) {
+    el("status-text").textContent = text;
+    el("dot").className = "dot" + (state ? " " + state : "");
+  }
+
+  function clock(iso) {
+    var d = new Date(iso);
+    if (isNaN(d.getTime())) return "";
+    return [d.getHours(), d.getMinutes(), d.getSeconds()].map(function (n) { return (n < 10 ? "0" : "") + n; }).join(":");
+  }
+
+  function duration(ms) {
+    var total = Math.max(0, Math.floor(ms / 1000));
+    if (total < 60) return total + "s";
+    var minutes = Math.floor(total / 60);
+    if (minutes < 60) return minutes + "m" + (total % 60 < 10 ? "0" : "") + (total % 60) + "s";
+    return Math.floor(minutes / 60) + "h" + (minutes % 60 < 10 ? "0" : "") + (minutes % 60) + "m";
+  }
+
+  function plural(n, word) { return n + " " + word + (n === 1 ? "" : "s"); }
+
+  function render(data) {
+    liveUrl = typeof data.liveUrl === "string" ? data.liveUrl : null;
+    el("live-url").textContent = liveUrl || "";
+    el("live-url").hidden = !liveUrl;
+    el("live-note").textContent = data.liveNote || (liveUrl ? openHint : "");
+    el("live-note").hidden = !el("live-note").textContent;
+    el("open-live").disabled = !liveUrl;
+
+    var f = data.findings;
+    ["high", "medium", "low", "open"].forEach(function (k) { el("f-" + k).textContent = f ? String(f[k]) : "–"; });
+    if (f) {
+      var parts = [f.thisRun + " filed this run"];
+      if (f.worthALook) parts.push(f.worthALook + " worth a look");
+      if (f.resolved) parts.push(f.resolved + " resolved");
+      el("f-sub").textContent = parts.join(" · ");
+    } else {
+      el("f-sub").textContent = "No session has attached yet.";
+    }
+
+    var c = data.coverage;
+    el("routes").hidden = !(c && c.routesTotal > 0);
+    if (c && c.routesTotal > 0) {
+      el("c-routes").textContent = c.routesVisited + " of " + c.routesTotal;
+      var pct = Math.round((100 * c.routesVisited) / c.routesTotal);
+      el("c-bar").style.width = Math.min(100, Math.max(0, pct)) + "%";
+      el("c-bar-wrap").setAttribute("aria-label", pct + "% of known routes visited");
+    }
+    el("c-line").textContent = c
+      ? plural(c.states, "state") + " explored · " + c.elementsExercised + " of " + c.elementsTotal + " elements exercised"
+      : "Nothing measured yet.";
+
+    var list = el("sessions");
+    while (list.firstChild) list.removeChild(list.firstChild);
+    var sessions = Array.isArray(data.sessions) ? data.sessions : [];
+    el("no-sessions").hidden = sessions.length > 0;
+    sessions.forEach(function (s) {
+      var li = document.createElement("li");
+      li.setAttribute("data-testid", "status-pane-session");
+      var who = document.createElement("div");
+      who.className = "who";
+      var name = document.createElement("strong");
+      name.textContent = s.session;
+      var role = document.createElement("span");
+      role.className = "line";
+      role.textContent = s.role;
+      var state = document.createElement("span");
+      state.className = "state " + (s.state === "running" || s.state === "stuck" ? s.state : "idle");
+      state.textContent = s.state === "idle" ? "idle " + duration(s.forMs) : s.state + " " + duration(s.forMs);
+      who.appendChild(name); who.appendChild(role); who.appendChild(state);
+      li.appendChild(who);
+      li.appendChild(labelled(s.state === "idle" ? "Last tool" : "Tool", s.tool));
+      if (s.task) li.appendChild(labelled("Task", s.task));
+      if (s.objective) li.appendChild(labelled("Objective", s.objective));
+      if (s.url) {
+        var page = document.createElement("div");
+        page.className = "page";
+        page.textContent = s.url;
+        li.appendChild(page);
+      }
+      list.appendChild(li);
+    });
+    if (data.at) setStatus(paused ? "Paused" : "Updated " + clock(data.at), paused ? "" : "on");
+  }
+
+  function labelled(label, value) {
+    var line = document.createElement("div");
+    line.className = "line";
+    line.appendChild(document.createTextNode(label + ": "));
+    var v = document.createElement("em");
+    v.textContent = value;
+    line.appendChild(v);
+    return line;
+  }
+
+  function poll() {
+    if (!connected || paused || inFlight || document.visibilityState === "hidden") return;
+    inFlight = true;
+    request("tools/call", { name: POLL_TOOL, arguments: {} })
+      .then(function (result) {
+        if (result && result.isError) throw new Error("the server could not report the run");
+        if (result && result.structuredContent) render(result.structuredContent);
+      })
+      .catch(function (err) {
+        if (paused) return;
+        setStatus("Could not update: " + (err && err.message ? err.message : String(err)), "err");
+      })
+      .then(function () { inFlight = false; });
+  }
+
+  function start() {
+    if (timer !== null) return;
+    poll();
+    timer = setInterval(poll, POLL_MS);
+  }
+
+  function stop() {
+    if (timer !== null) clearInterval(timer);
+    timer = null;
+  }
+
+  // The host is about to remove the view: stop everything, and never start again.
+  function tearDown() {
+    connected = false;
+    stop();
+    if (observer) observer.disconnect();
+    Object.keys(pending).forEach(function (id) { clearTimeout(pending[id].timeout); delete pending[id]; });
+  }
+
+  el("toggle").addEventListener("click", function () {
+    paused = !paused;
+    el("toggle").textContent = paused ? "Resume" : "Pause";
+    el("toggle").setAttribute("aria-pressed", paused ? "true" : "false");
+    if (paused) { stop(); setStatus("Paused", ""); } else if (connected) start();
+  });
+
+  el("open-live").addEventListener("click", function () {
+    if (!liveUrl) return;
+    var url = liveUrl;
+    var fallback = function () {
+      // A sandbox may block new windows; window.open with noopener returns null either way, so say how to open it by hand.
+      window.open(url, "_blank", "noopener");
+      openHint = "If no tab opened, copy the address above into your browser.";
+      el("live-note").textContent = openHint;
+      el("live-note").hidden = false;
+    };
+    if (canOpenLinks) request("ui/open-link", { url: url }).then(function (r) { if (r && r.isError) fallback(); }, fallback);
+    else fallback();
+  });
+
+  if (window.parent === window) {
+    setStatus("Open this pane through an MCP host: it reads the run through scout_status.", "err");
+    return;
+  }
+
+  request("ui/initialize", {
+    appInfo: { name: "SceneScout status", version: VERSION },
+    appCapabilities: { availableDisplayModes: ["inline"] },
+    protocolVersion: PROTOCOL,
+  })
+    .then(function (result) {
+      result = result || {};
+      applyContext(result.hostContext || {});
+      canOpenLinks = !!(result.hostCapabilities && result.hostCapabilities.openLinks);
+      notify("ui/notifications/initialized");
+      connected = true;
+      watchSize();
+      setStatus("Connected", "on");
+      start();
+    })
+    .catch(function (err) {
+      setStatus("Not connected: " + (err && err.message ? err.message : String(err)), "err");
+    });
+})();
+</script>
+</body>
+</html>
+`;
+}

package/dist/engine/status-pane.js

@@ -0,0 +1,128 @@
+/**
+ * The run-status pane: an MCP App (SEP-1865, extension `io.modelcontextprotocol/ui`)
+ * that a host able to render one shows inline, and the text every other host
+ * shows instead.
+ *
+ * `scout_status` links the pane's `ui://` resource through `_meta.ui.resourceUri`.
+ * The pane polls an app-only tool (`_meta.ui.visibility: ["app"]`) for what is
+ * built here, because the spec delivers no server notification to a view after
+ * it renders. A host that does not render MCP Apps treats `scout_status` as a
+ * plain tool, so its text has to stand alone: it always carries the live view's
+ * address.
+ *
+ * What the pane gets is what the live view already shows (ADR 7): each
+ * session's board entry, the open findings counted by severity, and the
+ * coverage figures in the report's summary. The board's text is redacted when
+ * it is written, and no token is returned except the one in the live view's
+ * address, which answers on this machine only.
+ *
+ * Nothing here imports Playwright or the MCP SDK, so every rule is table-tested.
+ */
+import { classify, formatDuration } from "./live.js";
+/** The pane's resource. `ui://` is the scheme the extension reserves for views. */
+export const STATUS_PANE_URI = "ui://scenescout/status.html";
+/** The only content type the 2026-01-26 specification defines for a view. */
+export const MCP_APP_MIME = "text/html;profile=mcp-app";
+/** The protocol version the pane names in `ui/initialize`. */
+export const MCP_APPS_PROTOCOL = "2026-01-26";
+/** The model-facing tool: returns the text and links the pane. */
+export const STATUS_TOOL = "scout_status";
+/** The app-only tool the pane polls. A host that implements visibility keeps it out of the model's list. */
+export const STATUS_POLL_TOOL = "scout_status_poll";
+/** How often the pane polls, in milliseconds: inside the 2–3 s the system-monitor example uses. */
+export const STATUS_POLL_MS = 2500;
+/** The live view's address. One place builds it, so the pane, the text and the attach result agree. */
+export function liveViewUrl(port, token) {
+    return `http://127.0.0.1:${port}/${token}/`;
+}
+export function countFindings(findings, runStart) {
+    const counts = { open: 0, high: 0, medium: 0, low: 0, thisRun: 0, worthALook: 0, resolved: 0 };
+    for (const f of findings) {
+        if (f.status === "resolved")
+            counts.resolved += 1;
+        else if (f.tier === "worth_a_look")
+            counts.worthALook += 1;
+        else {
+            counts.open += 1;
+            counts[f.severity] += 1;
+            if (runStart !== undefined && f.foundAt >= runStart)
+                counts.thisRun += 1;
+        }
+    }
+    return counts;
+}
+/** What the pane renders and the app-only tool returns. Pure: the server gathers the input. */
+export function paneData(input) {
+    const sessions = input.sessions.map((s) => {
+        const out = {
+            session: s.session,
+            role: s.role,
+            state: classify(s, input.nowMs),
+            tool: s.tool,
+            forMs: Math.max(0, input.nowMs - new Date(s.since).getTime()),
+            url: s.url,
+        };
+        if (s.objective)
+            out.objective = s.objective;
+        if (s.task)
+            out.task = s.task;
+        return out;
+    });
+    const data = {
+        at: new Date(input.nowMs).toISOString(),
+        version: input.version,
+        liveUrl: input.live ? liveViewUrl(input.live.port, input.live.token) : null,
+        sessions,
+        findings: input.findings ? countFindings(input.findings, input.runStart) : null,
+        coverage: input.coverage,
+    };
+    if (!data.liveUrl) {
+        data.liveNote = input.liveOff
+            ? "The live view is off: SCENESCOUT_LIVE=off is set in the server's environment."
+            : input.liveError
+                ? `The live view could not start: ${input.liveError}`
+                : "The live view starts with the first scout_attach.";
+    }
+    return data;
+}
+function sessionLine(s) {
+    const what = s.state === "idle"
+        ? `idle ${formatDuration(s.forMs)} after ${s.tool}`
+        : `${s.state === "stuck" ? "STUCK in" : "running"} ${s.tool} for ${formatDuration(s.forMs)}`;
+    const lines = [`- ${s.session} (${s.role}): ${what}${s.url ? ` on ${s.url}` : ""}`];
+    if (s.task)
+        lines.push(`  task: ${s.task}`);
+    if (s.objective)
+        lines.push(`  objective: ${s.objective}`);
+    return lines.join("\n");
+}
+/**
+ * The tool's text: everything the pane shows, for a host that shows no pane.
+ * The first line is the live view's address, in the `Live view:` form the
+ * attach result uses, so an agent that relays one relays the other.
+ */
+export function paneText(data) {
+    const lines = [
+        data.liveUrl
+            ? `Live view: ${data.liveUrl} — open it to watch every session. It answers on this machine only and cannot act on the run.`
+            : `Live view: not available. ${data.liveNote ?? ""}`.trimEnd(),
+    ];
+    if (data.sessions.length === 0)
+        lines.push("No session is attached.");
+    else {
+        lines.push(`${data.sessions.length} session${data.sessions.length === 1 ? "" : "s"}:`);
+        for (const s of data.sessions)
+            lines.push(sessionLine(s));
+    }
+    if (data.findings) {
+        const f = data.findings;
+        const extra = [f.worthALook ? `${f.worthALook} worth a look` : "", f.resolved ? `${f.resolved} resolved` : ""].filter(Boolean).join(", ");
+        lines.push(`Open findings: ${f.open} (${f.high} high, ${f.medium} medium, ${f.low} low), ${f.thisRun} this run${extra ? `; ${extra}` : ""}`);
+    }
+    if (data.coverage) {
+        const c = data.coverage;
+        const routes = c.routesTotal > 0 ? `routes ${c.routesVisited}/${c.routesTotal} · ` : "";
+        lines.push(`Coverage: ${routes}${c.states} states · ${c.elementsExercised}/${c.elementsTotal} elements exercised`);
+    }
+    return lines.join("\n");
+}

package/dist/first-run.js

@@ -147,6 +147,7 @@ export function firstRunCheckOptions(o, projectDir) {
         maxRoutes: o.maxRoutes,
         timeBudgetMs: o.maxMinutes * 60_000,
         ignore: [],
+        ignorePaths: [],
         flows: "off",
         retest: false,
         flowWrites: "never",

package/dist/installer.js

@@ -16,13 +16,118 @@ 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"];
+/** Windows' own PATHEXT when the variable is unset. Each entry includes its dot. */
+const WINDOWS_PATH_EXT = ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC";
+/** cmd.exe meta characters. A caret in front of one of these keeps it literal. */
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+/** A `.cmd` or `.bat` file. Node refuses to spawn one directly (EINVAL) unless a shell starts it. */
+export function isBatchShim(file) {
+    return /\.(?:cmd|bat)$/i.test(file);
+}
+function escapeCmdMeta(value) {
+    return value.replace(CMD_META, "^$1");
+}
+/**
+ * The file Windows would run for `command`, or null when nothing matches.
+ *
+ * The current directory is tried before PATH. A name that already contains a
+ * dot is tried as written, then with each PATHEXT suffix; a name without a
+ * dot only gains those suffixes. Suffixes stay in PATHEXT order, so an
+ * `.exe` listed ahead of `.cmd` wins when both exist.
+ */
+export function resolveWindowsCommand(command, opts) {
+    const listed = (opts.pathExt?.trim() || WINDOWS_PATH_EXT).split(";").filter((ext) => ext !== "");
+    const exts = path.win32.basename(command).includes(".") ? ["", ...listed] : listed;
+    const rooted = path.win32.isAbsolute(command) || /[\\/]/.test(command);
+    const dirs = rooted ? [""] : [opts.cwd, ...windowsPathDirs(opts.pathEnv)];
+    for (const dir of dirs) {
+        const base = rooted ? (path.win32.isAbsolute(command) ? command : path.win32.join(opts.cwd, command)) : path.win32.join(dir, command);
+        for (const ext of exts) {
+            const candidate = base + ext;
+            if (opts.exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function windowsPathDirs(pathEnv) {
+    const dirs = [];
+    for (const raw of pathEnv.split(";")) {
+        const dir = raw.trim();
+        if (!dir)
+            continue;
+        dirs.push(dir.length >= 2 && dir.startsWith('"') && dir.endsWith('"') ? dir.slice(1, -1) : dir);
+    }
+    return dirs;
+}
+/**
+ * One argument on a `cmd /c` line that a batch shim forwards with `%*`.
+ *
+ * Quoted for the program that finally runs (backslashes before a quote follow
+ * CommandLineToArgvW). Every cmd meta character is then caret-escaped twice:
+ * once for `cmd.exe /c`, and once for the shim line that expands `%*`. A JSON
+ * value and a path containing spaces each stay a single argument.
+ */
+function escapeCmdArgument(arg) {
+    let value = `${arg}`;
+    // Backslashes that escape a following quote, then a trailing run that the
+    // wrapping quote would otherwise swallow. The match does not backtrack.
+    value = value.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"');
+    value = value.replace(/(?=(\\+?)?)\1$/, "$1$1");
+    value = escapeCmdMeta(escapeCmdMeta(`"${value}"`));
+    return value;
+}
+/** The string after `cmd.exe /d /s /c`. The outer quotes exist for `/s` to strip. */
+function windowsBatchCommandLine(command, args) {
+    const program = escapeCmdMeta(path.win32.normalize(command));
+    return `"${[program, ...args.map(escapeCmdArgument)].join(" ")}"`;
+}
+/**
+ * How to start `command`. On Windows a resolved `.cmd` or `.bat` goes through
+ * `cmd.exe`, because node will not spawn those itself. Everywhere else, and
+ * for an executable, the command and its arguments pass through unchanged.
+ */
+export function planSpawn(opts) {
+    if (opts.platform === "win32" && opts.resolved && isBatchShim(opts.resolved)) {
+        return {
+            command: opts.comSpec?.trim() || "cmd.exe",
+            args: ["/d", "/s", "/c", windowsBatchCommandLine(opts.resolved, opts.args)],
+            windowsVerbatimArguments: true,
+        };
+    }
+    return { command: opts.command, args: opts.args };
+}
+/** `planSpawn` for this platform, resolving a Windows batch shim before choosing cmd.exe. */
+export function commandSpawnPlan(command, args, opts) {
+    if (opts.platform !== "win32")
+        return { command, args };
+    return planSpawn({
+        command,
+        args,
+        platform: "win32",
+        resolved: resolveWindowsCommand(command, { cwd: opts.cwd, pathEnv: opts.pathEnv ?? "", pathExt: opts.pathExt, exists: opts.exists }),
+        comSpec: opts.comSpec,
+    });
+}
 /** Real runner. `missing` separates "the binary is not installed" from "it ran and failed". */
 export const spawnRunner = (command, args, opts) => {
-    const r = spawnSync(command, args, { encoding: "utf8", timeout: 60_000, cwd: opts?.cwd });
+    const planned = commandSpawnPlan(command, args, {
+        platform: process.platform,
+        cwd: opts?.cwd ?? process.cwd(),
+        pathEnv: process.env.PATH,
+        pathExt: process.env.PATHEXT,
+        comSpec: process.env.ComSpec,
+        exists: (file) => fs.existsSync(file),
+    });
+    const r = spawnSync(planned.command, planned.args, {
+        encoding: "utf8",
+        timeout: 60_000,
+        cwd: opts?.cwd,
+        windowsVerbatimArguments: planned.windowsVerbatimArguments,
+    });
     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.
+    // A batch shim is started through cmd.exe above. EINVAL still means a shim
+    // was spawned directly and nothing ran: the same outcome as a missing binary.
     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) : "");
@@ -295,7 +400,8 @@ export function planCommand(opts) {
         if (mine || !checkout)
             return { action: "present", at: opts.resolved };
     }
-    // npm on Windows is a .cmd shim, which node cannot start directly.
+    // Putting `scenescout` on PATH stays a manual npm command on Windows. Client
+    // registration is separate: spawnRunner starts a `.cmd` shim itself.
     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");

package/dist/mcp-server.js

@@ -53,6 +53,8 @@ import { MAX_UNFILED_NAMED, unfiledDefects } from "./engine/calibration.js";
 import { SessionQueue, withWatchdog } from "./engine/dispatch.js";
 import { FIXTURE_KINDS } from "./engine/fixtures.js";
 import { feedForSession, LIVE_ENV, writeStatusFile, LIVE_TOKEN_FILE, liveEngines, liveTokenFileName, pidAlive, statusFileName, LiveServer, StatusBoard, } from "./engine/live.js";
+import { liveViewUrl, MCP_APP_MIME, paneData, paneText, STATUS_PANE_URI, STATUS_POLL_TOOL, STATUS_TOOL, } from "./engine/status-pane.js";
+import { statusPanePage } from "./engine/status-pane-page.js";
 import { formatBriefs, MAX_LANES, planLanes } from "./engine/brief.js";
 import { decideOpen, OPEN_CHOICES, OPEN_ENV, openChoiceFromEnv, openInBrowser } from "./engine/open.js";
 import { DEFAULT_EXPIRY_MARGIN_MINUTES, DEFAULT_RUN_MINUTES, judgeProfileFile } from "./engine/expiry.js";
@@ -70,6 +72,7 @@ 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 { livePrompt, loginPrompt, LOGIN_PROMPT, LIVE_PROMPT, LOGIN_PROMPT_ARGUMENTS, LIVE_PROMPT_ARGUMENTS } from "./prompts.js";
 import { formatScan, scanProject } from "./scan.js";
 import { CAPTURE_MARGIN, CAPTURES_DIRNAME, captureFileName, captureResultText, describePicture, EVIDENCE_ENV, EVIDENCE_LIMITS, EVIDENCE_MARGIN, EVIDENCE_MODES, evidenceFrame, evidenceSettings, findingPicturePath, MAX_CAPTURE_MARGIN, RECORD_ENV, recordChoice, returnsInline, } from "./engine/capture.js";
 import { decodePng, fitPicture } from "./engine/png.js";
@@ -346,7 +349,7 @@ function startLiveServer() {
 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 ` +
+    return (`\nLive view: ${liveViewUrl(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.`);
 }
 /** What each session's attach decided to open (engine/open.ts). scout_report reads it for the report. */
@@ -540,10 +543,11 @@ server.registerTool(PLAYBOOK_TOOL, {
         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.
+// Prompts, 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. `explore` and `live` accept that; `login` then says the
+// role is missing. None of them takes a password.
 server.server.registerCapabilities({ prompts: {} });
 server.server.setRequestHandler(ListPromptsRequestSchema, () => ({
     prompts: [
@@ -553,16 +557,36 @@ server.server.setRequestHandler(ListPromptsRequestSchema, () => ({
             description: "Start an exploratory test session: loads the SceneScout method and states the target.",
             arguments: EXPLORE_PROMPT_ARGUMENTS,
         },
+        {
+            name: LIVE_PROMPT,
+            title: "Watch the live view",
+            description: "Return the loopback live-view URL for the current session. Takes no arguments and no password.",
+            arguments: LIVE_PROMPT_ARGUMENTS,
+        },
+        {
+            name: LOGIN_PROMPT,
+            title: "Sign in as a role",
+            description: "Call scout_login for a role and wait the way that tool waits. The person signs in in the window it opens. Takes the role, and the app URL when you have it. Never a password.",
+            arguments: LOGIN_PROMPT_ARGUMENTS,
+        },
     ],
 }));
 server.server.setRequestHandler(GetPromptRequestSchema, (request) => {
-    if (request.params.name !== PLAYBOOK_PROMPT)
-        throw new McpError(ErrorCode.InvalidParams, `Unknown prompt: ${request.params.name}`);
+    const name = request.params.name;
     let message;
     try {
-        message = explorePrompt(loadPlaybook(PACKAGE_ROOT), request.params.arguments);
+        if (name === PLAYBOOK_PROMPT)
+            message = explorePrompt(loadPlaybook(PACKAGE_ROOT), request.params.arguments);
+        else if (name === LIVE_PROMPT)
+            message = livePrompt(request.params.arguments);
+        else if (name === LOGIN_PROMPT)
+            message = loginPrompt(request.params.arguments);
+        else
+            throw new McpError(ErrorCode.InvalidParams, `Unknown prompt: ${name}`);
     }
     catch (err) {
+        if (err instanceof McpError)
+            throw err;
         throw new McpError(ErrorCode.InvalidParams, err instanceof Error ? err.message : String(err));
     }
     return { messages: [{ role: "user", content: { type: "text", text: message } }] };
@@ -950,7 +974,7 @@ server.registerTool("scout_attach", {
         let openNote = "";
         if (opening.live && liveAddress && !liveOpened) {
             liveOpened = true;
-            openNote = openForUser("the live view", `http://127.0.0.1:${liveAddress.port}/${liveAddress.token}/`);
+            openNote = openForUser("the live view", liveViewUrl(liveAddress.port, liveAddress.token));
         }
         else if (!opening.live && liveAddress && !openWhySaid) {
             // Once per server, so a person wondering why no window appeared is told how to change it.
@@ -1760,6 +1784,67 @@ server.registerTool("scout_finding", {
         return errorText(err);
     }
 }));
+// ---- The run-status pane: an MCP App (SEP-1865, `io.modelcontextprotocol/ui`, spec 2026-01-26). ----
+// scout_status links the pane through _meta.ui.resourceUri; the pane polls the
+// app-only tool. Neither goes through a session queue: like the live view, a
+// watcher must never wait behind the agent's calls, and both only read.
+function statusPaneData() {
+    const eng = [lastWriter ? engines.get(lastWriter.session) : undefined, ...engines.values()].find((e) => !!e?.memory);
+    const memory = eng?.memory ?? null;
+    let coverage = null;
+    if (eng && memory) {
+        const all = eng.allKnownRoutes();
+        const cov = memory.coverage();
+        coverage = {
+            routesVisited: all.length - eng.unvisitedKnownRoutes().length,
+            routesTotal: all.length,
+            states: cov.states,
+            elementsExercised: cov.elementsExercised,
+            elementsTotal: cov.elementsTotal,
+        };
+    }
+    return paneData({
+        nowMs: Date.now(),
+        version: PKG_VERSION,
+        live: liveAddress,
+        liveError,
+        liveOff: process.env[LIVE_ENV] === "off",
+        sessions: board.list(),
+        findings: memory ? memory.findings : null,
+        runStart: memory?.sessionStart,
+        coverage,
+    });
+}
+function statusResult() {
+    try {
+        const data = statusPaneData();
+        return { content: [{ type: "text", text: paneText(data) }], structuredContent: { ...data } };
+    }
+    catch (err) {
+        return errorText(err);
+    }
+}
+server.registerResource("scenescout-status", STATUS_PANE_URI, {
+    title: "SceneScout run status",
+    description: "The run's sessions, open findings by severity, coverage and the live view's address, refreshed every few seconds.",
+    mimeType: MCP_APP_MIME,
+    // No outside origin: the page is one self-contained document, so the host's restrictive default CSP applies.
+    _meta: { ui: { csp: {}, prefersBorder: true } },
+}, () => ({
+    contents: [{ uri: STATUS_PANE_URI, mimeType: MCP_APP_MIME, text: statusPanePage(PKG_VERSION), _meta: { ui: { csp: {}, prefersBorder: true } } }],
+}));
+server.registerTool(STATUS_TOOL, {
+    title: "Run status",
+    description: "Show the person running you how the run stands: each session's objective and current task, open findings by severity, coverage, and the live view's address. " +
+        "Call it when the user wants to watch or asks how the run is going. A host that renders MCP Apps shows a pane that keeps itself up to date; every other host gets the same as text, and you pass the `Live view:` address on. Takes no input and touches no browser.",
+    // The legacy flat key alongside _meta.ui.resourceUri, as the ext-apps SDK's registerAppTool sets both for hosts that read only the old one.
+    _meta: { ui: { resourceUri: STATUS_PANE_URI }, "ui/resourceUri": STATUS_PANE_URI },
+}, async () => statusResult());
+server.registerTool(STATUS_POLL_TOOL, {
+    title: "Run status (for the pane)",
+    description: `Called by the ${STATUS_TOOL} pane every few seconds to refresh itself. Not for the agent: call ${STATUS_TOOL} instead.`,
+    _meta: { ui: { visibility: ["app"] } },
+}, async () => statusResult());
 server.registerTool("scout_coverage", {
     description: "Show exploration coverage: states visited, which elements remain unexercised, which options of a dropdown used this run no session has chosen yet, and which forms seen this run no session has submitted with every text field blank. Use to decide where to explore next and when the level's budget is satisfied. In a parallel run it shows this session's own work by default — the routes it reached this run and the forms it saw — so one lane is not handed another's gaps; scope:\"project\" shows every session's, each form and route tagged with the sessions that saw it.",
     inputSchema: {

package/dist/prompts.js

@@ -0,0 +1,106 @@
+/**
+ * MCP prompts other than the testing method.
+ *
+ * `explore` lives in playbook.ts because its text is the skill. `live` and
+ * `login` are short instructions: hand back the loopback live-view address,
+ * or call scout_login for a role. Neither accepts a password. The protocol
+ * server in mcp-server.ts lists all three; the SDK prompt helper is not used,
+ * because it rejects a request that omits `arguments`.
+ */
+import { validateRoleName } from "./engine/profiles.js";
+export const LIVE_PROMPT = "live";
+export const LOGIN_PROMPT = "login";
+/** `live` takes nothing. A password field here would ask the person for a credential the live view does not use. */
+export const LIVE_PROMPT_ARGUMENTS = [];
+/** `login` names a role, and the app's address when the caller has one. There is no password argument. */
+export const LOGIN_PROMPT_ARGUMENTS = [
+    {
+        name: "role",
+        description: "The name to save the sign-in under, e.g. admin. scout_attach { role } uses it afterwards. Not a password.",
+        required: true,
+    },
+    {
+        name: "url",
+        description: "The app's address or its sign-in page, when you have it, e.g. http://localhost:3000. Omit when the conversation already has it.",
+        required: false,
+    },
+];
+/**
+ * Argument names that would carry a credential. Matched on the name only, so
+ * a refusal can name the argument without repeating the value the client sent.
+ */
+const CREDENTIAL_ARGUMENT = /^(?:password|passwd|pass|secret|token|credential|credentials|otp|totp|mfa|apikey|api_key)$/i;
+function refuseCredentialArguments(args) {
+    if (!args)
+        return;
+    for (const key of Object.keys(args)) {
+        if (CREDENTIAL_ARGUMENT.test(key)) {
+            throw new Error(`this prompt does not take ${key}: never pass a password or any other credential`);
+        }
+    }
+}
+/**
+ * The opening message of the `live` prompt. The address itself is printed by
+ * the engine on tool results (`Live view: http://127.0.0.1:…`); this only
+ * tells the model to hand that line back. Any argument is refused.
+ */
+export function livePrompt(args) {
+    refuseCredentialArguments(args);
+    const given = Object.keys(args ?? {}).filter((key) => args?.[key] !== undefined);
+    if (given.length > 0)
+        throw new Error("the live prompt takes no arguments");
+    return ("Return the loopback live-view URL for the current session.\n\n" +
+        "The live view is one address for every session of this run. It is served on 127.0.0.1 only, and a tool result prints it as a line starting " +
+        '"Live view: http://127.0.0.1:". If this conversation does not already contain that line, call scout_session with no arguments and read it from the result. ' +
+        "Calling scout_session with a name would change the default session; do not pass one.\n\n" +
+        "Reply with that address. Where you can open a URL for the user, you may open it as well. " +
+        "If the result says the live view is unavailable, say so and do not invent an address.\n\n" +
+        "Do not ask for a password or any other credential. This prompt takes none.");
+}
+/** An http(s) address with no userinfo. The raw string is returned only after that check, so a refusal never quotes a password embedded in it. */
+function publicHttpUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error("url must be an http or https address");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw new Error(`only http and https URLs can be opened (got ${url.protocol})`);
+    if (url.username || url.password)
+        throw new Error("put no credentials in the URL: sign in in the window instead");
+    return raw;
+}
+/**
+ * The opening message of the `login` prompt: call scout_login for the role and
+ * wait the way that tool already waits. A missing or illegal role is refused.
+ * A password argument is refused without the value being repeated.
+ */
+export function loginPrompt(args) {
+    refuseCredentialArguments(args);
+    const given = args ?? {};
+    const unknown = Object.keys(given).filter((key) => key !== "role" && key !== "url");
+    if (unknown.length > 0)
+        throw new Error("the login prompt takes role and url only");
+    const checked = validateRoleName(typeof given.role === "string" ? given.role.trim() : given.role);
+    if (!checked.ok)
+        throw new Error(checked.error);
+    const url = publicHttpUrlOrNone(typeof given.url === "string" ? given.url.trim() : "");
+    // JSON so a quote in the address cannot rewrite the instruction. The address has already been refused when it carries credentials.
+    const where = url
+        ? `Call scout_login with ${JSON.stringify({ role: checked.role, url })}.`
+        : `Call scout_login with role ${JSON.stringify(checked.role)} and the app's address as url. ` +
+            "Use the address this conversation already has; if it has none, ask for the app's address or its sign-in page, then pass that as url.";
+    return (`Sign in as the role "${checked.role}" by calling scout_login. ` +
+        "Do not ask for a password, and do not type credentials yourself: the person signs in in the browser window the tool opens.\n\n" +
+        'Tell them first, in plain words: "A browser window is opening. Sign in there as you normally would; it closes by itself once you are in."\n\n' +
+        `${where}\n\n` +
+        "The call returns once they are signed in and the login is saved, or after its wait with the window still open. " +
+        `When it is still waiting, call scout_login again with the same role ("${checked.role}") to keep waiting, once they say they are done or to check. ` +
+        "Never pass a password.");
+}
+/** `publicHttpUrl("")` would throw. An omitted url is the optional argument left out, not an illegal address. */
+function publicHttpUrlOrNone(raw) {
+    return raw ? publicHttpUrl(raw) : "";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.16.0",
+  "version": "3.17.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",
@@ -111,14 +111,14 @@
     "dedup-bench": "tsx scripts/dedup-bench.ts"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "playwright": "^1.63.0",
     "zod": "^3.25.0"
   },
   "devDependencies": {
     "@changesets/cli": "3.0.3",
     "@types/node": "^20.19.0",
-    "prettier": "3.9.8",
+    "prettier": "3.9.9",
     "tsx": "^4.23.15",
     "typescript": "^5.9.3",
     "yaml": "^2.9.1"

package/skills/scenescout/SKILL.md

@@ -116,7 +116,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 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.** On a local desktop session the engine also opens it in the user's browser (an `Opened the live view` line says so), and opens report.html when `scout_report` writes it; pass `open` (`live`, `report`, `both`, `none`) only when the user asks for something else. `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.
+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.** On a local desktop session the engine also opens it in the user's browser (an `Opened the live view` line says so), and opens report.html when `scout_report` writes it; pass `open` (`live`, `report`, `both`, `none`) only when the user asks for something else. `scout_session` with no arguments repeats it if they ask again, and `scenescout watch <project>` opens it from a terminal. **When the user wants to watch the run, or asks how it is going, call `scout_status`** (no input): a host that renders MCP Apps shows a pane that keeps itself up to date with each session's objective and task, open findings by severity, coverage and a button for the live view; every other host gets the same as text, starting with the `Live view:` address, which you pass on. 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)