scenescout 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # scenescout
 
+## 1.3.0
+
+### Minor Changes
+
+- a7c978a: `scenescout install` now puts the `scenescout` command on your PATH. Until now neither an `npx` run nor a source checkout left it there, so `scenescout status`, `scenescout doctor` and the other commands the tool itself tells you to run answered "command not found".
+  
+  Run through `npx`, install does `npm install -g` of the version you ran. From a checkout it does `npm link`, so the command always runs what you last built, and From a checkout it runs `npm link`, taking the name over from any other copy the way install already takes over the MCP registration. Run through `npx`, a command that is already there is left alone. On Windows the step prints the command to run by hand. If npm refuses, the step prints the command to run by hand and does not fail the setup. `--no-command` skips it.
+- 195cb59: Watch a run live. `scout_attach` now returns a `Live view:` address, which the agent passes on to you, and `scenescout watch <project>` opens the same page from a terminal. It shows one card per session: the tool it is running, how long it has been there, the page it is on, a thumbnail of that page, a rolling feed of what it just did (each action, its target and how it turned out, read from the same action log a finding's repro trace uses), and a live stream you can switch on per session or for all of them. Opening a card's close-up shows a longer stretch of that feed beside the session's brief: the task the agent gave it at `scout_attach {task}`, and the goal of the journey it is on right now. Actions of one journey share a tint in the feed, and pointing at a group shows the goal those actions served. The Report button shows the run's report as it stands, rendered from the current state without writing it, so it can be read while the run is still going. It works for headless runs, and a session whose call is still running past its own tool's watchdog budget is marked as stuck.
+  
+  `status.json` now describes every session instead of the last one to write, and `scenescout status` prints a line for each.
+  
+  The live view is served on `127.0.0.1` only, behind a per-process token, answers GET and nothing else, and writes no frame to disk ([ADR 7](docs/adr/0007-the-live-view-is-local-read-only-and-leaves-nothing-behind.md)). A stream runs only while someone is watching it. Set `SCENESCOUT_LIVE=off` to keep the engine from opening the port. The engine now also shuts down, closing its browsers and removing the token file, when its client closes the connection instead of sending a signal.
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -35,7 +35,7 @@ This is a real run against the small demo app bundled in this repository. The ap
 
 <p align="center"><img src="examples/screenshots/dashboard-annotated.png" alt="The demo app's dashboard with two defects outlined in red: 1, a yellow badge covering the All orders button; 2, the weekly chart image failing to load" width="760" /></p>
 
-**The broken chart is the demo app's bug, not this page's** — it is one of the ten findings SceneScout filed, next to the badge sitting on a button. The red callouts were added for this README; the [unmarked screenshots](examples/screenshots/) are the ones the engine took.
+**The broken chart is the demo app's bug, not this page's** — it is one of the twelve findings SceneScout filed, next to the badge sitting on a button. The red callouts were added for this README; the [unmarked screenshots](examples/screenshots/) are the ones the engine took.
 
 An excerpt of the report it wrote — [read the whole thing](examples/report.md):
 
@@ -46,13 +46,16 @@ An excerpt of the report it wrote — [read the whole thing](examples/report.md)
 > **🔴 [HIGH] Filtering orders by Archived fails, and the page shows an empty table instead of an error**
 > Evidence: `GET /api/orders?status=archived → HTTP 500`
 >
+> **🔴 [HIGH] A clerk can approve an order by calling the endpoint the page hides from them**
+> Evidence: `POST /api/orders/1037/approve 200 as clerk; POST /api/orders/1038/reject 403 as clerk` — the button was hidden, the server did not agree.
+>
 > **🟠 [MEDIUM] The "New: bulk import" badge sits on top of the All orders button** *(callout 1)*
 > Evidence: `"All orders" overlaps "New: bulk import" (81%)` — measured from layout boxes, no screenshot needed.
 >
 > **🟡 [LOW] The dashboard chart image is missing** *(callout 2)*
 > Evidence: `GET /img/weekly-chart.png → HTTP 404`
 >
-> **Gap ledger — what was NOT tested:** 4/7 visited routes never design-audited · single-role run, so permission boundaries are untested
+> **Gap ledger — what was NOT tested:** 9/12 visited routes never design-audited · single-role run, so permission boundaries are untested
 
 Every finding comes with a repro trace and a Playwright regression-test skeleton. To try it yourself, clone this repository, run `npm run demo:serve`, then `/scenescout --url http://127.0.0.1:4173` — see [demo-app/](demo-app/). Its README lists every seeded defect and which oracle catches it.
 
@@ -136,9 +139,10 @@ Then download the browser once with `npx -y scenescout install --browser-only`.
 
 1. puts the `/scenescout` skill into `~/.claude/skills/` (or `$CLAUDE_CONFIG_DIR/skills/`) — a `scenescout` folder it didn't create is moved aside to a `.backup-…` copy, never deleted,
 2. downloads the browser SceneScout drives (skipped if you already have it). By default that is Chromium, as two builds: the full browser for headed runs and the headless shell every other run uses. [Choose something else](#-choosing-browsers) with `--browsers`,
-3. registers the MCP server with Claude Code at user scope. Run through `npx`, the launcher is `npx -y scenescout serve`, with the absolute path of `npx` where one sits beside node, so it works under nvm/fnm. From a clone or a global install it is the absolute node path plus that install's `dist/mcp-server.js`.
+3. registers the MCP server with Claude Code at user scope. Run through `npx`, the launcher is `npx -y scenescout serve`, with the absolute path of `npx` where one sits beside node, so it works under nvm/fnm. From a clone or a global install it is the absolute node path plus that install's `dist/mcp-server.js`,
+4. puts the `scenescout` command on your PATH, so `scenescout status`, `scenescout watch` and `scenescout doctor` work from any terminal. Run through `npx`, that is `npm install -g` of the version you just ran; from a clone it is `npm link`, so the command always runs what you last built. If npm refuses (a system-wide node usually needs `sudo` for this), the step prints the command to run by hand and the rest of the setup still counts as done: `npx -y scenescout <command>` works without it.
 
-Re-run it any time: after moving the folder or switching node versions it refreshes the stored paths. It exits non-zero if any step failed, so it is safe to chain. Opt out of a step with `--no-register` or `--skip-browser`.
+Re-run it any time: after moving the folder or switching node versions it refreshes the stored paths. It exits non-zero if a step the tool depends on failed, so it is safe to chain. Opt out of a step with `--no-register`, `--skip-browser` or `--no-command`.
 
 If `claude` isn't on the PATH of the shell you ran it from, it prints the registration command instead of running it:
 
@@ -179,6 +183,32 @@ The agent scans the project (if there is one), attaches read-only, explores, and
 
 ---
 
+## 📺 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. 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 six parallel agents against the demo app: one card per session, each with its role, the tool it is running and for how long, the page it is on, a thumbnail, and a feed of the actions it just took" width="880" /></p>
+
+- **What it is doing:** the tool it is running and for how long, the page it is on, and a thumbnail of that page. This works for headless runs too, which have no window to look at.
+- **What it just did:** a rolling feed of its actions, each with its target and how it turned out, with failures in red. It is the same trail a finding's repro trace uses. The engine never sees the agent's reasoning, so this is what the session *did*, not what it thought.
+- **Stuck, not slow:** a call still running past its own tool's watchdog budget turns the card red, so a wedged session is visible without asking. A crawl legitimately runs for minutes; it is judged against the crawl's budget, not a click's.
+- **Live stream:** switch it on for one card, or for all of them. Click a thumbnail for a close-up.
+- **The report, as it stands:** the Report button in the top bar shows the same document `scout_report` writes at the end, rendered from the run's current state, so findings can be read while the agents are still working.
+- **What it is for:** the close-up puts the feed beside the session's brief: the task the agent gave it when it attached (`scout_attach {task}`), and the goal of the journey it is on right now (`scout_journey`). Actions of one journey share a tint in the feed; point at a group and the brief shows the goal those actions served.
+
+<p align="center"><img src="examples/screenshots/live-view-closeup.png" alt="A close-up of one session: its page streaming live, the feed of its recent actions grouped by journey, and beside it the task and current objective" width="880" /></p>
+
+<p align="center"><img src="examples/screenshots/live-view-report.png" alt="The report opened from the live view's top bar while the run is still going: summary table, gap ledger and the findings filed so far" width="880" /></p>
+
+The view is served on `127.0.0.1` only, behind a token that changes every time the engine starts. It answers `GET` and nothing else, so a viewer can watch a run but not act in it, and no frame is ever written to disk ([ADR 7](docs/adr/0007-the-live-view-is-local-read-only-and-leaves-nothing-behind.md)). A stream runs only while someone is watching it. `SCENESCOUT_LIVE=off` keeps the port closed.
+
+**Try it with parallel agents.** The demo app has three roles and several separate areas, so a run can be split between agents. Start it with `npm run demo:serve`, then ask your agent to explore it with several agents in parallel, one role and one area each. The pictures above come from a run of six. Two things keep a parallel run efficient:
+
+- **Each agent opens its own session when it starts and closes it when it is done.** An agent waiting for its turn then holds no browser. Opening every session up front leaves browsers idling while the machine runs out of memory for the agents that are working.
+- **Run about as many agents at once as your machine has cores, less two.** Each one drives a real browser.
+
+---
+
 ## 🔄 How a run works
 
 One curiosity loop, repeated — breadth first, then judgment where it matters:
@@ -457,7 +487,8 @@ The CLI is also useful on its own:
 
 ```bash
 npx -y scenescout scan <path>       # project discovery: framework, routes, saved logins
-npx -y scenescout status <path>     # what a running engine is doing right now
+npx -y scenescout status <path>     # what every session of a running engine is doing right now
+npx -y scenescout watch <path>      # the same, live in your browser, with each session's page
 ```
 
 ---
@@ -519,7 +550,7 @@ npm test           # build + 12 suites: scan, oracle, policy, fixture, dispatch,
 npm run demo       # regenerate examples/ from the demo app
 ```
 
-Contributing? Start with [VISION.md](VISION.md) (what is in scope) and [CONTRIBUTING.md](CONTRIBUTING.md) (how changes land), then see [CLAUDE.md](CLAUDE.md) for the house rules — chiefly: bug fixes need a regression test at the cheapest layer that can fail, keep the repo project-agnostic (ADR 6), and `npm test` must pass.
+Contributing? Start with [VISION.md](VISION.md) (what is in scope) and [CONTRIBUTING.md](CONTRIBUTING.md) (how changes land), then see [AGENTS.md](AGENTS.md) for the house rules — chiefly: bug fixes need a regression test at the cheapest layer that can fail, keep the repo project-agnostic (ADR 6), and `npm test` must pass.
 
 ## 🔐 Security
 
@@ -545,6 +576,6 @@ Found a way past the write policy, or another security problem? Please report it
 - **A trustworthy gap ledger.** Entries must be actionable (a search box or wizard sub-step isn't "form filled but never submitted"); API/download URLs never enter the route contract.
 - **Honest reporting.** Shared chrome counted once, stale scores marked, role matrix compares only roles that actually attempted a route.
 - **Cross-run written knowledge.** `scout_note` curates `.scenescout/ASSUMPTIONS.md` — app model, personas, constraints, risks — in prose.
-- **Daemon-grade robustness.** Per-tool watchdogs, orphaned-browser reaping, bounded teardown, live status via `scenescout status <project>`.
+- **Daemon-grade robustness.** Per-tool watchdogs, orphaned-browser reaping, bounded teardown, live status via `scenescout status <project>`, and a live view of every session's page: the agent gives you its address when it attaches, or run `scenescout watch <project>` (loopback only, read-only, nothing written to disk: [ADR 7](docs/adr/0007-the-live-view-is-local-read-only-and-leaves-nothing-behind.md)).
 
 </details>

package/dist/browsers.js

@@ -140,6 +140,17 @@ export function installCommandFor(target, fromCheckout) {
 export function serviceWorkerPolicy(engine) {
     return engine === "chromium" ? "allow" : "block";
 }
+/**
+ * How the live view gets frames of a page.
+ *
+ * Chromium can push a frame on every repaint through the DevTools protocol,
+ * which costs nothing while the page sits still. Firefox and WebKit have no
+ * such channel in the driver, so a stream there is a screenshot taken on a
+ * timer for as long as somebody is watching.
+ */
+export function screencastSupport(engine) {
+    return engine === "chromium" ? "cdp" : "poll";
+}
 /**
  * The key that moves keyboard focus to the next control, links and buttons
  * included. WebKit on macOS follows Safari: plain Tab stops only at text

package/dist/cli.js

@@ -15,8 +15,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { APPROX_DISK_MB, BROWSER_ENGINES, browserPresence, defaultAttachNote, defaultEngine, launchTarget, parseBrowserSelection, playwrightInstallArgs, } from "./browsers.js";
 import { CLIENT_LABELS, firstMessageHint, manualFor, parseClients, registerWithClient, vscodeBinary } from "./clients.js";
-import { diagnose, installSkill, launchCommand, manualRegisterCommand, registerMcp, resolveClaudeDir, spawnRunner } from "./installer.js";
+import { CLI_NAME, diagnose, ensureCommand, findOnUserPath, installSkill, isEphemeralRoot, launchCommand, manualRegisterCommand, planCommand, registerMcp, resolveClaudeDir, spawnRunner, } from "./installer.js";
 import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME } from "./engine/memory.js";
+import { localClock, formatSessionLine, LIVE_TOKEN_FILE, watchTarget, wholeSessions } from "./engine/live.js";
 import { formatScan, scanProject } from "./scan.js";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(here, "..");
@@ -27,7 +28,8 @@ Usage:
   scenescout scan <projectPath>     Discover framework, routes, auth states
   scenescout serve                  Run the MCP server (stdio)
   scenescout install                One-step setup: skill + Chromium + MCP registration
-                                    (--skip-browser, --no-register to opt out of a step;
+                                    It also puts the \`scenescout\` command on your PATH.
+                                    (--skip-browser, --no-register, --no-command to opt out of a step;
                                      --browser-only when the skill and server came from a plugin;
                                      --browsers <list> to choose what to download: chromium (default),
                                      chromium-headless-shell, firefox, webkit, all — comma-separated)
@@ -37,52 +39,87 @@ Usage:
   scenescout doctor                 Check the setup and print the fix for anything missing
                                     (--engine: only node, the build and the browser — for plugin
                                      installs and other MCP clients)
-  scenescout status [projectPath]   What is the engine doing right now? (live status + recent actions)
+  scenescout status [projectPath]   What is the engine doing right now? (every session + recent actions)
+  scenescout watch [projectPath]    Open the live view in a browser: what each session is doing, a thumbnail
+                                    of its page, and a live stream you can switch on per session
+                                    (--no-open to print the address only)
 `);
     process.exit(exitCode);
 }
