scenescout 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # scenescout
 
+## 3.1.0
+
+### Minor Changes
+
+- 52d97d8: Record a run, and read the whole thing back afterwards.
+  
+  `scout_attach {record: true}` keeps a frame of the page after every action, and
+  `scout_report` then writes `report.html` beside `report.md`: the report, the
+  screenshots taken around each finding, and every session's trail in the blocks
+  its tasks made — one self-contained page that opens from the file system with
+  nothing running. Recording is off unless asked for, because the frames are
+  pictures of the app under test and no redaction can read a picture
+  ([ADR 8](docs/adr/0008-a-recorded-run-is-evidence-and-must-be-asked-for.md)).
+  
+  The live view serves the same document at its own address and goes there when
+  the run ends, so the report survives a refresh instead of dying with the board.
+  The close-up gains a timeline: a tick per action, coloured by task, that plays
+  a recorded run back while it is still going. A finding's screenshots also hang
+  under it in the live report panel, which no longer resets itself while it is
+  being read.
+  
+  Fixes: a listener left on a control that had been replaced threw on load and
+  left the board blank; a viewer arriving after the last browser closed saw the
+  empty state instead of the finished run; a finding's evidence could be drawn
+  from a different session than the one that filed it.
+
 ## 3.0.1
 
 ### Patch Changes

package/README.md

@@ -187,28 +187,67 @@ The agent scans the project (if there is one), attaches read-only, explores, and
 
 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>
+<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>
 
 - **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.
+- **What it is for:** the close-up puts the feed beside the session's brief — the objective it was given when it attached (`scout_attach {objective}`), and underneath it the task it is on right now (`scout_task`), which the engine requires before any tool will act. Each task tints its own block of actions, so a change of task is a change of colour; point at a block and the brief names the task those actions served.
+- **Scrub it back:** under the page is a tick per action, coloured by task. Click one to see the frame from that moment, and `Back to live` to return. On a run that was not recorded the ticks still read the trail; they just have no picture behind them.
 
-<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-closeup.png" alt="A close-up of one session: a frame from a step picked out of the timeline, the timeline itself as a tick per action coloured by task, the feed of the session's actions in the same colours, and beside it the objective and the task it is on" 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>
+<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, each with an accordion of the screenshots taken around it" 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.
+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 it shows is written to disk ([ADR 7](docs/adr/0007-the-live-view-is-local-read-only-and-leaves-nothing-behind.md)) unless the run was recorded, which is asked for and off by default ([ADR 8](docs/adr/0008-a-recorded-run-is-evidence-and-must-be-asked-for.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:
+**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 three. 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.
 
 ---
 
+## 🎬 Recording a run, and reading it back
+
+A report says what happened. For QA work that is not always enough — the point
+is often to *show* what was checked, not to assert it. Ask for a recorded run
+and the engine keeps a frame of the page after every action:
+
+```
+Use SceneScout to test http://localhost:3000, record the run
+```
+
+or, on the tool directly, `scout_attach {record: true}`.
+
+Then `scout_report` writes two files side by side in `.scenescout/`:
+`report.md` as always, and `report.html` — the whole run as one self-contained
+page. It opens from the file system with nothing running, needs no network, and
+holds:
+
+- **The report**, rendered from the same Markdown.
+- **The screenshots around each finding**, in an accordion under it, from the
+  session that filed it.
+- **Every session's trail**, in the blocks its tasks made, each step with the
+  page as it was at that moment.
+
+<p align="center"><img src="examples/screenshots/run-page.png" alt="The saved copy of a run, opened from the file system with nothing running: a finding with its evidence accordion open, showing the four screenshots taken around it with the action and time under each" width="880" /></p>
+
+The live view serves the same document at `run` while the engine is still up,
+and sends you there when the run ends — so the address survives a refresh
+instead of a panel over a dead board.
+
+**What it costs.** Frames are pictures of the app under test, inside the tested
+project's folder, and the secret redaction that protects everything else the
+engine writes cannot read a picture. That is why it is off unless asked for,
+capped per session, and written only under `.scenescout/`, which ignores itself
+so `git add -A` in the tested project cannot pick the frames up. The reasoning is in
+[ADR 8](docs/adr/0008-a-recorded-run-is-evidence-and-must-be-asked-for.md).
+
+---
+
 ## 🔄 How a run works
 
 One curiosity loop, repeated — breadth first, then judgment where it matters:
@@ -242,7 +281,7 @@ Snapshots are cheap: re-snapshotting a route returns only *what changed*, with s
 | **Look** | `scout_snapshot` `scout_hover` `scout_screenshot` | Read the structured scene (diffed); reveal tooltips/hover cards; capture pixels only when needed |
 | **Act** | `scout_click` `scout_type` `scout_select` `scout_upload` `scout_press` `scout_scroll` `scout_navigate` `scout_back` `scout_run_plan` | Drive the UI like a user; `scout_run_plan` batches a whole mechanical sequence into one call |
 | **Assess** | `scout_design_audit` `scout_journey` | Score a page's craft/a11y/consistency; measure how hard a task is to complete |
-| **Record** | `scout_note` `scout_finding` `scout_resolve` `scout_report` | Curate durable notes; file deduped findings; mark fixes; generate the report |
+| **Record** | `scout_note` `scout_finding` `scout_resolve` `scout_report` | Curate durable notes; file deduped findings; mark fixes; write the report, and on a recorded run the whole run as one page |
 | **Close** | `scout_close` | Tear down one session or all |
 
 A few that punch above their weight:
@@ -290,6 +329,8 @@ A `🛡 WRITE-POLICY blocked` notice is the safety net doing its job, not an app
 - 👥 **A role capability matrix** — what each role could and couldn't reach.
 - 🧾 **A gap ledger** — everything *not* done, so the report is honest about its own coverage.
 
+`.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.
+
 👀 Watch a run live: `node dist/cli.js status <project-path>`.
 
 ---
@@ -514,8 +555,9 @@ src/
     design.ts       the design audit + page scoring
     memory.ts       cross-run storage + finding dedup
     report.ts       the gap ledger + report generation
+    replay.ts       the run as one page: steps, tasks, frames under each finding
     …               collector · dispatch · fixtures · authloss · reaper
-scripts/            the 12 test suites (smoke/ holds the real-browser ones)
+scripts/            the 14 test suites (smoke/ holds the real-browser ones)
 test-app/           fixtures for the real-browser smoke tests
 skills/scenescout/   the testing method (SKILL.md): a skill in Claude Code, served by the server everywhere else
 docs/adr/           why it's built this way

package/dist/engine/browser.js

@@ -10,6 +10,7 @@ import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGE
 import { OracleMonitor, formatViolations } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
+import { framePath, RECORD_MAX_FRAMES } from "./replay.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";
@@ -102,6 +103,8 @@ function actionabilityDiagnostic(message) {
  */
 /** 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;
+/** A frame for the record is worth a moment, not a stall: the action has already happened. */
+const RECORD_SHOT_TIMEOUT_MS = 2500;
 export class BrowserEngine {
     browser = null;
     context = null;
@@ -206,6 +209,57 @@ export class BrowserEngine {
     journey = null;
     /** The session's objective: the whole remit the agent was given at scout_attach. Empty when none was given. */
     sessionObjective = "";
+    /**
+     * Keep a frame of the page after each action, as evidence. Off by default:
+     * a recording is pictures of somebody's app sitting in their project
+     * folder, which is the rule ADR 7 otherwise holds ("no frame touches the
+     * disk"). QA work is what earns the exception — a report says what was
+     * checked, a recording shows it.
+     */
+    recording = false;
+    framesKept = 0;
+    /** How many frames could not be written. The first one says so in the log; the rest are counted. */
+    framesFailed = 0;
+    /**
+     * The frame for the step just taken, as a path relative to the memory
+     * directory, or undefined when this run is not recorded. Failing to write
+     * one must never fail the action: evidence is worth having, not worth
+     * losing a run over.
+     */
+    async recordFrame(action) {
+        const dir = this.memory?.dir;
+        if (!this.recording || !dir || this.framesKept >= RECORD_MAX_FRAMES)
+            return undefined;
+        const jpeg = await this.liveShot(RECORD_SHOT_TIMEOUT_MS);
+        if (!jpeg)
+            return undefined;
+        const rel = framePath(this.sessionKey, this.framesKept + 1, action);
+        try {
+            await fs.promises.mkdir(path.dirname(path.join(dir, rel)), { recursive: true });
+            await fs.promises.writeFile(path.join(dir, rel), jpeg);
+        }
+        catch (err) {
+            // A frame that cannot be written must not fail the action, but a run
+            // that keeps NOTHING — a read-only checkout, a full disk — would
+            // otherwise finish silently and produce a report with no evidence in
+            // it, which is the one thing recording exists to prevent. Said once,
+            // through the action log, so it reaches the live feed and the report.
+            this.framesFailed += 1;
+            if (this.framesFailed === 1) {
+                this.logAction({
+                    action: "record:failed",
+                    target: `no frame could be written under ${dir} (${err instanceof Error ? err.message : String(err)}); later failures are not repeated here`,
+                    url: this.page?.url() ?? "",
+                });
+            }
+            return undefined;
+        }
+        this.framesKept += 1;
+        if (this.framesKept === RECORD_MAX_FRAMES) {
+            this.logAction({ action: "record:full", target: `${RECORD_MAX_FRAMES} frames kept; later steps have none`, url: this.page?.url() ?? "" });
+        }
+        return rel;
+    }
     /**
      * The batch of actions running right now. Required before a tool may act
      * (task.ts), stated by the agent on the call or by a journey, and kept
@@ -352,6 +406,11 @@ export class BrowserEngine {
         }
         this.mode = opts.mode ?? "read-only";
         this.sessionObjective = (opts.objective ?? "").trim().replace(/\s+/g, " ").slice(0, 300);
+        this.recording = opts.record === true;
+        // A re-attached engine starts a new recording: numbering from where the
+        // last one stopped would run into the cap with frames it never took.
+        this.framesKept = 0;
+        this.framesFailed = 0;
         this.headed = opts.headed ?? false;
         this.blockedRequests = [];
         this.pendingCreations = new Set();
@@ -887,7 +946,8 @@ export class BrowserEngine {
                 blocked +
                 formatViolations(this.oracles.drain()));
         }
-        this.logAction({ action, target, url });
+        const frame = await this.recordFrame(action);
+        this.logAction({ action, target, url, ...(frame ? { frame } : {}) });
         await this.scanForInjections();
         const violations = this.oracles.drain();
         const mutations = this.drainMutations() + this.drainBlocked() + this.drainCreated();

package/dist/engine/live-page.js

@@ -54,7 +54,8 @@ export const LIVE_PAGE = `<!doctype html>
   #finished h2 { margin: 0 0 8px; font-size: 18px; }
   #finished p { margin: 0 0 8px; color: var(--muted); }
   #finished .where { font: 12px/1.6 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; overflow-wrap: anywhere; }
-  #finished button { margin-top: 8px; padding: 7px 14px; font-weight: 600; }
+  #finished .btn { display: inline-block; margin-top: 8px; padding: 8px 16px; font-weight: 600; text-decoration: none;
+    color: #fff; background: var(--accent); border-radius: 6px; }
   main { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 320px), 1fr)); gap: 12px; padding: 16px; }
   .card { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; overflow: hidden; display: flex; flex-direction: column; }
   .card.stuck { border-color: var(--stuck); }
