scenescout 3.22.0 → 3.23.1

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}`,