scenescout 3.22.0 → 3.23.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

package/README.md

@@ -485,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/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

@@ -777,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;

package/dist/engine/brief.js

@@ -49,7 +49,7 @@ export function moduleOf(route) {
  * to the point, is stable — the same routes produce the same split every time,
  * so a re-run of a lane can be given the same brief.
  */
-export function splitRoutes(routes, laneCount) {
+export function splitRoutes(routes, laneCount, order) {
     const lanes = Math.max(1, Math.min(Math.floor(laneCount) || 1, MAX_LANES));
     const byModule = new Map();
     for (const route of routes) {
@@ -63,9 +63,16 @@ export function splitRoutes(routes, laneCount) {
     // Biggest first, then by name, and each module's own routes sorted: nothing
     // about the split may depend on the order the routes were discovered in, or
     // a lane that has to be re-run cannot be handed the same brief.
-    const modules = [...byModule.entries()]
+    const sorted = [...byModule.entries()]
         .map(([name, list]) => [name, [...list].sort((a, b) => a.localeCompare(b))])
         .sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]));
+    // Given an order (a run continuing an earlier one, from-run.ts), a route's
+    // place in it decides: the modules are dealt by their earliest route, and
+    // each lane takes its routes in that order, so every lane starts on what the
+    // order puts first. Routes it does not name go after, in the stable order.
+    const rank = order ? new Map(order.map((r, i) => [r, i])) : null;
+    const at = (r) => rank?.get(r) ?? Number.MAX_SAFE_INTEGER;
+    const modules = rank ? [...sorted].sort((a, b) => Math.min(...a[1].map(at)) - Math.min(...b[1].map(at))) : sorted;
     const out = Array.from({ length: lanes }, () => ({ modules: [], routes: [] }));
     for (const [name, list] of modules) {
         let smallest = 0;
@@ -75,6 +82,9 @@ export function splitRoutes(routes, laneCount) {
         out[smallest].modules.push(name);
         out[smallest].routes.push(...list);
     }
+    if (rank)
+        for (const lane of out)
+            lane.routes = [...lane.routes].sort((a, b) => at(a) - at(b));
     // A lane with nothing to do is a browser held open for no reason.
     return out.filter((lane) => lane.routes.length > 0);
 }
@@ -93,7 +103,7 @@ function signInArgument(opts) {
 }
 /** The lanes to run, each with the objective to attach with. */
 export function planLanes(routes, laneCount, opts = {}) {
-    return splitRoutes(routes, laneCount).map((lane, i) => ({
+    return splitRoutes(routes, laneCount, opts.order).map((lane, i) => ({
         lane: laneName(lane.modules, i),
         objective: laneObjective(lane.modules, opts.goal),
         modules: lane.modules,
@@ -101,6 +111,23 @@ export function planLanes(routes, laneCount, opts = {}) {
         landing: landingOf(lane.routes),
     }));
 }
+/**
+ * The lanes of a replay (from-run.ts replayPlan): one per session of the
+ * recorded run, with its routes in the order it took them, not a new split.
+ * Named as a split's lanes are, by what they own, and made unique.
+ */
+export function replayBriefs(lanes, goal) {
+    const taken = new Set();
+    return lanes.map((l, i) => {
+        const modules = [...new Set(l.routes.map(moduleOf))];
+        const base = laneName(modules, i);
+        let lane = base;
+        for (let k = 2; taken.has(lane); k += 1)
+            lane = `${base.slice(0, LANE_NAME_MAX - `-${k}`.length)}-${k}`;
+        taken.add(lane);
+        return { lane, objective: laneObjective(modules, goal), modules, routes: [...l.routes], landing: landingOf(l.routes) };
+    });
+}
 /**
  * The first of a lane's routes a browser can open as it stands. A route the
  * engine normalised (`/orders/:id`) is a pattern, not an address; a lane with
@@ -143,6 +170,9 @@ export function formatBriefs(briefs, opts = {}) {
     const mode = opts.mode ?? "read-only";
     const lines = [
         `LANE PLAN — ${briefs.length} lane(s) over ${briefs.reduce((n, b) => n + b.routes.length, 0)} route(s).`,
+        ...(opts.fromRunNote
+            ? [`This run ${opts.fromRunNote}. Each lane's routes are listed in the order to take them, and what to do first is under each lane: pass it on.`]
+            : []),
         ``,
         `Give each lane its own agent. Every lane attaches with its own session name, so the browsers run genuinely in parallel, and lands on its own first route rather than the home page:`,
         `  scout_attach { session: "<lane>", url: "<origin><landing>", projectPath, mode: "${mode}"${signInArgument(opts)}, objective: "<objective>" }`,
@@ -158,6 +188,8 @@ export function formatBriefs(briefs, opts = {}) {
         lines.push(`owns: ${b.modules.join(", ")} (${b.routes.length} route(s))`);
         lines.push(`landing: ${b.landing}`);
         lines.push(`routes: ${b.routes.slice(0, 20).join(", ")}${b.routes.length > 20 ? ` … and ${b.routes.length - 20} more` : ""}`);
+        for (const l of opts.laneLines?.(b) ?? [])
+            lines.push(l);
         lines.push(``);
     }
     return lines.join("\n");

package/dist/engine/ci-lanes.js

@@ -8,7 +8,7 @@
  * and how the lanes' endings become the run's. The loop that runs them is
  * src/ci-run.ts; the shared budget is engine/ci.ts's. Why: ADR 20.
  */
-import { LANE_RULES, planLanes } from "./brief.js";
+import { LANE_RULES, planLanes, replayBriefs } from "./brief.js";
 import { CI_TOOLS } from "./ci.js";
 /** The session the run attaches first. It plans, holds no lane, and writes the report once every lane is done. */
 export const PLANNER_SESSION = "default";
@@ -88,6 +88,10 @@ export function crawlNotes(text) {
 export function crawlFoundNothing(text) {
     return /^(?:\[session [^\]]*\]\s*)?(Nothing to crawl|Nothing new to crawl|No routes to crawl yet)/m.test(text);
 }
+/** The routes a run has to plan with: the page it attached on, then every route the planning crawl listed. */
+export function plannedRoutes(target, notes) {
+    return [...new Set([routeOf(target), ...notes.keys()])];
+}
 /** The path a target URL opens, as a route: the planning crawl never lists the page the run attached on. */
 function routeOf(url) {
     try {
@@ -119,12 +123,12 @@ export function laneSessions(names) {
  * run has nothing to split, and explores in one loop, saying why.
  */
 export function planCiLanes(o) {
-    const routes = [...new Set([routeOf(o.target), ...o.notes.keys()])];
+    const routes = plannedRoutes(o.target, o.notes);
     if (o.count < 2)
         return { lanes: [], oneLoop: "one lane was asked for" };
     if (o.notes.size === 0 && o.planningFailed)
         return { lanes: [], oneLoop: `${o.planningFailed}, so there was nothing to split` };
-    const briefs = planLanes(routes, o.count, { goal: o.focus, mode: o.mode });
+    const briefs = planLanes(routes, o.count, { goal: o.focus, mode: o.mode, ...(o.order ? { order: o.order } : {}) });
     if (briefs.length < 2) {
         const where = briefs[0]?.modules[0];
         return {
@@ -132,16 +136,27 @@ export function planCiLanes(o) {
             oneLoop: `the planning crawl found ${routes.length} route(s), all in ${where ? `one module (${where})` : "no module"}, so there was nothing to split`,
         };
     }
+    return { lanes: asCiLanes(briefs, o.target, o.notes) };
+}
+function asCiLanes(briefs, target, notes) {
     const sessions = laneSessions(briefs.map((b) => b.lane));
-    return {
-        lanes: briefs.map((b, i) => ({
-            ...b,
-            session: sessions[i],
-            // On the target's origin whatever the route says: a path written `//host/x` must not become another host.
-            url: `${new URL(o.target).origin}${b.landing.startsWith("/") ? "" : "/"}${b.landing}`,
-            crawl: b.routes.flatMap((r) => o.notes.get(r) ?? []).slice(0, LIST_MAX),
-        })),
-    };
+    return briefs.map((b, i) => ({
+        ...b,
+        session: sessions[i],
+        // On the target's origin whatever the route says: a path written `//host/x` must not become another host.
+        url: `${new URL(target).origin}${b.landing.startsWith("/") ? "" : "/"}${b.landing}`,
+        crawl: b.routes.flatMap((r) => notes.get(r) ?? []).slice(0, LIST_MAX),
+    }));
+}
+/**
+ * A replayed run's lanes (from-run.ts replayPlan): one per session the
+ * recorded run had, each with its routes in recorded order, however many lanes
+ * were asked for. With fewer than two the run replays in one loop.
+ */
+export function planReplayLanes(o) {
+    if (o.lanes.length < 2)
+        return { lanes: [], oneLoop: `the recorded run had ${o.lanes.length === 1 ? "one session" : "no steps"}, so it is replayed in one loop` };
+    return { lanes: asCiLanes(replayBriefs(o.lanes, o.focus), o.target, new Map()) };
 }
 // ── what a lane is told ─────────────────────────────────────────────────────
 /**
@@ -171,6 +186,7 @@ export function ciLaneKickoff(o) {
         `Target: ${o.url}`,
         `Your lane: ${lane.objective}`,
         `Your routes (${lane.routes.length}): ${lane.routes.slice(0, LIST_MAX).join(", ")}${lane.routes.length > LIST_MAX ? ` … and ${lane.routes.length - LIST_MAX} more` : ""}`,
+        ...(o.fromRun ?? []),
         `Your browser is on ${routeOf(lane.url)}.`,
         lane.crawl.length > 0 ? `What the planning crawl saw on your routes:\n${lane.crawl.map((l) => `  ${l.trim()}`).join("\n")}` : "",
         `Project directory (for scout_scan): ${o.projectDir}`,