scenescout 3.21.3 → 3.23.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # scenescout
 
+## 3.23.0
+
+### Minor Changes
+
+- ed24973: Start a run from an earlier run's record, opt-in. Every run that writes its report now keeps a record of what it worked on and left (routes in order, each session's steps, and on each route the controls never exercised, forms never submitted and options never chosen), in the project's memory and in `ci.json` under `record`. `scenescout ci --from-run <ci.json or project directory>` (or `SCENESCOUT_FROM_RUN`) with `--from-run-mode continue` (the default) takes first the routes that run never worked on, then the ones it left work on, told exactly what to do first on each, then the rest, reaching a page the earlier run got to by acting on another page through the same steps; a run takes on only its budget's worth of pages (`--from-run-turns-per-page`, default 7 turns a page) and the next continued run takes the pages after them; `--from-run-mode replay` follows its routes and steps in order, one lane per session it had. `scout_lane_brief` takes `fromRun` and `fromRunMode`, the ci action takes `from-run` and `from-run-mode`, and the run it started from is named in the report, `summary.md` and `ci.json` (`fromRun`). Without it, runs behave as before.
+
+## 3.22.0
+
+### Minor Changes
+
+- 072b68b: `scenescout check --record --template <file.json>` (the action's `template` input) also writes the recorded run up as a test report laid out by the template: each saved flow a test and each step a row with its expected and actual result and its frame, failed steps as deviations, a SHA-256 manifest of the evidence and blank sign-off rows. Flows gain optional `id`, `requirements` and a step's `expected` for traceability; an example template is in `examples/report-template.json`.
+
 ## 3.21.3
 
 ### Patch Changes

package/README.md

@@ -279,7 +279,10 @@ Use SceneScout to test http://localhost:3000, record the run
 or, on the tool directly, `scout_attach {record: true}`. `SCENESCOUT_RECORD=on` in
 the server's environment records every run. A CI gate records too:
 `scenescout check --record` writes `replay.html`, every journey step by step with
-its frames ([recording a check](docs/ci.md#recording-a-check)).
+its frames ([recording a check](docs/ci.md#recording-a-check)), and
+`--template <file.json>` also writes it up as a test report laid out as a template
+says, with expected and actual results, deviations, blank sign-off rows and a
+SHA-256 manifest of the evidence ([test reports](docs/ci.md#a-test-report-from-a-template)).
 
 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
@@ -482,6 +485,7 @@ npx scenescout ci http://127.0.0.1:3000
 - **Caps:** at most 80 model turns, 3,000,000 tokens and 20 minutes (`--max-turns`, `--max-tokens`, `--max-minutes`), shared by two model loops that each explore their own part of the app (`--lanes`, default 2). The first cap reached ends the exploration; the report is still written, and says which cap ended it. On the benchmark's demo app a run at these defaults cost about $0.03 on `gpt-6-luna` ([docs/benchmark.md](docs/benchmark.md#choosing-the-defaults-issue-419)).
 - **Mode:** `read-only` by default; `--mode observe` sends no form at all, `--mode safe-write` lets the run create records and change only the ones it created. `--mode destructive` runs only with `--allow-destructive` as well.
 - **Duplicates:** when the dedup rule keeps a filed finding apart, the run's model is asked at its lowest effort whether it is one already open on the same page, and merges it on a "same", keeping the filing's title, category, severity and evidence under that finding. The two findings' titles, categories and evidence, and the page's path, are sent; `--dedup rule` turns it off ([ADR 17](docs/adr/0017-a-model-judges-only-the-merges-the-rule-misses.md)).
+- **Starting from an earlier run (opt-in):** every run that writes its report leaves a record in `ci.json` and the project's memory: the routes it worked on, its steps, and what it left on each route. `--from-run <ci.json or project directory>` continues where that run left off (routes it never worked on first, then the ones it left work on, with exactly which forms, options and controls to take first), and `--from-run-mode replay` follows its routes and steps in order. `scout_lane_brief {fromRun, fromRunMode}` does the same for a parallel run. On the demo app a chain of continued runs found 8 defects against 7 for fresh runs at the default budget, and 4, 3 and 4 against 4 at a budget cut to stand in for a larger app, within the noise, so it stays off unless asked for ([the measurement](docs/benchmark.md#starting-from-an-earlier-run-issue-418)).
 - **Output**, in `.scenescout/ci/` (or `--out`): `report.md` and `report.html` (the report an agent's run writes), `summary.md` (also appended to the GitHub job summary), `ci.json` and `ci.sarif`, with a usage line: turns, tokens, time and an estimated cost where the model's price is known (`--price-in`, `--price-out` give one for any model).
 
 There is a GitHub Action for it (`uses: brunoboto96/SceneScout/ci@…`). [docs/ci.md](docs/ci.md#an-unattended-exploratory-run) has the workflow and every option; [ADR 14](docs/adr/0014-an-unattended-run-reports-and-never-gates.md) says why it works this way.

package/dist/check-run.js

@@ -20,6 +20,7 @@ import { firstLineOf } from "./engine/limits.js";
 import { isNonPageResource } from "./engine/crawl.js";
 import { checkRetestPlan, retestResults, wellFormedFindings } from "./engine/verify.js";
 import { capFrames, isReplayFrameFile, journeyOf, journeyVideoPath, isGeneratedReplay, isJourneyVideoFile, redactReplay, REPLAY_VIDEOS_DIRNAME, replayVideos, REPLAY_FILE, REPLAY_FRAMES_DIRNAME, replayFramePath, replayFrames, replaySessionKey, visitOf, } from "./engine/check-replay.js";
+import { buildTemplateReport, evidenceFiles, evidenceIndex, isGeneratedReport, readReportTemplate, recordedReportFile, reportFileOf, templateRecordError, } from "./engine/check-report.js";
 /** The baselines folder a check uses: the one --baselines names, else the project's own. */
 export function baselinesDirOf(options) {
     return options.baselinesDir ?? defaultBaselinesDir(options.projectDir);
@@ -470,7 +471,34 @@ async function takeBaselines(engine, options, mode, targets, log) {
  * check, recorded or not, so a page from an earlier run is never read, or
  * uploaded, as this one's; whatever else the folder holds stays.
  */
-export function clearReplayOutput(outDir) {
+export function clearReplayOutput(outDir, reportFile) {
+    // The test report the earlier run's check.json says it wrote (--template), and the one this run's template names:
+    // each only when it still carries the mark. A copy renamed or kept under any other name is the project's own.
+    const reports = new Set();
+    try {
+        const earlier = recordedReportFile(JSON.parse(fs.readFileSync(path.join(outDir, "check.json"), "utf8")));
+        if (earlier)
+            reports.add(earlier);
+    }
+    catch {
+        // No earlier check.json, or one that cannot be read: it names no report to remove.
+    }
+    if (reportFile)
+        reports.add(reportFile);
+    for (const name of reports) {
+        const at = path.join(outDir, name);
+        let text;
+        try {
+            text = fs.readFileSync(at, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        if (isGeneratedReport(text))
+            fs.rmSync(at);
+    }
     // Only a page a check wrote: a file of the same name the project keeps there is its own.
     const page = path.join(outDir, REPLAY_FILE);
     let text = null;
@@ -512,6 +540,39 @@ export function clearReplayOutput(outDir) {
     if (fs.readdirSync(root).length === 0)
         fs.rmdirSync(root);
 }
+/**
+ * The report template a check was given (--template), read and validated, or
+ * null for none. Throws, before the browser starts, when the check is not
+ * recorded, when the template is not valid, or when the file it would write is
+ * one the project keeps there and a check did not write.
+ */
+export function prepareTemplateReport(options, outDir) {
+    if (options.template === undefined)
+        return null;
+    const needsRecord = templateRecordError(options);
+    if (needsRecord)
+        throw new Error(needsRecord);
+    const template = readReportTemplate(options.template);
+    const file = path.join(outDir, reportFileOf(template));
+    let text = null;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    if (text !== null && !isGeneratedReport(text))
+        throw new Error(`${file} is not a report SceneScout wrote, so a check will not overwrite it. Move or rename it, name another file in the template's "file", or pass --out to write the check somewhere else`);
+    return template;
+}
+/** Write the template's report beside replay.html, after check.json and the replay page, so the manifest hashes the files as written. Returns its file name. */
+export function writeTemplateReport(outDir, result, template, meta) {
+    const file = reportFileOf(template);
+    const evidence = evidenceIndex(outDir, evidenceFiles(result));
+    fs.writeFileSync(path.join(outDir, file), buildTemplateReport(result, template, evidence, meta));
+    return file;
+}
 /**
  * Why a recorded check (--record or --video) must not start, or null: a
  * replay.html in the output folder that a check did not write is the

package/dist/ci-run.js

@@ -22,9 +22,10 @@ import { CreateMessageRequestSchema, ErrorCode, McpError } from "@modelcontextpr
 import { DEDUP_JUDGE_CAPABILITY, durationText, JUDGE_CALL_MS, JUDGE_MAX_OUTPUT_TOKENS, JUDGE_SYSTEM, JUDGE_TOOL, judgeKickoffOf, samplingResultOf, } from "./engine/dedup.js";
 import { CAPTURE_MARGIN, parseCaptureResult, rebaseUrl, SHOT_FILES, SHOTS_DIRNAME } from "./engine/capture.js";
 import { addUsage, attachFailure, budgetSpend, wallLeftMs, guardToolArgs, CAPTURE_TOOLS, childEnv, ciCaptureKickoff, ciCaptureSystemPrompt, CI_DIRNAME, ciExitCode, ciKickoff, ciSarif, ciSummaryJson, ciSummaryMarkdown, ciSystemPrompt, ciToolArgs, ciTools, describeStop, findingsThisRun, newBudget, NO_USAGE, readFindings, redactKeys, settleTurn, takeTurn, toolResultText, usageLine, } from "./engine/ci.js";
-import { ciLaneKickoff, ciLaneSystemPrompt, crawlFoundNothing, crawlNotes, LANE_TOOLS, mergeLaneStops, PLAN_CRAWL_ROUNDS, planCiLanes, PLANNER_SESSION, } from "./engine/ci-lanes.js";
+import { ciLaneKickoff, ciLaneSystemPrompt, crawlFoundNothing, crawlNotes, LANE_TOOLS, mergeLaneStops, PLAN_CRAWL_ROUNDS, planCiLanes, plannedRoutes, planReplayLanes, PLANNER_SESSION, } from "./engine/ci-lanes.js";
 import { resolveTimeLimits } from "./engine/limits.js";
-import { MEMORY_DIRNAME, writeSelfIgnore } from "./engine/memory.js";
+import { loadRunRecord, MEMORY_DIRNAME, noteFromRunOnDisk, readRunRecordsOnDisk, writeSelfIgnore } from "./engine/memory.js";
+import { carryForward, continueLines, continueExhausted, continuePlan, DEFAULT_TURNS_PER_PAGE, pageCap, takenPages, fromRunLine, isPattern, pathLine, prefixOutcome, prefixPlan, replayLines, replayPlan, } from "./engine/from-run.js";
 import { sarifFilesFor } from "./engine/sarif.js";
 import { decodePng, diffImages, encodePng } from "./engine/png.js";
 import { AnthropicConversation, backoffMs, errorMessage, MalformedReply, OpenAIConversation, retryable, retryAfterMs, } from "./engine/provider.js";
@@ -434,43 +435,119 @@ function takesSession(t) {
 }
 const messageOf = (err) => (err instanceof Error ? err.message : String(err));
 /**
- * A run split into lanes (--lanes): plan, then run every lane at once, then
- * fold what they did. The plan is a snapshot and a crawl from the planner's
- * session (no model call: only their time counts), the crawl repeated while it
- * finds routes, and the split brief.ts makes of them. Each lane attaches its
- * own session on the run's target URL, as the planner did (the engine resolves
- * every path against the URL a session attached with), opens its first route,
- * runs the agent loop there with its own conversation, draws its turns from
- * the run's one budget, and is closed when it ends. Their findings are already
- * one: every session files into the project's one memory, whose dedup folds a
- * defect two lanes filed. `outcome` is absent when there was nothing to split,
- * and the run explores in one loop instead.
+ * Take the earlier run's path to a page (from-run.ts prefixPlan) in one
+ * scout_run_plan call, which the write policy governs like any other step.
+ * Nothing happens when the record never reached the page or opened it by its
+ * address. When a step cannot be repeated (the record cannot say it, or the
+ * page changed), the session navigates to the page directly instead, if it is
+ * not a pattern. Returns the note for the record and the line the model is told.
  */
-async function exploreInLanes(o) {
-    const { host, options, log, now, budget } = o;
-    const timeLeft = () => wallLeftMs(budgetSpend(budget), options.caps, now());
-    // ── plan ──
+async function reachByPath(o) {
+    if (!o.route)
+        return { lines: [] };
+    const plan = prefixPlan(o.record, o.route);
+    if (!plan || ("steps" in plan && plan.direct))
+        return { lines: [] };
+    let why;
+    let steps = 0;
+    if ("cannot" in plan)
+        why = `its path cannot be repeated: ${plan.cannot}`;
+    else {
+        steps = plan.steps.length;
+        const r = await o.host
+            .call("scout_run_plan", { session: o.session, steps: plan.steps, task: `Taking the earlier run's path to ${o.route}` }, Math.min(240_000, o.timeLeft()))
+            .catch((err) => ({ text: `ERROR: ${messageOf(err)}`, isError: true }));
+        const out = prefixOutcome(r.text.replace(/^\[session [^\]\n]*\]\n/, ""), steps, o.route);
+        if (out.ok) {
+            o.say(`reached ${o.route} by the earlier run's path (${steps} step(s)).`);
+            return {
+                note: { session: o.session, target: o.route, steps, outcome: "replayed" },
+                lines: [`Your browser reached ${o.route} the way the earlier run did: ${pathLine(plan.steps)}. Start there.`],
+            };
+        }
+        why = out.why;
+    }
+    o.say(`could not take the earlier run's path to ${o.route} (${why}); navigating to it instead.`);
+    const direct = isPattern(o.route)
+        ? undefined
+        : await o.host
+            .call("scout_navigate", { session: o.session, target: o.route, task: `Opening ${o.route}` }, Math.min(120_000, o.timeLeft()))
+            .catch((err) => ({ text: `ERROR: ${messageOf(err)}`, isError: true }));
+    const opened = !!direct && !direct.isError && !/^(ERROR|REFUSED):/.test(direct.text.replace(/^\[session [^\]\n]*\]\n/, ""));
+    return {
+        note: { session: o.session, target: o.route, steps, outcome: opened ? "navigated" : "unreached", why: why.slice(0, 300) },
+        lines: [
+            opened
+                ? `The earlier run's path to ${o.route} could not be repeated (${why}), so your browser was sent there directly.`
+                : `The earlier run's path to ${o.route} could not be repeated (${why}); reach it from the page you are on.`,
+        ],
+    };
+}
+/** The planning crawl's notes with these routes added, each with no note: routes a record knew that the crawl did not list. */
+function withRoutes(notes, routes) {
+    const out = new Map(notes);
+    for (const r of routes)
+        if (!out.has(r))
+            out.set(r, []);
+    return out;
+}
+/**
+ * The record this run's report left in the project's memory (from-run.ts), for
+ * ci.json: the newest written since the run started. A continued run's carries
+ * the record it continued, so a chain of runs each given the last one's
+ * ci.json accumulates what the chain covered. Never fatal: without one, ci.json
+ * has no record, and the log says why.
+ */
+function thisRunsRecord(o) {
+    let own;
+    try {
+        own = readRunRecordsOnDisk(o.projectDir)
+            .filter((r) => r.at >= o.since)
+            .at(-1);
+    }
+    catch (err) {
+        o.log(`The run's record could not be read from the project's memory, so ci.json holds none: ${messageOf(err)}`);
+        return undefined;
+    }
+    if (!own) {
+        o.log("The report left no run record in the project's memory, so ci.json holds none.");
+        return undefined;
+    }
+    const withPrefixes = {
+        ...own,
+        ...(o.prefixes && o.prefixes.length > 0 ? { prefixes: [...o.prefixes] } : {}),
+        ...(o.continuedFresh ? { continuedFresh: true } : {}),
+        ...(o.assigned && o.assigned.length > 0 ? { assigned: [...new Set(o.assigned)] } : {}),
+    };
+    return o.continued ? carryForward(o.continued, withPrefixes) : withPrefixes;
+}
+/**
+ * The planning crawl a run split into lanes, or a continued run, starts with: a
+ * snapshot from the planner's session (attaching harvests no links; a snapshot
+ * of the page it landed on does), then a crawl repeated while it finds routes,
+ * up to PLAN_CRAWL_ROUNDS. No model call: only its time counts.
+ */
+async function planningCrawl(o) {
     // What went wrong while planning, so a plan left with nothing to split says why rather than blaming the app.
     let planningFailed;
     /** One planner call: its text, or undefined after saying why it failed. */
     const plannerCall = async (tool, maxMs, what) => {
         try {
-            const r = await host.call(tool, { session: PLANNER_SESSION }, Math.min(maxMs, timeLeft()));
+            const r = await o.host.call(tool, { session: PLANNER_SESSION }, Math.min(maxMs, o.timeLeft()));
             if (r.isError)
                 throw new Error(r.text.replace(/^ERROR:\s*/, ""));
             return r.text;
         }
         catch (err) {
             planningFailed = `the planning ${what} failed: ${messageOf(err).slice(0, 300)}`;
-            log(`Lanes: ${planningFailed}.`);
+            o.log(`${o.label}: ${planningFailed}.`);
             return undefined;
         }
     };
-    // Attaching harvests no links; a snapshot of the page it landed on does, so the first crawl has routes to visit.
-    if (timeLeft() > 0)
+    if (o.timeLeft() > 0)
         await plannerCall("scout_snapshot", 120_000, "snapshot");
     const notes = new Map();
-    for (let round = 0; round < PLAN_CRAWL_ROUNDS && timeLeft() > 0; round += 1) {
+    for (let round = 0; round < PLAN_CRAWL_ROUNDS && o.timeLeft() > 0; round += 1) {
         const text = await plannerCall("scout_crawl", 600_000, "crawl");
         if (text === undefined)
             break;
@@ -481,14 +558,24 @@ async function exploreInLanes(o) {
         if (crawlFoundNothing(text) || notes.size === known)
             break;
     }
-    const plan = planCiLanes({
-        target: options.url,
-        notes,
-        count: options.lanes,
-        focus: options.focus,
-        mode: options.mode,
-        ...(planningFailed ? { planningFailed } : {}),
-    });
+    return { notes, ...(planningFailed ? { planningFailed } : {}) };
+}
+/**
+ * A run split into lanes (--lanes): plan, then run every lane at once, then
+ * fold what they did. The plan is a snapshot and a crawl from the planner's
+ * session (no model call: only their time counts), the crawl repeated while it
+ * finds routes, and the split brief.ts makes of them. Each lane attaches its
+ * own session on the run's target URL, as the planner did (the engine resolves
+ * every path against the URL a session attached with), opens its first route,
+ * runs the agent loop there with its own conversation, draws its turns from
+ * the run's one budget, and is closed when it ends. Their findings are already
+ * one: every session files into the project's one memory, whose dedup folds a
+ * defect two lanes filed. `outcome` is absent when there was nothing to split,
+ * and the run explores in one loop instead.
+ */
+async function exploreInLanes(o) {
+    const { host, options, log, now, budget, plan } = o;
+    const timeLeft = () => wallLeftMs(budgetSpend(budget), options.caps, now());
     if (plan.oneLoop) {
         log(`Lanes: ${plan.oneLoop}. Exploring in one loop.`);
         return { lanes: { asked: options.lanes, sessions: [], oneLoop: plan.oneLoop } };
@@ -539,7 +626,9 @@ async function exploreInLanes(o) {
                     on = lane.url;
             }
             say(`attached on ${new URL(on).pathname}, owning ${lane.modules.join(", ")}.`);
-            return await exploreLane(lane, on, say, { ...result, attached: true });
+            // A continued run: the earlier run's path to this lane's first page, when it got there by acting on another.
+            const reached = o.reach && timeLeft() > 0 ? await o.reach(lane.session, lane.routes[0], say) : [];
+            return await exploreLane(lane, on, say, { ...result, attached: true }, reached);
         }
         catch (err) {
             // Not a cap and not the model's API: the lane itself broke. Reported as the lane's, and the run's (mergeLaneStops), never dropped.
@@ -548,7 +637,7 @@ async function exploreInLanes(o) {
             return { ...result, attached, stop: "could-not-start", stopDetail: why };
         }
     };
-    const exploreLane = async (lane, on, say, result) => {
+    const exploreLane = async (lane, on, say, result, reached = []) => {
         const outcome = await agentLoop({
             client: o.makeClient(system, tools, ciLaneKickoff({
                 lane: { ...lane, url: on },
@@ -559,6 +648,7 @@ async function exploreInLanes(o) {
                 level: options.level,
                 focus: options.focus,
                 caps: options.caps,
+                ...(o.laneLines || reached.length > 0 ? { fromRun: [...(o.laneLines?.(lane) ?? []), ...reached] } : {}),
             })),
             host,
             tools,
@@ -625,6 +715,11 @@ export async function runCi(options, resolved, deps) {
     let reportWritten = false;
     let capture;
     let lanes;
+    let runFromRun;
+    let runRecord;
+    let earlier;
+    // The real clock, as the server's: this run's record is the one its report wrote after this.
+    const startedIso = new Date().toISOString();
     let host = null;
     // Set when the exploration ends (or never starts): the report and the close share FINISH_MS from then.
     let finishBy = 0;
@@ -636,6 +731,17 @@ export async function runCi(options, resolved, deps) {
         const judge = judgeAsk
             ? judgeHandler({ ask: judgeAsk, model: resolved.model, spend: budget, caps: options.caps, calls: judgeCalls, secrets, now })
             : undefined;
+        // The earlier run's record, read before anything starts: a run asked to continue or replay one must not quietly start fresh.
+        if (options.fromRun && !options.show) {
+            try {
+                earlier = loadRunRecord(options.fromRun.path);
+            }
+            catch (err) {
+                throw new Error(`--from-run: ${messageOf(err)}`);
+            }
+            if (options.fromRun.mode === "replay" && replayPlan(earlier).length === 0)
+                throw new Error(`--from-run: the run recorded in ${options.fromRun.path} took no steps, so there is nothing to replay`);
+        }
         host = await (deps.startHost ?? startServer)(log, judge);
         // What every session of the run attaches with: the planner's here, and each lane's when the run is split.
         const attachArgs = (a) => ({
@@ -666,10 +772,67 @@ export async function runCi(options, resolved, deps) {
             const listed = await host.tools();
             const toolHost = host;
             let captured = null;
-            const oneLoop = () => {
+            // Named as it was given: a resolved path would put a local directory in the report and ci.json.
+            const from = options.fromRun ? (options.fromRun.given ?? options.fromRun.path) : "";
+            const replay = earlier && options.fromRun?.mode === "replay" ? replayPlan(earlier) : undefined;
+            const continuing = earlier && options.fromRun?.mode === "continue" ? earlier : undefined;
+            // A run split into lanes, or a continued one, crawls first: the lanes are split, and a continued run's routes ordered, from what it finds.
+            // A replay does not: its routes and steps are the record's.
+            const timeLeft = () => wallLeftMs(budgetSpend(budget), options.caps, now());
+            const plans = !options.show && !replay && (options.lanes > 1 || !!continuing);
+            const planned = plans ? await planningCrawl({ host, log, timeLeft, label: options.lanes > 1 ? "Lanes" : "From run" }) : undefined;
+            const planItems = continuing && planned ? continuePlan(continuing, plannedRoutes(options.url, planned.notes)) : undefined;
+            // A record with no work left anywhere: explore as a fresh run (the stable split, the landing page, no path), and say so.
+            const continuedFresh = !!planItems && continueExhausted(planItems);
+            const items = continuedFresh ? undefined : planItems;
+            // How many pages a continued run takes on, from its budget (from-run.ts pageCap): each lane's share of the turns, or the run's.
+            const perPage = options.fromRun?.turnsPerPage ?? DEFAULT_TURNS_PER_PAGE;
+            const cap = items ? pageCap(options.caps.turns, perPage) : undefined;
+            const laneCap = items ? pageCap(Math.floor(options.caps.turns / Math.max(1, options.lanes)), perPage) : undefined;
+            // The pages this run was given, kept in its record so the next continued run takes the next ones.
+            const assigned = [];
+            if (options.fromRun && earlier && !options.show) {
+                runFromRun = { mode: options.fromRun.mode, source: from, runId: earlier.runId, recordAt: earlier.at };
+                log(`From run: ${fromRunLine(runFromRun)}.`);
+                if (items)
+                    log(`From run: ${items.filter((i) => i.tier === 1).length} route(s) it never worked on, ${items.filter((i) => i.tier === 2).length} with work left, ${items.filter((i) => i.tier === 3).length} worked through.`);
+                if (continuedFresh)
+                    log("From run: the earlier run left no recorded work on any route, so this run explores as a fresh one.");
+                // Noted in the project's memory for the report, which the server writes. Never fatal: the run goes on.
+                try {
+                    noteFromRunOnDisk(options.projectDir, { at: new Date().toISOString(), ...runFromRun });
+                }
+                catch (err) {
+                    log(`From run: the project's memory could not be told, so the report will not name the earlier run: ${messageOf(err)}`);
+                }
+            }
+            // How a continued run's lanes (or its one loop) reached their first page by the earlier run's path, for the record.
+            const prefixes = [];
+            const reach = items
+                ? async (session, route, say) => {
+                    const r = await reachByPath({ host: toolHost, session, record: continuing, route, timeLeft, say });
+                    if (r.note)
+                        prefixes.push(r.note);
+                    return r.lines;
+                }
+                : undefined;
+            const oneLoop = async () => {
                 const tools = ciTools(listed, options.show ? CAPTURE_TOOLS : undefined);
                 const system = options.show ? ciCaptureSystemPrompt() : ciSystemPrompt(loadPlaybook(packageRoot), options);
-                const kickoff = options.show ? ciCaptureKickoff({ url: options.url, show: options.show }) : ciKickoff(options);
+                const reached = reach && items && !options.show ? await reach(PLANNER_SESSION, items[0]?.route, (l) => log(`From run: ${l}`)) : [];
+                if (items && cap !== undefined) {
+                    const mine = takenPages(items, cap);
+                    assigned.push(...mine);
+                    log(`From run: takes on ${mine.join(", ")} (${cap} page(s) at ${perPage} turns a page).`);
+                }
+                const fromRun = planItems
+                    ? [...continueLines(planItems, { from, ...(cap !== undefined ? { cap } : {}) }), ...reached]
+                    : replay && replay.length > 0
+                        ? replayLines(replay[0], { from })
+                        : undefined;
+                const kickoff = options.show
+                    ? ciCaptureKickoff({ url: options.url, show: options.show })
+                    : ciKickoff({ ...options, ...(fromRun && fromRun.length > 0 ? { fromRunLines: fromRun } : {}) });
                 return agentLoop({
                     client: deps.makeClient(system, tools, kickoff),
                     host: toolHost,
@@ -685,8 +848,56 @@ export async function runCi(options, resolved, deps) {
                     },
                 });
             };
-            if (options.lanes > 1 && !options.show) {
-                const split = await exploreInLanes({ host, listed, options, makeClient: deps.makeClient, log, now, budget, attachArgs, attachMs });
+            // A replay has as many lanes as the recorded run had sessions; otherwise the planning crawl is split as asked.
+            const lanePlan = options.show
+                ? undefined
+                : replay
+                    ? planReplayLanes({ target: options.url, lanes: replay, ...(options.focus ? { focus: options.focus } : {}) })
+                    : options.lanes > 1 && planned
+                        ? planCiLanes({
+                            target: options.url,
+                            // A continued run splits every route it orders, the record's own included, so none is left out of every lane.
+                            notes: items
+                                ? withRoutes(planned.notes, items.map((i) => i.route))
+                                : planned.notes,
+                            count: options.lanes,
+                            focus: options.focus,
+                            mode: options.mode,
+                            ...(planned.planningFailed ? { planningFailed: planned.planningFailed } : {}),
+                            ...(items ? { order: items.map((i) => i.route) } : {}),
+                        })
+                        : undefined;
+            if (replay && replay.length > 1 && replay.length !== options.lanes)
+                log(`From run: replaying the recorded run's ${replay.length} sessions as ${replay.length} lanes.`);
+            if (lanePlan && (lanePlan.lanes.length > 0 || options.lanes > 1)) {
+                // A replayed lane is told its own session's steps: the plan keeps the recorded sessions' order.
+                const replayed = new Map(replay ? lanePlan.lanes.map((l, i) => [l.session, replay[i]]) : []);
+                const laneLines = planItems
+                    ? (lane) => {
+                        if (items && laneCap !== undefined) {
+                            const mine = takenPages(items, laneCap, lane.routes);
+                            assigned.push(...mine);
+                            log(`From run: lane ${lane.session} takes on ${mine.join(", ") || "no page with work left"} (${laneCap} page(s) at ${perPage} turns a page).`);
+                        }
+                        return continueLines(planItems, { from, only: lane.routes, ...(laneCap !== undefined ? { cap: laneCap } : {}) });
+                    }
+                    : replay
+                        ? (lane) => replayLines(replayed.get(lane.session), { from })
+                        : undefined;
+                const split = await exploreInLanes({
+                    host,
+                    listed,
+                    options,
+                    makeClient: deps.makeClient,
+                    log,
+                    now,
+                    budget,
+                    attachArgs,
+                    attachMs,
+                    plan: lanePlan,
+                    ...(laneLines ? { laneLines } : {}),
+                    ...(reach ? { reach } : {}),
+                });
                 lanes = split.lanes;
                 outcome = split.outcome ?? (await oneLoop());
             }
@@ -709,6 +920,16 @@ export async function runCi(options, resolved, deps) {
                 reportWritten = !report.isError && !/^ERROR:/.test(report.text) && fs.existsSync(path.join(options.projectDir, MEMORY_DIRNAME, "report.md"));
                 if (!reportWritten)
                     log(`The report could not be generated: ${report.text.slice(0, 400)}`);
+                else
+                    runRecord = thisRunsRecord({
+                        projectDir: options.projectDir,
+                        since: startedIso,
+                        continued: earlier && options.fromRun?.mode === "continue" ? earlier : undefined,
+                        prefixes,
+                        continuedFresh,
+                        assigned,
+                        log,
+                    });
             }
         }
     }
@@ -748,6 +969,8 @@ export async function runCi(options, resolved, deps) {
         findings: findingsThisRun(before, readMemoryFindings(options.projectDir)),
         ...(capture ? { capture } : {}),
         ...(lanes ? { lanes } : {}),
+        ...(runFromRun ? { fromRun: runFromRun } : {}),
+        ...(runRecord ? { record: runRecord } : {}),
         ...(options.show
             ? {}
             : {

package/dist/cli.js

@@ -21,7 +21,8 @@ import { APPROX_DISK_MB, defaultAttachNote, defaultEngine, launchTarget, parseBr
 import { CLIENT_LABELS, firstMessageHint, manualFor, parseClients, registerWithClient, vscodeBinary } from "./clients.js";
 import { CLAUDE_CODE_NOT_NEEDED, CLI_NAME, desktopExtensionRoots, diagnose, doctorAllGood, findDesktopExtension, installClosing, ensureCommand, findOnUserPath, installSkill, isEphemeralRoot, launchCommand, manualRegisterCommand, planCommand, registerMcp, resolveClaudeDir, spawnRunner, } from "./installer.js";
 import { downloadBrowsers, presentBrowsers } from "./installer.js";
-import { baselinesDirOf, clearReplayOutput, replayPageConflict, defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
+import { baselinesDirOf, clearReplayOutput, replayPageConflict, defaultCheckDir, prepareTemplateReport, readCheckInputs, runCheck, writeTemplateReport, } from "./check-run.js";
+import { reportFileOf } from "./engine/check-report.js";
 import { buildCheckReplayHtml, commitOf, REPLAY_FILE, replayFrames, replayVideos } from "./engine/check-replay.js";
 import { recordChoice } from "./engine/capture.js";
 import { httpClient, httpJudgeAsk, runCi } from "./ci-run.js";
@@ -112,7 +113,10 @@ Usage:
                                       and write replay.html beside the report, role → journey → step (default:
                                       SCENESCOUT_RECORD, else off; the frames go in replay-frames/);
                                      --video [on|off]: record a WebM of each saved flow, and only of the flows,
-                                      into replay-videos/, played on replay.html beside its steps (default off))
+                                      into replay-videos/, played on replay.html beside its steps (default off);
+                                     --template file.json: on a recorded check, also write a test report laid out
+                                      as the template says (report.html unless it names a file), with the frames,
+                                      deviations and a SHA-256 manifest of the evidence; needs --record)
                                     Exit code: 0 passed, 1 failed the gate, 2 could not run.
   scenescout ci <url>               An exploratory run with no person present: a model reached through its API
                                     drives the tools by the SceneScout method and the run ends in the report.
@@ -580,15 +584,18 @@ async function check(args) {
     let options = parsed.options;
     const outDir = options.outDir ?? defaultCheckDir(options.projectDir);
     let inputs;
+    let template = null;
     try {
         // --record, else SCENESCOUT_RECORD, else off.
         options = { ...options, record: recordChoice(options.record, process.env) };
+        // --template: read and checked before the browser starts, so a bad template never costs a run.
+        template = prepareTemplateReport(options, outDir);
         // A replay.html the project keeps there is its own: a recorded check refuses to start rather than overwrite it.
         const conflict = options.record || options.video ? replayPageConflict(outDir) : null;
         if (conflict)
             throw new Error(conflict);
         // A replay page an earlier run left must never be read, or uploaded, as this run's.
-        clearReplayOutput(outDir);
+        clearReplayOutput(outDir, template ? reportFileOf(template) : undefined);
         inputs = readCheckInputs(options);
     }
     catch (err) {
@@ -615,7 +622,11 @@ async function check(args) {
         console.error(`scenescout check: could not run a saved flow: ${refused}`);
         process.exit(EXIT.error);
     }
+    // Recorded in check.json, so the next check removes exactly this file and the action finds it.
+    if (template && result.replay)
+        result = { ...result, testReport: reportFileOf(template) };
     const markdown = formatCheck(result);
+    let reportFile = null;
     try {
         const version = packageVersion();
         if (!options.outDir)
@@ -645,6 +656,8 @@ async function check(args) {
                 couldNotRun,
             });
             fs.writeFileSync(path.join(outDir, REPLAY_FILE), html);
+            if (template)
+                reportFile = writeTemplateReport(outDir, result, template, { version, commit: commitOf(process.env) });
         }
         // On GitHub Actions the verdict also goes on the run's summary page.
         if (process.env.GITHUB_STEP_SUMMARY)
@@ -659,6 +672,8 @@ async function check(args) {
     console.log(`Wrote report.md, check.sarif and check.json to ${outDir}`);
     if (result.replay)
         console.log(`Wrote ${REPLAY_FILE} to ${outDir}, with ${replayFrames(result.replay).length} frame(s) and ${replayVideos(result.replay).length} journey video(s) beside it: open it in a browser to see each step`);
+    if (reportFile)
+        console.log(`Wrote ${reportFile} to ${outDir}: the test report the template lays out, with a SHA-256 manifest of its evidence`);
     const pictured = result.baselines?.results.filter((r) => r.files).length ?? 0;
     if (pictured > 0)
         console.log(`Wrote the pictures of ${pictured} changed baseline(s) under ${path.join(outDir, VISUAL_DIRNAME)}`);
@@ -762,7 +777,7 @@ async function ci(args) {
         console.error(redactKeys(`scenescout ci: ${message}`, secrets));
         process.exit(EXIT_CI.couldNotRun);
     };
-    const parsed = parseCiArgs(args, process.cwd());
+    const parsed = parseCiArgs(args, process.cwd(), process.env);
     if (!parsed.ok)
         return fail(parsed.error);
     const options = parsed.options;