-/** Realtime observability: read the status file + recent action log the running engine maintains. */
-function status(projectPath) {
-    // A project last touched before the rename (or one a pre-rename engine is
-    // using right now) still keeps its status under the legacy directory.
-    const dir = [MEMORY_DIRNAME, LEGACY_MEMORY_DIRNAME]
+/**
+ * A project last touched before the rename (or one a pre-rename engine is using
+ * right now) still keeps its status under the legacy directory.
+ */
+function statusDir(projectPath) {
+    return ([MEMORY_DIRNAME, LEGACY_MEMORY_DIRNAME]
         .map((name) => path.join(projectPath, name))
-        .find((candidate) => fs.existsSync(path.join(candidate, "status.json"))) ?? path.join(projectPath, MEMORY_DIRNAME);
+        .find((candidate) => fs.existsSync(path.join(candidate, "status.json"))) ?? path.join(projectPath, MEMORY_DIRNAME));
+}
+/** null when there is no file; "unreadable" when there is one and it does not parse. */
+function readStatusFile(dir) {
     const statusPath = path.join(dir, "status.json");
-    if (!fs.existsSync(statusPath)) {
-        console.log(`No status file at ${statusPath} — no SceneScout engine has attached to this project (or it predates v0.8).`);
-        return;
-    }
-    let st;
+    if (!fs.existsSync(statusPath))
+        return null;
     try {
-        st = JSON.parse(fs.readFileSync(statusPath, "utf8"));
+        return JSON.parse(fs.readFileSync(statusPath, "utf8"));
     }
     catch {
         // status.json is written fire-and-forget on every tool call, so a process
         // killed mid-write leaves a truncated file. That is a diagnosable state,
         // not a reason for the diagnostic tool itself to crash.
-        console.log(`Status file at ${statusPath} is unreadable or truncated — the engine was probably killed mid-write. Re-attach to refresh it.`);
+        return "unreadable";
+    }
+}
+function pidAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process EXISTS but belongs to another user — only
+        // ESRCH actually means "no such process". Treating both as dead reported
+        // a live engine as stale.
+        return err?.code === "EPERM";
+    }
+}
+/** Realtime observability: read the status file + recent action log the running engine maintains. */
+function status(projectPath) {
+    const dir = statusDir(projectPath);
+    const statusPath = path.join(dir, "status.json");
+    const st = readStatusFile(dir);
+    if (st === null) {
+        console.log(`No status file at ${statusPath} — no SceneScout engine has attached to this project (or it predates v0.8).`);
         return;
     }
-    let alive = false;
-    if (st.pid) {
-        try {
-            process.kill(st.pid, 0);
-            alive = true;
-        }
-        catch (err) {
-            // EPERM means the process EXISTS but belongs to another user — only
-            // ESRCH actually means "no such process". Treating both as dead reported
-            // a live engine as stale.
-            alive = err?.code === "EPERM";
-        }
+    if (st === "unreadable") {
+        console.log(`Status file at ${statusPath} is unreadable or truncated — the engine was probably killed mid-write. Re-attach to refresh it.`);
+        return;
     }
+    const alive = pidAlive(st.pid);
     const age = st.at ? Math.round((Date.now() - new Date(st.at).getTime()) / 1000) : null;
     console.log(`Engine pid ${st.pid ?? "?"} — ${alive ? "ALIVE" : "not running (stale status)"}`);
     console.log(`${st.phase === "running" ? "⏳ running" : "· idle after"}: ${st.tool ?? "?"}${age !== null ? ` (as of ${age}s ago)` : ""}`);
-    console.log(`Session: ${st.session ?? "?"} (${st.role ?? "?"})${st.sessions && st.sessions.length > 1 ? ` · all sessions: ${st.sessions.join(", ")}` : ""}`);
-    if (st.url)
-        console.log(`URL: ${st.url}`);
+    // The file is written by another process and can be caught mid-write, so
+    // only entries whole enough to describe are described.
+    const sessions = wholeSessions(st.detail);
+    if (sessions.length > 0) {
+        // One line per session. The single "Session:" line below it is all an
+        // engine from before the live view can offer.
+        console.log(`Sessions (${sessions.length}):`);
+        for (const entry of sessions)
+            console.log(`  ${formatSessionLine(entry, Date.now())}`);
+        if (alive && st.live?.port)
+            console.log("Live view: scenescout watch");
+        if (alive && st.live?.error)
+            console.log(`Live view unavailable: ${st.live.error}`);
+    }
+    else {
+        console.log(`Session: ${st.session ?? "?"} (${st.role ?? "?"})${st.sessions && st.sessions.length > 1 ? ` · all sessions: ${st.sessions.join(", ")}` : ""}`);
+        if (st.url)
+            console.log(`URL: ${st.url}`);
+    }
     // Recent actions from the newest session log — the "what has it been doing" trail.
     const logs = fs.existsSync(dir)
         ? fs
@@ -108,7 +145,7 @@ function status(projectPath) {
         for (const line of lines) {
             try {
                 const e = JSON.parse(line);
-                console.log(`  ${e.at.slice(11, 19)} ${e.action}${e.target ? ` ${e.target}` : ""} @ ${e.url}`);
+                console.log(`  ${localClock(e.at)} ${e.action}${e.target ? ` ${e.target}` : ""} @ ${e.url}`);
             }
             catch {
                 /* skip malformed line */
@@ -116,6 +153,43 @@ function status(projectPath) {
         }
     }
 }
+/** Open the engine's live view. The engine serves it; this only finds the address and hands it to a browser. */
+function watch(projectPath, open) {
+    const dir = statusDir(projectPath);
+    const st = readStatusFile(dir);
+    let token = null;
+    try {
+        token = fs.readFileSync(path.join(dir, LIVE_TOKEN_FILE), "utf8");
+    }
+    catch {
+        // watchTarget explains a missing token in context.
+    }
+    const target = watchTarget({ status: st, alive: st !== null && st !== "unreadable" && pidAlive(st.pid), token });
+    if ("problem" in target) {
+        console.log(target.problem);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Live view: ${target.url}`);
+    console.log("It is served on this machine only, and the address holds its access token: treat it like a password.");
+    if (!open)
+        return;
+    const { command, args } = browserOpener(target.url);
+    const result = spawnSync(command, args, { stdio: "ignore" });
+    if (result.error || result.status !== 0)
+        console.log("Could not open a browser from here. Open the address above yourself.");
+}
+/** The platform's own "open this URL" command. */
+function browserOpener(url) {
+    switch (process.platform) {
+        case "darwin":
+            return { command: "open", args: [url] };
+        case "win32":
+            return { command: "cmd", args: ["/c", "start", "", url] };
+        default:
+            return { command: "xdg-open", args: [url] };
+    }
+}
 /** Which browser builds are on disk, going by the paths Playwright reports for the version we depend on. */
 async function presentBrowsers() {
     const executables = { chromium: null, firefox: null, webkit: null };
@@ -303,8 +377,39 @@ async function install(flags) {
             }
         }
     }
+    // `scenescout status`, `watch` and `doctor` are typed by a person, and neither
+    // a checkout nor an npx run leaves the command on PATH. Not having it costs
+    // convenience, never a working setup, so this step reports and does not fail.
+    let cli = isEphemeralRoot(packageRoot) ? `npx -y ${CLI_NAME}` : `node ${path.join(packageRoot, "dist", "cli.js")}`;
+    if (browserOnly) {
+        // a plugin install has no package of its own to put on PATH
+    }
+    else if (flags.includes("--no-command")) {
+        console.log(`· Putting \`${CLI_NAME}\` on PATH skipped (--no-command). Until then the command is:  ${cli}`);
+    }
+    else {
+        const onPath = () => findOnUserPath({ names: process.platform === "win32" ? [`${CLI_NAME}.cmd`] : [CLI_NAME], pathValue: process.env.PATH ?? "" });
+        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        const done = ensureCommand(planCommand({ packageRoot, nodePath: process.execPath, version: pkg.version, resolved: onPath(), platform: process.platform }), spawnRunner);
+        if (done.status === "present") {
+            cli = CLI_NAME;
+            console.log(`✓ \`${CLI_NAME}\` command already on PATH: ${done.at}`);
+        }
+        else if (done.status === "installed") {
+            const at = onPath();
+            if (at)
+                cli = CLI_NAME;
+            const what = done.how === "link" ? "linked to this checkout, so it runs whatever was last built" : "installed globally";
+            console.log(at
+                ? `✓ \`${CLI_NAME}\` command ${what}: ${at}${done.replaced ? `   (it replaces ${done.replaced})` : ""}`
+                : `· \`${CLI_NAME}\` was ${what}, but npm's global bin directory is not on this shell's PATH. Add it (\`npm prefix -g\` names it; the commands are in its bin folder), or use:  ${cli}`);
+        }
+        else {
+            console.log(`· \`${CLI_NAME}\` was not put on PATH (${done.detail}). To do it by hand:  ${done.manual}\n  Until then the command is:  ${cli}`);
+        }
+    }
     if (failed) {
-        console.log(`\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  scenescout doctor${forClaude ? "" : " --engine"}`);
+        console.log(`\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  ${cli} doctor${forClaude ? "" : " --engine"}`);
         process.exitCode = 1;
         return;
     }
@@ -317,7 +422,7 @@ async function install(flags) {
     // Telling someone to restart a client nothing was registered with sends them looking for a server that is not there.
     if (others.length > 0 && !flags.includes("--no-register"))
         console.log(`\n${firstMessageHint(others)}`);
-    console.log(`Something off? Run:  scenescout doctor${forClaude ? "" : " --engine"}`);
+    console.log(`Something off? Run:  ${cli} doctor${forClaude ? "" : " --engine"}`);
 }
 async function doctor(flags) {
     const checks = diagnose({
@@ -387,6 +492,11 @@ try {
             status(path.resolve(args[0] ?? process.cwd()));
             break;
         }
+        case "watch": {
+            const positional = args.filter((a) => !a.startsWith("--"));
+            watch(path.resolve(positional[0] ?? process.cwd()), !args.includes("--no-open"));
+            break;
+        }
         default:
             usage();
     }

package/dist/engine/browser.js

@@ -2,13 +2,13 @@ import { chromium, firefox, webkit } from "playwright";
 import fs from "node:fs";
 import path from "node:path";
 import { elementKey, fingerprintState, isNonPageRoute, normalizePath } from "./fingerprint.js";
-import { AUTH_LOSS_PREFIX, MemoryStore } from "./memory.js";
+import { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore } from "./memory.js";
 import { AuthLossTracker } from "./authloss.js";
 import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, } from "./collector.js";
 import { OracleMonitor, formatViolations } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
-import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, serviceWorkerPolicy, sharedWorkersAllowed } from "../browsers.js";
+import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, screencastSupport, serviceWorkerPolicy, sharedWorkersAllowed, } from "../browsers.js";
 import { revealedLines } from "./hover.js";
 import { explainLaunchFailure, isMissingBrowser } from "./launch.js";
 import { ACTION_TIMEOUT_MS, performScroll, probeFocusIndicators, probeOverlays, scrollContainer } from "./probes.js";
@@ -98,6 +98,8 @@ function actionabilityDiagnostic(message) {
  * actions by ref, runs oracles after every action, and records everything in
  * the persistent memory store. Contains no LLM calls — the MCP client is the brain.
  */
+/** A screencast whose page has been gone for this many 500 ms ticks ends and says so; a re-attach takes fewer. */
+const SCREENCAST_PAGELESS_TICKS = 20;
 export class BrowserEngine {
     browser = null;
     context = null;
@@ -186,6 +188,8 @@ export class BrowserEngine {
     designAuditCount = 0;
     /** Active task-efficiency measurement (scout_journey), if any. */
     journey = null;
+    /** The session's task, from scout_attach. Empty when the agent gave none. */
+    task = "";
     /**
      * Begin measuring a user JOURNEY — the interaction cost of completing one
      * real task ("create an order", "approve a document"). E2E suites assert
@@ -200,7 +204,7 @@ export class BrowserEngine {
             fromLog: this.memory?.actionLog.length ?? 0,
             startUrl: page.url(),
         };
-        this.logAction({ action: "journey:start", target: goal, url: page.url() });
+        this.logAction({ action: JOURNEY_START, target: goal, url: page.url() });
         return `JOURNEY STARTED — "${goal}"\nFrom: ${page.url()}\nNow perform the task the way a first-time user would (click through the UI; don't jump straight to a known deep URL, or the measurement is meaningless). Call scout_journey {action:"end"} when the task is complete or you conclude it can't be.`;
     }
     /** Close the journey and report its interaction cost + friction signals. */
@@ -225,7 +229,7 @@ export class BrowserEngine {
         catch {
             /* fact recording is best-effort */
         }
-        this.logAction({ action: "journey:end", target: j.goal, url: page.url(), result: completed ? "completed" : "abandoned" });
+        this.logAction({ action: JOURNEY_END, target: j.goal, url: page.url(), result: completed ? "completed" : "abandoned" });
         return formatJourney({ goal: j.goal, completed, seconds, note }, measured);
     }
     /** Whether the browser window is visible — headed hover results carry a physical-cursor caveat. */
@@ -258,6 +262,7 @@ export class BrowserEngine {
             throw new Error(`storageStatePath does not exist: ${opts.storageStatePath}`);
         }
         this.mode = opts.mode ?? "read-only";
+        this.task = (opts.task ?? "").trim().replace(/\s+/g, " ").slice(0, 300);
         this.headed = opts.headed ?? false;
         this.blockedRequests = [];
         this.pendingCreations = new Set();
@@ -1909,6 +1914,125 @@ export class BrowserEngine {
         this.logAction({ action: "screenshot", url: page.url() });
         return { base64: buf.toString("base64"), mimeType: "image/jpeg" };
     }
+    /**
+     * What the live view shows next to a session's name. The task is what the
+     * agent said the session is for; the objective is the goal of the journey it
+     * is on right now (scout_journey). Both are the agent's own words — the
+     * engine sees tool calls, never the reasoning behind them. Neither is
+     * redacted here: the caller that writes them anywhere does that.
+     */
+    get liveDescription() {
+        return {
+            mode: this.mode,
+            browser: this.engineName,
+            headed: this.headed,
+            ...(this.task ? { task: this.task } : {}),
+            ...(this.journey ? { objective: this.journey.goal, objectiveSince: new Date(this.journey.startedAt).toISOString() } : {}),
+        };
+    }
+    /**
+     * A frame for somebody WATCHING the run, as opposed to scout_screenshot,
+     * which is the agent looking. It is not logged: the action log is the repro
+     * trace attached to findings, and a person glancing at the dashboard is not
+     * a step anyone should replay. It is also bounded, because the moment a
+     * viewer most wants a picture is when the renderer has wedged.
+     */
+    async liveShot(timeoutMs = 3000) {
+        const page = this.page;
+        if (!page || page.isClosed())
+            return null;
+        let timer;
+        // The driver's own timeout covers a slow capture; the race covers a
+        // renderer that never answers the protocol at all.
+        return Promise.race([
+            page.screenshot({ type: "jpeg", quality: 55, fullPage: false, timeout: timeoutMs }).catch(() => null),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(null), timeoutMs + 500);
+            }),
+        ]).finally(() => clearTimeout(timer));
+    }
+    /**
+     * Push frames of this session's page until the returned function is called.
+     * The stream follows the session rather than one tab: adopting a popup
+     * replaces `this.page`, and a stream left on the old tab would show a page
+     * the session is no longer driving.
+     */
+    async startScreencast(onFrame, onEnd = () => { }) {
+        if (!this.page || this.page.isClosed())
+            return null;
+        let stopped = false;
+        let bound = null;
+        let release = null;
+        // Ticks in a row with no page to take frames from: a re-attach passes
+        // through a few, a closed session never comes back.
+        let pageless = 0;
+        const bind = async (page) => {
+            if (screencastSupport(this.engineName) === "cdp") {
+                const cdp = await page.context().newCDPSession(page);
+                try {
+                    cdp.on("Page.screencastFrame", (frame) => {
+                        if (!stopped)
+                            onFrame(Buffer.from(frame.data, "base64"));
+                        void cdp.send("Page.screencastFrameAck", { sessionId: frame.sessionId }).catch(() => { });
+                    });
+                    await cdp.send("Page.startScreencast", { format: "jpeg", quality: 55, maxWidth: 1280, maxHeight: 900, everyNthFrame: 2 });
+                }
+                catch (err) {
+                    // Not bound: the timer tries this page again on its next tick.
+                    await cdp.detach().catch(() => { });
+                    throw err;
+                }
+                release = async () => {
+                    await cdp.send("Page.stopScreencast").catch(() => { });
+                    await cdp.detach().catch(() => { });
+                };
+            }
+            else {
+                release = null;
+            }
+            bound = page;
+        };
+        const stop = async () => {
+            stopped = true;
+            clearInterval(timer);
+            const current = release;
+            release = null;
+            await current?.();
+        };
+        await bind(this.page).catch(() => { });
+        // One timer does both jobs: it notices a replaced tab, and where the
+        // browser cannot push frames it is also what takes them.
+        const timer = setInterval(() => {
+            if (stopped)
+                return;
+            const page = this.page;
+            if (!page || page.isClosed()) {
+                pageless += 1;
+                if (pageless >= SCREENCAST_PAGELESS_TICKS)
+                    void stop().finally(onEnd);
+                return;
+            }
+            pageless = 0;
+            if (page !== bound) {
+                const previous = release;
+                release = null;
+                void (async () => {
+                    await previous?.();
+                    if (!stopped)
+                        await bind(page).catch(() => { });
+                })();
+                return;
+            }
+            if (screencastSupport(this.engineName) === "poll") {
+                void this.liveShot(1500).then((jpeg) => {
+                    if (jpeg && !stopped)
+                        onFrame(jpeg);
+                });
+            }
+        }, 500);
+        timer.unref();
+        return stop;
+    }
     get currentState() {
         return this.currentFingerprint;
     }