@@ -128,6 +129,18 @@ export const LIVE_PAGE = `<!doctype html>
   #focus .bar .line { color: #cbd5e1; padding: 0; flex: 1 1 auto; }
   #focus .bar .line b { color: #fff; }
   #focus .stage { flex: 1 1 auto; min-height: 0; position: relative; }
+  #timeline { flex: 0 0 auto; display: flex; gap: 2px; overflow-x: auto; padding: 6px 0 2px; scrollbar-width: thin; }
+  #timeline button { flex: 0 0 auto; width: 16px; height: 26px; padding: 0; border: 0; border-radius: 3px; cursor: pointer;
+    background: rgba(230,233,238,.18); }
+  #timeline button.g0 { background: rgba(96,165,250,.75); } #timeline button.g1 { background: rgba(52,211,153,.75); }
+  #timeline button.g2 { background: rgba(251,191,36,.8); }  #timeline button.g3 { background: rgba(244,114,182,.75); }
+  #timeline button.framed { height: 34px; }
+  #timeline .none { color: var(--muted); font-size: 12px; align-self: center; }
+  #timeline button.bad { outline: 2px solid var(--stuck); outline-offset: -2px; }
+  #timeline button[aria-pressed="true"] { outline: 2px solid #fff; outline-offset: -2px; }
+  #focus .scrub { display: flex; align-items: center; gap: 10px; color: #cbd5e1; font-size: 12px; }
+  #focus .scrub b { color: #fff; }
+  #focus .scrub button { padding: 3px 10px; }
   #focus img { width: 100%; height: 100%; object-fit: contain; background: #000; border-radius: 6px; display: block; }
   #focus .none { position: absolute; inset: 0; display: none; align-items: center; justify-content: center; padding: 16px;
     color: #98a2b3; font-size: 13px; text-align: center; }
@@ -152,6 +165,18 @@ export const LIVE_PAGE = `<!doctype html>
   #report .doc details { margin: 8px 0; }
   #report .doc summary { cursor: pointer; color: var(--muted); }
   #report .doc .unset { color: var(--muted); font-style: italic; }
+  #report .doc details.evidence { margin: 10px 0 16px; padding: 8px 12px; background: var(--panel); border: 1px solid var(--line); border-radius: 6px; }
+  #report .doc details.evidence[open] summary { margin-bottom: 10px; }
+  #report .doc details.evidence figure { margin: 0 0 12px; }
+  #report .doc details.evidence .shots { display: flex; flex-wrap: wrap; gap: 14px; }
+  #report .doc details.evidence figure { flex: 1 1 320px; max-width: 440px; }
+  #report .doc details.evidence img { display: block; width: 100%; max-height: 280px; object-fit: cover; object-position: top;
+    border: 1px solid var(--line); border-radius: 4px; background: var(--shade); }
+  #report .doc details.evidence .gone img { display: none; }
+  #report .doc details.evidence .gone-note { display: none; margin: 0 0 4px; padding: 12px; border: 1px dashed var(--line);
+    border-radius: 4px; color: var(--muted); font-size: 12px; }
+  #report .doc details.evidence .gone .gone-note { display: block; }
+  #report .doc details.evidence figcaption { margin-top: 4px; font: 11px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; color: var(--muted); }
   @media (prefers-reduced-motion: no-preference) { .badge.running { animation: pulse 1.6s ease-in-out infinite; } }
   @keyframes pulse { 50% { opacity: .55; } }
 </style>
@@ -173,7 +198,7 @@ export const LIVE_PAGE = `<!doctype html>
   <h2>The run has finished</h2>
   <p>Its browsers are closed, so there is nothing left to watch. What it found is in the report.</p>
   <p class="where" id="finished-where" data-testid="live-finished-where"></p>
-  <button type="button" id="finished-report" data-testid="live-finished-report">Read the report</button>
+  <p><a class="btn" href="run" id="finished-run" data-testid="live-finished-run">Open the whole run</a></p>
 </div>
 <main id="grid"></main>
 <div id="report" role="dialog" aria-modal="true" aria-label="The run's report" data-testid="live-report-dialog">
@@ -196,6 +221,9 @@ export const LIVE_PAGE = `<!doctype html>
     <img id="focus-img" alt="">
     <span class="none">No frame available. The session's page may be closed, or not answering.</span>
   </div>
+  <div class="scrub"><span id="scrub-where" data-testid="live-scrub-where">Live</span><span class="spacer"></span>
+    <button type="button" id="scrub-live" data-testid="live-scrub-live" hidden>Back to live</button></div>
+  <div id="timeline" data-testid="live-timeline" role="group" aria-label="The steps this session took"></div>
   <div class="lower">
     <div class="feed" id="focus-feed" data-testid="live-focus-feed"></div>
     <aside class="brief" aria-label="What this session is doing" data-testid="live-focus-brief">
@@ -220,6 +248,10 @@ export const LIVE_PAGE = `<!doctype html>
   var eventsKey = '';
   var frames = {};
   var hoverTask = null;
+  // A step the viewer picked from the timeline: the stage shows its frame
+  // instead of the live page, so a run can be watched back while it runs.
+  var scrubbed = null;
+  var timelineLines = [];
   var reportOpen = false;
   var reportTimer = null;
   var reportProblem = null;
@@ -230,6 +262,10 @@ export const LIVE_PAGE = `<!doctype html>
   var reportShown = false;
   var reportFile = null;
   var reportMarkdown = null;
+  // What the panel last rendered, so an unchanged report is left alone.
+  var reportKey = null;
+  // Per-finding frames from api/report: empty unless the run was recorded.
+  var reportEvidence = [];
   var savedACopy = false;
   // A result that reads as a failure is shown in red.
   var BAD_RESULT = /error|fail|refus|block|violation|abandoned/i;
@@ -276,7 +312,7 @@ export const LIVE_PAGE = `<!doctype html>
       frames[d.session] = src;
       var card = cards[d.session];
       if (card && card.live) card.img.src = src;
-      if (focused === d.session) document.getElementById('focus-img').src = src;
+      if (focused === d.session && !scrubbed) document.getElementById('focus-img').src = src;
     });
     events.addEventListener('unavailable', function (e) {
       var d;
@@ -375,6 +411,35 @@ export const LIVE_PAGE = `<!doctype html>
     }
     if (last < text.length) node.appendChild(document.createTextNode(text.slice(last)));
   }
+  /**
+   * The frames recorded around one finding, as a closed accordion. Nothing is
+   * shown when the run was not recorded: the report reads the same as before.
+   */
+  function evidenceFor(id) {
+    var found = null;
+    reportEvidence.forEach(function (e) { if (e.id === id) found = e; });
+    if (!found || !found.frames.length) return null;
+    var box = el('details', 'evidence');
+    box.setAttribute('data-testid', 'live-report-evidence-' + id);
+    box.appendChild(el('summary', '', found.frames.length + (found.frames.length === 1 ? ' screenshot' : ' screenshots') + ' from around this finding'));
+    var shots = el('div', 'shots');
+    box.appendChild(shots);
+    found.frames.forEach(function (f) {
+      var fig = el('figure');
+      var img = el('img');
+      img.loading = 'lazy';
+      img.src = 'record/' + f.frame;
+      img.alt = f.action + ' ' + f.detail;
+      // A recording deleted since the run leaves a broken icon under a finding
+      // that still counts it as evidence. Say which it is.
+      img.addEventListener('error', function () { fig.classList.add('gone'); });
+      fig.appendChild(img);
+      fig.appendChild(el('figcaption', '', clock(f.at) + ' · ' + f.action + ' · ' + f.detail));
+      fig.appendChild(el('p', 'gone-note', 'This frame is no longer in ' + f.frame.replace(/\\/[^/]*$/, '') + '.'));
+      shots.appendChild(fig);
+    });
+    return box;
+  }
   function renderMarkdown(root, md) {
     root.textContent = '';
     var lines = md.split('\\n');
@@ -390,14 +455,23 @@ export const LIVE_PAGE = `<!doctype html>
     }
     function list(tag, re) {
       var box = el(tag);
+      var ids = [];
       var m;
       while (i < lines.length && (m = re.exec(lines[i]))) {
         var li = el('li');
         inline(li, m[1]);
         box.appendChild(li);
+        // A finding names its id on its first bullet; the frames recorded
+        // around it hang under that list, so the proof sits with the claim.
+        var id = /^\\*\\*Id:\\*\\* \`([^\`]+)\`/.exec(m[1]);
+        if (id) ids.push(id[1]);
         i += 1;
       }
       container.appendChild(box);
+      ids.forEach(function (id) {
+        var shots = evidenceFor(id);
+        if (shots) container.appendChild(shots);
+      });
     }
     while (i < lines.length) {
       var line = lines[i];
@@ -482,8 +556,26 @@ export const LIVE_PAGE = `<!doctype html>
           return;
         }
         reportMarkdown = d.markdown;
+        reportEvidence = d.evidence || [];
         meta.textContent = (finished ? 'as the run left it at ' : 'as the run stands at ') + clock(d.at) + ' · ' + whereItIs();
+        // The report is re-read every few seconds while the run goes on.
+        // Re-rendering an unchanged document threw away what the reader was
+        // doing with it: an opened accordion shut itself, and the page jumped
+        // back to the top, every five seconds.
+        var key = d.markdown + '\\u0000' + JSON.stringify(reportEvidence);
+        if (key === reportKey) return;
+        var open = {};
+        var was = doc.querySelectorAll('details[open][data-testid]');
+        for (var k = 0; k < was.length; k += 1) open[was[k].getAttribute('data-testid')] = true;
+        var top = doc.parentNode ? doc.parentNode.scrollTop : 0;
+        reportKey = key;
         renderMarkdown(doc, d.markdown);
+        // A finding whose evidence the reader had open stays open through a change.
+        Object.keys(open).forEach(function (id) {
+          var node = doc.querySelector('details[data-testid="' + id + '"]');
+          if (node) node.open = true;
+        });
+        if (doc.parentNode) doc.parentNode.scrollTop = top;
       })
       .catch(function (err) {
         // The last rendering stays; with none, say why there is nothing to read.
@@ -531,6 +623,65 @@ export const LIVE_PAGE = `<!doctype html>
     document.getElementById('report-open').focus();
   }
 
+  // One tick per step, coloured by the task it served: a run can be scrolled
+  // back through while it is still going, and a step with a frame is taller.
+  function renderTimeline(lines) {
+    // Kept so a re-render (picking a step, say) draws the same run back. The
+    // status poll carries six lines and the close-up three hundred: redrawing
+    // from whichever was nearest to hand shrank the timeline to six ticks.
+    timelineLines = lines || timelineLines;
+    lines = timelineLines;
+    var node = document.getElementById('timeline');
+    var atEnd = node.scrollLeft + node.clientWidth >= node.scrollWidth - 8;
+    node.textContent = '';
+    var groups = 0;
+    var last = null;
+    (lines || []).forEach(function (line) {
+      var task = line.task || '';
+      if (task && task !== last) groups += 1;
+      last = task;
+      var tick = el('button');
+      tick.type = 'button';
+      tick.className = (task ? 'g' + ((groups - 1) % 4) : '') + (line.frame ? ' framed' : '') + (BAD_RESULT.test(line.result || '') ? ' bad' : '');
+      tick.title = clock(line.at) + '  ' + line.action + (line.target ? ' ' + line.target : '') + (task ? '\\n' + task : '');
+      tick.setAttribute('aria-label', tick.title);
+      tick.setAttribute('aria-pressed', scrubbed && scrubbed.at === line.at && scrubbed.action === line.action ? 'true' : 'false');
+      tick.addEventListener('click', function () { showStep(line); });
+      node.appendChild(tick);
+    });
+    if (atEnd) node.scrollLeft = node.scrollWidth;
+  }
+
+  // Show one step: its frame if the run was recorded, and what it was doing.
+  function showStep(line) {
+    var where = document.getElementById('scrub-where');
+    var back = document.getElementById('scrub-live');
+    scrubbed = line;
+    back.hidden = false;
+    if (!line.frame) {
+      where.textContent = clock(line.at) + ' ' + line.action + ' — this run kept no frame for that step';
+      // Leaving the live frame up under that caption is the most misleading
+      // state this page can reach: it reads as the page at that moment.
+      document.getElementById('focus-img').removeAttribute('src');
+      document.getElementById('focus-stage').classList.add('empty');
+      renderTimeline(null);
+      return;
+    }
+    document.getElementById('focus-stage').classList.remove('empty');
+    document.getElementById('focus-img').src = 'record/' + line.frame;
+    where.textContent = clock(line.at) + ' ' + line.action + (line.task ? ' · ' + line.task : '');
+    renderTimeline(null);
+  }
+
+  function backToLive() {
+    scrubbed = null;
+    document.getElementById('scrub-where').textContent = 'Live';
+    document.getElementById('scrub-live').hidden = true;
+    if (focused) document.getElementById('focus-img').src = frames[focused] || shotUrl(focused);
+    // Otherwise the step just left keeps its outline until the next full feed.
+    renderTimeline(null);
+  }
+
   // Built with textContent only: an action's target is text from the app under test.
   function renderFeed(node, lines, onGroup) {
     // Measured before the node is emptied: an empty node always reads as scrolled to its end.
@@ -589,10 +740,17 @@ export const LIVE_PAGE = `<!doctype html>
 
   function openFocus(name) {
     focused = name;
+    scrubbed = null;
+    // The ticks belong to the session just left; showing them under this one's
+    // name, and playing its frames when one is clicked, is worse than none.
+    timelineLines = [];
+    renderTimeline([]);
     document.getElementById('focus-stage').classList.remove('empty');
     document.getElementById('focus-name').textContent = name;
     document.getElementById('focus-img').alt = 'Live view of ' + name;
     document.getElementById('focus-img').src = frames[name] || shotUrl(name);
+    document.getElementById('scrub-where').textContent = 'Live';
+    document.getElementById('scrub-live').hidden = true;
     document.getElementById('focus').classList.add('open');
     hoverTask = null;
     renderFeed(document.getElementById('focus-feed'), (latest[name] || {}).feed, showTask);
@@ -612,8 +770,21 @@ export const LIVE_PAGE = `<!doctype html>
   function loadFullFeed(name) {
     fetch('api/activity?session=' + encodeURIComponent(name), { cache: 'no-store' })
       .then(function (r) { return r.ok ? r.json() : null; })
-      .then(function (d) { if (d && focused === d.session) renderFeed(document.getElementById('focus-feed'), d.feed, showTask); })
-      .catch(function () { /* the short feed from the last poll stays on screen */ });
+      .then(function (d) {
+        if (!d || focused !== d.session) return;
+        renderFeed(document.getElementById('focus-feed'), d.feed, showTask);
+        renderTimeline(d.feed);
+      })
+      .catch(function () {
+        // The short feed from the last poll stays on screen, but the timeline
+        // is drawn from this call alone: an empty strip would read as a
+        // session that did nothing.
+        if (!timelineLines.length) {
+          var strip = document.getElementById('timeline');
+          strip.textContent = '';
+          strip.appendChild(el('span', 'none', 'The step list could not be loaded. Trying again.'));
+        }
+      });
   }
 
   function setBrief(id, text, unset) {
@@ -685,7 +856,10 @@ export const LIVE_PAGE = `<!doctype html>
     });
     syncEvents();
     reportFile = snap.report || reportFile;
-    if (snap.sessions.length > 0) sawRun = true;
+    // A viewer who opens the board after the last browser closed never sees a
+    // session, but the engine only names a report file once one has attached:
+    // that is a finished run, not a board waiting for its first attach.
+    if (snap.sessions.length > 0 || snap.report) sawRun = true;
     finished = sawRun && snap.sessions.length === 0;
     document.getElementById('empty').style.display = snap.sessions.length || finished ? 'none' : 'block';
     document.getElementById('finished').classList.toggle('open', finished);
@@ -693,10 +867,18 @@ export const LIVE_PAGE = `<!doctype html>
       var where = document.getElementById('finished-where');
       where.textContent = whereItIs();
       where.className = 'where' + (reportFile && reportFile.written ? '' : ' unset');
-      // The moment somebody wants the report is the moment the run ends: show it.
+      // The moment somebody wants the run is the moment it ends, and a panel
+      // over a dead board is lost on the next refresh. The run has its own
+      // address; go there, so the address IS the report from then on.
       if (!reportShown) {
         reportShown = true;
-        if (!reportOpen) openReport();
+        // The run has its own address, and going there means a refresh shows
+        // the report instead of a dead board. Ask whether it is there first:
+        // a run with no page to serve would otherwise land on a 404, and the
+        // panel below is the only other copy.
+        fetch('run', { cache: 'no-store' })
+          .then(function (r) { if (r.ok) location.href = 'run'; else openReport(); })
+          .catch(function () { openReport(); });
       }
     }
     document.getElementById('engine').textContent = 'engine pid ' + snap.pid + ' · v' + snap.version;
@@ -719,14 +901,22 @@ export const LIVE_PAGE = `<!doctype html>
     Object.keys(cards).forEach(function (name) { setLive(cards[name], streamAll); });
   });
   // A session with nothing to show answers 503; say so rather than leaving a broken-image icon.
-  document.getElementById('focus-img').addEventListener('error', function () { document.getElementById('focus-stage').classList.add('empty'); });
+  document.getElementById('focus-img').addEventListener('error', function () {
+    document.getElementById('focus-stage').classList.add('empty');
+    // A live session with nothing to show and a recorded frame that has since
+    // been deleted look identical here; only the second is worth explaining.
+    if (scrubbed) {
+      document.getElementById('scrub-where').textContent =
+        clock(scrubbed.at) + ' ' + scrubbed.action + ' — its frame could not be loaded; the recording may have been removed';
+    }
+  });
   document.getElementById('focus-img').addEventListener('load', function () { document.getElementById('focus-stage').classList.remove('empty'); });
   document.getElementById('focus-close').addEventListener('click', closeFocus);
   // A re-rendered feed replaces the group under the pointer without a mouseleave; leaving the feed itself still resets.
   document.getElementById('focus-feed').addEventListener('mouseleave', function () { showTask(null); });
   document.getElementById('focus').addEventListener('click', function (e) { if (e.target === this) closeFocus(); });
+  document.getElementById('scrub-live').addEventListener('click', backToLive);
   document.getElementById('report-open').addEventListener('click', openReport);
-  document.getElementById('finished-report').addEventListener('click', openReport);
   document.getElementById('report-save').addEventListener('click', saveACopy);
   // Closing the tab on a finished run whose report was never written to disk
   // throws the only copy away. The browser shows its own confirm/dismiss, and

package/dist/engine/live.js

@@ -80,6 +80,8 @@ export function feedForSession(log, session, limit, redact = (s) => s) {
             line.target = e.target;
         if (e.result !== undefined)
             line.result = e.result;
+        if (e.frame !== undefined)
+            line.frame = e.frame;
         if (task !== undefined)
             line.task = task;
         lines.push(line);
@@ -90,8 +92,13 @@ export function feedForSession(log, session, limit, redact = (s) => s) {
 }
 /** How many feed lines a status poll carries per session. Enough to read the last move at a glance; the close-up asks for more. */
 export const FEED_LINES = 6;
-/** The cap the close-up gets. A long run's log is thousands of lines and none of it needs to reach the page. */
-export const FEED_LINES_MAX = 60;
+/**
+ * The cap the close-up gets. A long run's log is thousands of lines and none
+ * of it needs to reach the page — but this is also what the timeline is drawn
+ * from, and a timeline that only reaches back a minute cannot be scrubbed.
+ * The whole run, every step of it, is the page at `run`.
+ */
+export const FEED_LINES_MAX = 300;
 /**
  * How long a call may run before the session is judged wedged rather than
  * busy, when the entry does not carry the tool's own watchdog budget (an
@@ -251,6 +258,13 @@ export function watchTarget(input) {
         };
     return { url: `http://127.0.0.1:${port}/${clean}/` };
 }
+/** What `run` says when there is no run to show: a page, because a person navigated here. */
+export const NO_RUN_PAGE = '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>No run to show</title>' +
+    "<style>body{margin:0;display:grid;place-items:center;min-height:100vh;background:#0e1116;color:#e6e9ee;" +
+    'font:16px/1.6 system-ui,-apple-system,"Segoe UI",sans-serif}main{max-width:34rem;padding:2rem;text-align:center}' +
+    "a{color:#7aa2ff}</style></head><body><main><h1>Nothing to show yet</h1>" +
+    "<p>This run has not produced a report. It may not have started, or its engine may have exited since you opened this page.</p>" +
+    '<p><a href="./">Back to the live board</a></p></main></body></html>';
 const LIVE_CSP = "default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; base-uri 'none'; form-action 'none'";
 const BOUNDARY = "scenescoutframe";
 /** A thumbnail younger than this is served again instead of taking a new one. */
@@ -381,6 +395,30 @@ export class LiveServer {
                 return this.send(res, 404, "no run attached");
             return this.send(res, 200, JSON.stringify(report), "application/json; charset=utf-8");
         }
+        if (route === "run" && !name) {
+            const doc = this.provider.replay();
+            // Somebody clicked a button or refreshed a bookmark to get here, so an
+            // answer they cannot read is worse than no link at all.
+            if (!doc)
+                return this.send(res, 404, NO_RUN_PAGE, "text/html; charset=utf-8", { "Content-Security-Policy": LIVE_CSP });
+            return this.send(res, 200, doc, "text/html; charset=utf-8", { "Content-Security-Policy": LIVE_CSP });
+        }
+        if (route === "record" && name) {
+            // A recorded frame, by the path the feed gave. The provider decides what
+            // exists; nothing here builds a filesystem path from the request.
+            const rel = parts.slice(2).join("/");
+            let asked;
+            try {
+                asked = decodeURIComponent(rel);
+            }
+            catch {
+                return this.send(res, 404, "not found");
+            }
+            const jpeg = await this.provider.frame(asked);
+            if (!jpeg)
+                return this.send(res, 404, "no such frame");
+            return this.send(res, 200, jpeg, "image/jpeg", { "Content-Length": jpeg.length, "Cache-Control": "private, max-age=3600" });
+        }
         if (route === "events" && !name) {
             const wanted = this.param(req, "sessions");
             if (wanted === null)

package/dist/engine/replay.js

@@ -0,0 +1,348 @@
+/**
+ * The run, as one file that outlives it.
+ *
+ * The live view dies with the engine: its address is a port in a process, so
+ * refreshing after a run is over gets nothing. This builds a self-contained
+ * HTML document instead — the report, and every session's steps grouped by
+ * the task they served — written next to report.md. It opens from the file
+ * system with no server, works offline, and can be handed to somebody who was
+ * never watching.
+ *
+ * Frames appear beside the steps only when the run was recorded
+ * (`scout_attach {record:true}`), which is off by default: a recording is
+ * pictures of somebody's app sitting in their project folder, and ADR 7's
+ * "no frame touches the disk" is the rule it deliberately relaxes. The
+ * document is built the same way either way; a step with no frame simply
+ * shows none.
+ *
+ * Everything here is pure string work — no browser, no filesystem — so the
+ * escaping and the grouping are table-tested.
+ */
+import path from "node:path";
+/** Most frames one recorded session keeps. A long run is thousands of actions, and a project folder is not a video store. */
+export const RECORD_MAX_FRAMES = 600;
+/**
+ * Where a recorded frame is stored, relative to the memory directory — and
+ * the path the live view serves it at, so it is always written with forward
+ * slashes. The session name is the agent's and the action the tool's, so both
+ * are reduced to a plain file name here: a session called `../../etc` decides
+ * nothing about where the engine writes.
+ */
+export function framePath(session, index, action) {
+    const plain = (text, fallback) => text
+        .replace(/[^a-z0-9._-]+/gi, "-")
+        .replace(/^[.-]+/, "")
+        .slice(0, 60) || fallback;
+    return `recordings/${plain(session, "session")}/${String(index).padStart(4, "0")}-${plain(action, "step")}.jpg`;
+}
+/**
+ * The file a viewer's frame request names, or null when it is not one of this
+ * run's frames. The path comes from a browser and may be anything, so it is
+ * resolved and then required to still be under the recordings directory —
+ * `..`, an absolute path and a sibling directory whose name merely starts the
+ * same way are all refused. The one filesystem rule in the frame route, kept
+ * here so it can be table-tested rather than reached only through HTTP.
+ */
+export function resolveFrame(root, relPath) {
+    if (!relPath)
+        return null;
+    const inside = relPath.replace(/^recordings[\\/]/, "");
+    if (!inside || inside.includes("\0"))
+        return null;
+    // Both sides resolved: on Windows `path.resolve` prefixes the drive, so
+    // comparing its output against a root that has none rejects every frame.
+    const base = path.resolve(root);
+    const file = path.resolve(base, inside);
+    return file.startsWith(base + path.sep) ? file : null;
+}
+/** Text from the app under test reaches this document, so nothing is interpolated unescaped. */
+export function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+/**
+ * A session's steps in the blocks its tasks made. Consecutive steps that
+ * served the same task are one block, so the document reads the way the live
+ * feed did: a change of task is a change of block, and of colour.
+ */
+export function taskBlocks(steps) {
+    const blocks = [];
+    for (const step of steps) {
+        const task = step.task ?? null;
+        const last = blocks[blocks.length - 1];
+        if (!last || last.task !== task)
+            blocks.push({ task, steps: [step] });
+        else
+            last.steps.push(step);
+    }
+    return blocks;
+}
+/** The viewer's own clock is not this document's to assume; times are shown as they were logged. */
+function clock(iso) {
+    const at = iso.length >= 19 ? iso.slice(11, 19) : iso;
+    return at;
+}
+/**
+ * When the document was written. The log is UTC and this page may be opened
+ * anywhere, so it says which clock it is quoting rather than implying the
+ * reader's own.
+ */
+function stamp(iso) {
+    return iso.length >= 16 ? `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC` : iso;
+}
+/**
+ * What an image that will not load does. This page is meant to be handed on,
+ * and a copy sent without its `recordings/` folder would otherwise show a row
+ * of broken icons under a finding that still counts them as evidence.
+ */
+const GONE = `onerror="this.parentNode.classList.add('gone')"`;
+/** A result that reads as a failure, so a step that went wrong is visible without reading every line. */
+const BAD_RESULT = /error|fail|refus|block|violation|abandoned/i;
+function renderStep(step, framePrefix = "", savedAt = "") {
+    const detail = [step.target, step.result ? `→ ${step.result}` : ""].filter(Boolean).join(" ") || step.url || "";
+    const bad = BAD_RESULT.test(step.result ?? "") ? " bad" : "";
+    const frame = step.frame
+        ? `<a class="frame" href="${escapeHtml(framePrefix + step.frame)}" target="_blank" rel="noreferrer"><img loading="lazy" ${GONE} src="${escapeHtml(framePrefix + step.frame)}" alt="What the page showed at this step"></a>`
+        : "";
+    const where = savedAt && step.frame ? `<p class="onDisk">${escapeHtml(savedAt + "/" + step.frame)}</p>` : "";
+    return (`<li class="step"><div class="row"><span class="t">${escapeHtml(clock(step.at))}</span>` +
+        `<span class="a${bad}">${escapeHtml(step.action)}</span>` +
+        `<span class="d" title="${escapeHtml([step.target, step.result, step.url].filter(Boolean).join(" · "))}">${escapeHtml(detail)}</span></div>${frame}${where}</li>`);
+}
+function renderSession(s, index, framePrefix = "", savedAt = "") {
+    const blocks = taskBlocks(s.steps);
+    const body = blocks
+        .map((b, i) => {
+        const head = b.task ? `<p class="task">${escapeHtml(b.task)}</p>` : `<p class="task none">No task stated for these</p>`;
+        return `<section class="block g${i % 4}">${head}<ol class="steps">${b.steps.map((step) => renderStep(step, framePrefix, savedAt)).join("")}</ol></section>`;
+    })
+        .join("");
+    const framed = s.steps.filter((x) => x.frame).length;
+    return (`<details class="session"${index === 0 ? " open" : ""}><summary><b>${escapeHtml(s.session)}</b> <span class="role">${escapeHtml(s.role)}</span>` +
+        `<span class="count">${s.steps.length} steps · ${blocks.length} task${blocks.length === 1 ? "" : "s"}${framed ? ` · ${framed} frames` : ""}</span></summary>` +
+        (s.objective ? `<p class="objective">${escapeHtml(s.objective)}</p>` : "") +
+        body +
+        `</details>`);
+}
+/**
+ * The steps that were on screen just before a finding was filed. The report's
+ * own repro trace says what happened; on a recorded run these show it.
+ */
+export function evidenceFor(steps, foundAt, most = 4) {
+    const before = steps.filter((x) => x.frame && x.at <= foundAt);
+    return before.slice(-most).map((x) => ({
+        at: x.at,
+        action: x.action,
+        detail: [x.target, x.result ? `→ ${x.result}` : ""].filter(Boolean).join(" ") || x.url || "",
+        frame: x.frame,
+    }));
+}
+function renderEvidence(e, framePrefix = "", savedAt = "") {
+    if (e.frames.length === 0)
+        return "";
+    const shots = e.frames
+        .map((f) => `<figure><img loading="lazy" ${GONE} src="${escapeHtml(framePrefix + f.frame)}" alt="The page when this step ran">` +
+        `<p class="gone-note">This frame is not beside this file. Frames live in the run's <code>recordings/</code> folder, which travels with it.</p>` +
+        `<figcaption>${escapeHtml(clock(f.at))} <b>${escapeHtml(f.action)}</b> ${escapeHtml(f.detail)}` +
+        (savedAt ? `<span class="onDisk">${escapeHtml(savedAt + "/" + f.frame)}</span>` : "") +
+        `</figcaption></figure>`)
+        .join("");
+    return `<details class="evidence"><summary>Evidence — the ${e.frames.length} step${e.frames.length === 1 ? "" : "s"} on screen before this was filed</summary><div class="shots">${shots}</div></details>`;
+}
+/**
+ * The report's markdown as elements. A deliberately small subset — headings,
+ * tables, lists, code fences, the report's own <details> repro blocks — built
+ * by escaping every piece of text, because finding titles and element names
+ * come from the app under test.
+ */
+export function renderMarkdown(md, evidence = [], framePrefix = "", savedAt = "") {
+    const out = [];
+    const lines = md.split("\n");
+    let i = 0;
+    let para = [];
+    const inline = (text) => escapeHtml(text)
+        .replace(/`([^`]+)`/g, "<code>$1</code>")
+        .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+    const flush = () => {
+        if (para.length)
+            out.push(`<p>${inline(para.join(" "))}</p>`);
+        para = [];
+    };
+    while (i < lines.length) {
+        const line = lines[i];
+        let m;
+        if (/^```/.test(line)) {
+            flush();
+            const code = [];
+            i += 1;
+            while (i < lines.length && !/^```/.test(lines[i])) {
+                code.push(lines[i]);
+                i += 1;
+            }
+            i += 1;
+            out.push(`<pre><code>${escapeHtml(code.join("\n"))}</code></pre>`);
+        }
+        else if ((m = /^(#{1,6}) (.*)$/.exec(line))) {
+            flush();
+            const level = Math.min(6, m[1].length + 1);
+            out.push(`<h${level}>${inline(m[2])}</h${level}>`);
+            i += 1;
+        }
+        else if ((m = /^<details><summary>(.*)<\/summary>$/.exec(line))) {
+            flush();
+            out.push(`<details><summary>${inline(m[1])}</summary>`);
+            i += 1;
+        }
+        else if (/^<\/details>$/.test(line)) {
+            flush();
+            out.push(`</details>`);
+            i += 1;
+        }
+        else if (/^\|/.test(line)) {
+            flush();
+            const rows = [];
+            let first = true;
+            while (i < lines.length && /^\|/.test(lines[i])) {
+                const row = lines[i];
+                i += 1;
+                if (/^\|(\s*:?-+:?\s*\|)+\s*$/.test(row))
+                    continue;
+                const cells = row
+                    .replace(/^\||\|\s*$/g, "")
+                    .split("|")
+                    .map((c) => `<${first ? "th" : "td"}>${inline(c.trim())}</${first ? "th" : "td"}>`);
+                rows.push(`<tr>${cells.join("")}</tr>`);
+                first = false;
+            }
+            out.push(`<table>${rows.join("")}</table>`);
+        }
+        else if (/^\s*[-*] /.test(line)) {
+            flush();
+            const items = [];
+            // A finding's id sits in this list; its evidence goes straight under it,
+            // which is where a reader is when they ask "show me".
+            let found;
+            while (i < lines.length && (m = /^\s*[-*] (.*)$/.exec(lines[i]))) {
+                const id = /\*\*Id:\*\* `([0-9a-f]+)`/.exec(m[1])?.[1];
+                if (id)
+                    found = evidence.find((e) => e.id === id);
+                items.push(`<li>${inline(m[1])}</li>`);
+                i += 1;
+            }
+            out.push(`<ul>${items.join("")}</ul>`);
+            if (found)
+                out.push(renderEvidence(found, framePrefix, savedAt));
+        }
+        else if (/^\d+\. /.test(line)) {
+            flush();
+            const items = [];
+            while (i < lines.length && (m = /^\d+\. (.*)$/.exec(lines[i]))) {
+                items.push(`<li>${inline(m[1])}</li>`);
+                i += 1;
+            }
+            out.push(`<ol>${items.join("")}</ol>`);
+        }
+        else if (line.trim() === "") {
+            flush();
+            i += 1;
+        }
+        else {
+            para.push(line);
+            i += 1;
+        }
+    }
+    flush();
+    return out.join("\n");
+}
+const STYLE = `
+:root { color-scheme: light dark; --bg:#f6f7f9; --panel:#fff; --line:#d9dde3; --text:#15181d; --muted:#5d6673; --accent:#2563eb; --bad:#b91c1c; }
+@media (prefers-color-scheme: dark) { :root { --bg:#0e1116; --panel:#161a21; --line:#2a303a; --text:#e6e9ee; --muted:#98a2b3; --accent:#7aa2ff; --bad:#fca5a5; } }
+* { box-sizing: border-box; }
+body { margin:0; background:var(--bg); color:var(--text); font:15px/1.55 system-ui,-apple-system,"Segoe UI",sans-serif; }
+header { position:sticky; top:0; z-index:2; display:flex; flex-wrap:wrap; gap:8px 16px; align-items:baseline; padding:14px 20px; background:var(--panel); border-bottom:1px solid var(--line); }
+header h1 { margin:0; font-size:17px; }
+header .meta { color:var(--muted); font-size:13px; }
+nav { margin-left:auto; display:flex; gap:12px; font-size:14px; }
+nav a { color:var(--accent); }
+main { max-width:1000px; margin:0 auto; padding:24px 20px 64px; }
+h2 { font-size:21px; margin:32px 0 12px; padding-top:20px; border-top:1px solid var(--line); }
+h3 { font-size:17px; margin:24px 0 8px; }
+h4 { font-size:15px; margin:20px 0 6px; }
+table { border-collapse:collapse; margin:10px 0 16px; font-size:13px; }
+th, td { border:1px solid var(--line); padding:5px 9px; text-align:left; vertical-align:top; }
+th { background:var(--panel); }
+code { font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; background:var(--panel); border:1px solid var(--line); border-radius:4px; padding:0 4px; }
+pre { padding:12px; background:var(--panel); border:1px solid var(--line); border-radius:6px; overflow-x:auto; }
+pre code { border:0; padding:0; background:none; }
+details.session { background:var(--panel); border:1px solid var(--line); border-radius:8px; margin:12px 0; padding:10px 14px; }
+details.session > summary { cursor:pointer; font-size:15px; display:flex; gap:10px; align-items:baseline; }
+details.session .role { color:var(--muted); font-size:13px; }
+details.session .count { margin-left:auto; color:var(--muted); font-size:12px; }
+.objective { margin:8px 0 14px; color:var(--muted); }
+.block { border-left:2px solid transparent; border-radius:4px; padding:6px 10px; margin:8px 0; }
+.block.g0 { background:rgba(96,165,250,.22); border-color:rgba(96,165,250,.85); }
+.block.g1 { background:rgba(52,211,153,.22); border-color:rgba(52,211,153,.85); }
+.block.g2 { background:rgba(251,191,36,.24); border-color:rgba(251,191,36,.9); }
+.block.g3 { background:rgba(244,114,182,.22); border-color:rgba(244,114,182,.85); }
+@media (prefers-color-scheme: light) {
+  .block.g0 { background:rgba(37,99,235,.13); } .block.g1 { background:rgba(5,150,105,.13); }
+  .block.g2 { background:rgba(217,119,6,.15); } .block.g3 { background:rgba(219,39,119,.12); }
+}
+.task { margin:2px 0 8px; font-weight:600; }
+.task.none { font-weight:400; color:var(--muted); font-style:italic; }
+ol.steps { list-style:none; margin:0; padding:0; }
+.step { margin:0 0 2px; }
+.step .row { display:flex; gap:8px; font:12px/1.6 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+.step .t { color:var(--muted); flex:0 0 auto; }
+.step .a { font-weight:600; flex:0 0 auto; }
+.step .a.bad { color:var(--bad); }
+.step .d { color:var(--muted); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.step .frame { display:block; margin:4px 0 10px; }
+.step .frame img { max-width:min(100%,720px); max-height:360px; object-fit:cover; object-position:top; border:1px solid var(--line); border-radius:6px; display:block; }
+details.evidence { margin:6px 0 18px; padding:8px 12px; background:var(--panel); border:1px solid var(--line); border-radius:8px; }
+details.evidence > summary { cursor:pointer; color:var(--muted); font-size:13px; }
+details.evidence .shots { display:flex; flex-wrap:wrap; gap:14px; margin-top:12px; }
+details.evidence figure { margin:0; max-width:min(100%,460px); }
+details.evidence img { width:100%; max-height:300px; object-fit:cover; object-position:top; border:1px solid var(--line); border-radius:6px; display:block; background:var(--panel); }
+.onDisk { display:block; margin-top:4px; color:var(--muted); font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
+header .served { flex:1 1 100%; margin:6px 0 0; color:var(--muted); font-size:12px; }
+header .served code { font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
+.gone-note { display:none; margin:0; padding:14px; border:1px dashed var(--line); border-radius:6px; color:var(--muted); font-size:12px; }
+figure.gone .gone-note, a.gone .gone-note { display:block; }
+figure.gone img, a.gone img { display:none; }
+a.frame.gone { display:block; max-width:min(100%,720px); }
+details.evidence figcaption { margin-top:4px; color:var(--muted); font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
+`;
+/** The whole document: one file, no external assets, opens from the file system. */
+export function buildReplayHtml(input) {
+    const framed = input.sessions.some((s) => s.steps.some((x) => x.frame));
+    const prefix = input.framePrefix ?? "";
+    const savedAt = input.savedAt ?? "";
+    const sessions = input.sessions.map((s, i) => renderSession(s, i, prefix, savedAt)).join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SceneScout run — ${escapeHtml(input.project)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header>
+  <h1>SceneScout run</h1>
+  <span class="meta">${escapeHtml(input.project)} · written ${escapeHtml(stamp(input.at))}${input.version ? ` · v${escapeHtml(input.version)}` : ""}</span>
+  ${savedAt ? `<p class="served">This page is served by the engine and goes when it does. The copy that stays is <code>${escapeHtml(savedAt)}/report.html</code>, beside the frames it shows.</p>` : ""}
+  <nav><a href="#report">Report</a><a href="#steps">Steps</a></nav>
+</header>
+<main>
+<h2 id="report">Report</h2>
+${renderMarkdown(input.markdown, input.evidence ?? [], prefix, savedAt)}
+<h2 id="steps">What each session did</h2>
+<p class="objective">Every action, in the blocks its tasks made. ${framed
+        ? "Each step shows the page as it was; click a frame to open it full size."
+        : "This run was not recorded, so there are no frames — attach with record:true to keep them."}</p>
+${sessions || "<p>No session recorded any action.</p>"}
+</main>
+</body>
+</html>
+`;
+}

package/dist/engine/report.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { SHARED_CHROME_ROUTE } from "./memory.js";
+import { feedForSession } from "./live.js";
+import { buildReplayHtml, evidenceFor } from "./replay.js";
 function playwrightSkeleton(f) {
     const routeClass = f.state.split("#")[0].split("?")[0];
     let gotoPath = routeClass;
@@ -56,6 +58,66 @@ function violationRollup(oracleLog) {
 }
 const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
 const SEVERITY_ICON = { high: "🔴", medium: "🟠", low: "🟡" };
+/**
+ * What to call the project in a document meant to be handed on. The memory
+ * directory's absolute path names a person's home directory and often the
+ * machine it ran on; the project's own folder name says which project it was
+ * without any of that.
+ */
+function projectName(dir) {
+    const parent = path.dirname(dir);
+    return path.basename(parent) || path.basename(dir) || "project";
+}
+/** Every session that did anything, with its steps in order — what the HTML replays. */
+function replaySessions(memory) {
+    const names = [...new Set(memory.actionLog.map((e) => e.session ?? "default"))];
+    return names.map((session) => ({
+        session,
+        // The role a session ran as is not on the log's entries; until it is, the
+        // session's own name is the honest label rather than a guess from coverage.
+        role: "",
+        // No redactor: the log is redacted as it is WRITTEN (memory.logAction
+        // covers url, target and result), so what is stored is already clean.
+        // Filtering again here would run a regex over every step of a long run to
+        // find what cannot be there. `replay-redaction` in contract-test pins it.
+        steps: feedForSession(memory.actionLog, session, Number.MAX_SAFE_INTEGER),
+    }));
+}
+/** The frames that were on screen while each finding was being found. */
+export function findingEvidence(memory, sessions) {
+    const all = sessions.flatMap((s) => s.steps).sort((a, b) => a.at.localeCompare(b.at));
+    return memory.findings
+        .map((f) => {
+        // The session that filed it, where it said so: with three browsers
+        // running at once, the run's whole log interleaves them, and the steps
+        // before a finding would come from whichever lane acted last.
+        const own = f.session ? sessions.find((s) => s.session === f.session) : undefined;
+        return { id: f.id, frames: evidenceFor(own ? own.steps : all, f.foundAt) };
+    })
+        .filter((e) => e.frames.length > 0);
+}
+/**
+ * The whole run as one page, for the live view to serve at its own address.
+ * Frames go through the view's own route, since the browser is reading this
+ * over HTTP rather than from the folder the frames live in.
+ */
+export function replayDocument(memory, markdown, version = "") {
+    const sessions = replaySessions(memory);
+    return buildReplayHtml({
+        markdown,
+        sessions,
+        evidence: findingEvidence(memory, sessions),
+        project: projectName(memory.dir),
+        at: new Date().toISOString(),
+        version,
+        framePrefix: "record/",
+        savedAt: memory.dir,
+    });
+}
+/** What the live view shows under each finding on a recorded run: the frames it was found on. */
+export function reportEvidence(memory) {
+    return findingEvidence(memory, replaySessions(memory));
+}
 /**
  * Split an element key into words. Keys are `tid:some-test-id` or `role:name`,
  * and testids come in every casing convention there is — a `\b`-anchored regex
@@ -492,13 +554,51 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
     }
     const markdown = lines.join("\n");
     const outPath = path.join(memory.dir, "report.md");
-    if (opts.write !== false)
+    const htmlPath = path.join(memory.dir, "report.html");
+    let htmlWritten = false;
+    let htmlProblem = "";
+    if (opts.write !== false) {
         fs.writeFileSync(outPath, markdown);
+        // The same run as one file that outlives the engine: the live view's
+        // address is a port in a process, and refreshing after the run is over
+        // gets nothing. This opens from the file system, offline, forever.
+        try {
+            const sessions = replaySessions(memory);
+            fs.writeFileSync(htmlPath, buildReplayHtml({
+                markdown,
+                sessions,
+                evidence: findingEvidence(memory, sessions),
+                project: projectName(memory.dir),
+                at: new Date().toISOString(),
+                version: extras?.version ?? "",
+            }));
+            htmlWritten = true;
+        }
+        catch (err) {
+            // The markdown is the report of record and is already on disk, so this
+            // must not fail the report — but the summary then says what went wrong
+            // rather than naming a file that is not there.
+            htmlProblem = err instanceof Error ? err.message : String(err);
+            // An earlier run's page would otherwise sit beside a fresh report.md,
+            // carrying its own timestamp, looking like this run.
+            try {
+                fs.rmSync(htmlPath, { force: true });
+            }
+            catch {
+                htmlProblem += "; an older one may still be beside it";
+            }
+        }
+    }
     // Bounded summary for the tool result: full reports have exceeded client
     // token limits in real runs (66–72KB observed) — the wire gets the digest,
     // the disk gets the document.
     const summaryLines = [
         `Report written to ${outPath}`,
+        ...(htmlWritten
+            ? [`The same run as one page, with every session's steps: ${htmlPath}`]
+            : htmlProblem
+                ? [`The one-page version of this run could NOT be written (${htmlProblem}); ${outPath} is unaffected.`]
+                : []),
         ``,
         `OPEN FINDINGS: ${open.length} (${open.filter((f) => f.severity === "high").length} high) — ${current.length} this session, ${historical.length} historical${resolved.length ? `, ${resolved.length} resolved` : ""}`,
         ...(extras && extras.routesTotal > 0

package/dist/mcp-server.js

@@ -38,7 +38,8 @@ import { MemoryStore, redactSecrets } from "./engine/memory.js";
 import { SessionQueue, withWatchdog } from "./engine/dispatch.js";
 import { FIXTURE_KINDS } from "./engine/fixtures.js";
 import { feedForSession, LIVE_ENV, writeStatusFile, LIVE_TOKEN_FILE, LiveServer, StatusBoard, } from "./engine/live.js";
-import { computeGaps, formatRouteCoverage, generateReport } from "./engine/report.js";
+import { computeGaps, formatRouteCoverage, generateReport, replayDocument, reportEvidence } from "./engine/report.js";
+import { RECORD_MAX_FRAMES, resolveFrame } from "./engine/replay.js";
 import { needsTask, taskRefusal, TASK_MAX } from "./engine/task.js";
 import { EXPLORE_PROMPT_ARGUMENTS, explorePrompt, loadPlaybook, PLAYBOOK_PROMPT, PLAYBOOK_TOOL, SERVER_INSTRUCTIONS } from "./playbook.js";
 import { formatScan, scanProject } from "./scan.js";
@@ -116,12 +117,24 @@ let lastRun = null;
 function keepReport(eng) {
     if (!eng.memory)
         return;
+    // The markdown is the record and is kept first. The frames and the one-page
+    // version are extras, and building them in the same attempt meant a failure
+    // in either threw the report away with them — leaving a finished run with
+    // findings in it telling the viewer there was nothing to report.
     try {
         const { markdown } = generateReport(eng.memory, eng.oracleLog.all, reportExtras(eng), { write: false });
-        lastRun = { markdown: redactSecrets(markdown), at: new Date().toISOString(), dir: eng.memory.dir };
+        lastRun = { markdown: redactSecrets(markdown), at: new Date().toISOString(), dir: eng.memory.dir, evidence: [], replay: "" };
     }
-    catch {
-        // Best-effort: a report that cannot be rendered must not fail a close.
+    catch (err) {
+        console.error(`[scenescout] the report for ${eng.sessionKey} could not be kept: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    try {
+        lastRun.evidence = reportEvidence(eng.memory);
+        lastRun.replay = replayDocument(eng.memory, lastRun.markdown, PKG_VERSION);
+    }
+    catch (err) {
+        console.error(`[scenescout] the one-page version of this run could not be built: ${err instanceof Error ? err.message : String(err)}; the report itself is unaffected`);
     }
 }
 /** Where this run's report belongs, and whether the agent has written it there yet. */
@@ -155,9 +168,58 @@ const liveProvider = {
     report: () => {
         const eng = (lastWriter && engines.get(lastWriter.session)) ?? engines.values().next().value;
         if (!eng?.memory)
-            return lastRun ? { markdown: lastRun.markdown, at: lastRun.at } : null;
+            return lastRun ? { markdown: lastRun.markdown, at: lastRun.at, evidence: lastRun.evidence } : null;
         const { markdown } = generateReport(eng.memory, eng.oracleLog.all, reportExtras(eng), { write: false });
-        return { markdown: redactSecrets(markdown), at: new Date().toISOString() };
+        return { markdown: redactSecrets(markdown), at: new Date().toISOString(), evidence: reportEvidence(eng.memory) };
+    },
+    /**
+     * The whole run as one page, served at its own address. The live view sends
+     * a finished run here: the address then IS the report, so refreshing works
+     * and there is nothing to lose by closing a panel.
+     */
+    replay: () => {
+        const eng = (lastWriter && engines.get(lastWriter.session)) ?? engines.values().next().value;
+        if (!eng?.memory)
+            return lastRun?.replay || null;
+        try {
+            const { markdown } = generateReport(eng.memory, eng.oracleLog.all, reportExtras(eng), { write: false });
+            return replayDocument(eng.memory, redactSecrets(markdown), PKG_VERSION);
+        }
+        catch (err) {
+            // This address is one people refresh and bookmark, so a throw here would
+            // hand them a blank page. Say so, and fall back to the last rendering.
+            console.error(`[scenescout] the run's page could not be rendered: ${err instanceof Error ? err.message : String(err)}`);
+            return lastRun?.replay || null;
+        }
+    },
+    /**
+     * A recorded frame, read from the run's own recordings directory. The path
+     * comes from a viewer, so it is resolved and then required to still be
+     * inside that directory: nothing else in the project is reachable this way.
+     */
+    frame: async (relPath) => {
+        // Sessions may hold different project directories, so the frame belongs to
+        // the session its own path names — not to whichever engine happens to be
+        // first. Falling back keeps a finished run's frames reachable.
+        const named = relPath.replace(/^recordings[\\/]/, "").split("/")[0];
+        const dir = engines.get(named)?.memory?.dir ?? engines.values().next().value?.memory?.dir ?? lastRun?.dir;
+        if (!dir)
+            return null;
+        const file = resolveFrame(path.join(dir, "recordings"), relPath);
+        if (!file)
+            return null;
+        try {
+            return await fs.promises.readFile(file);
+        }
+        catch (err) {
+            // A viewer can ask for anything, so a missing file is ordinary. A frame
+            // that exists and cannot be read is not, and would otherwise present as
+            // "that frame does not exist".
+            if (err.code !== "ENOENT") {
+                console.error(`[scenescout] a recorded frame could not be read (${file}): ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return null;
+        }
     },
     // Both go around the session queue on purpose: a viewer must never wait
     // behind the agent's calls, and a session that is stuck is the one most
@@ -177,6 +239,7 @@ function reportExtras(eng) {
         unvisitedRoutes: unvisited,
         mode: eng.mode,
         policyAttributed: eng.oracleLog.policyAttributed,
+        version: PKG_VERSION,
     };
 }
 /** Hand the live view's token to `scenescout watch` through a file only the owner can read. */
@@ -456,13 +519,18 @@ server.registerTool("scout_attach", {
             '"Approve and reject orders as a manager"). It sits above the task, which is what the session is doing at any moment. ' +
             "Shown to whoever is watching the run; worth setting whenever more than one session is live."),
         task: z.string().max(300).optional().describe("Old name for `objective` (2.0). Prefer `objective`."),
+        record: z
+            .boolean()
+            .default(false)
+            .describe("Keep a frame of the page after every action, under .scenescout/recordings/, and show it beside that step in report.html. " +
+            "Off by default: a recording is pictures of the app under test sitting in the project folder. Turn it on for QA work, where the run is evidence and not only a report."),
         session: z
             .string()
             .max(40)
             .optional()
             .describe("Session name for multi-role runs (e.g. 'admin', 'qa'). Creates/replaces that session's browser and makes it the default. Default: 'default'."),
     },
-}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, browser, viewportWidth, viewportHeight, objective, task, session, }) => {
+}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, browser, viewportWidth, viewportHeight, objective, task, record, session, }) => {
     try {
         const target = session ?? activeName;
         if (session) {
@@ -533,6 +601,7 @@ server.registerTool("scout_attach", {
             viewport,
             // `task` is what this was called in 2.0; it named the session's whole remit, which is the objective.
             objective: objective ?? task,
+            record,
             memoryStore: store,
         });
         eng.role = storageStatePath ? path.basename(storageStatePath).replace(/\.json$/i, "") : "anonymous";
@@ -543,7 +612,13 @@ server.registerTool("scout_attach", {
             await ensureLive(eng.memory.dir);
             writeStatus(target, "idle", "scout_attach");
         }
-        return text(out + conflictNote + (engines.size > 1 ? `\n${sessionLines()}` : "") + liveLine(), target);
+        // Recording writes pictures of the app under test into the project, so
+        // a run doing it says where they go rather than leaving the person to
+        // find a folder of screenshots later.
+        const recordNote = record && eng.memory?.dir
+            ? `\n\n📸 RECORDING: a frame of the page after each action, under ${path.join(eng.memory.dir, "recordings", target)}/ (at most ${RECORD_MAX_FRAMES}). scout_report writes them into report.html beside report.md.`
+            : "";
+        return text(out + conflictNote + recordNote + (engines.size > 1 ? `\n${sessionLines()}` : "") + liveLine(), target);
     }
     catch (err) {
         return errorText(err);
@@ -922,6 +997,7 @@ server.registerTool("scout_finding", {
             evidence,
             url: eng.currentUrl,
             state: eng.currentState || "(unknown)",
+            session: eng.sessionKey,
         });
         return text(isNew
             ? `Finding recorded: [${finding.severity}] ${finding.title} (id ${finding.id})`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.0.1",
+  "version": "3.1.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",