scenescout 3.15.0 → 3.16.0

package/dist/engine/check.js

@@ -12,9 +12,11 @@
  */
 import { createHash } from "node:crypto";
 import { BROWSER_ENGINES } from "../browsers.js";
+import { BASELINE_MODES, baselineEvidence, baselineFingerprint, countStatuses, describeChange, parseThreshold, VISUAL_RULE, } from "./baseline.js";
 import { flowStepEvidence } from "./flow.js";
 import { parseLimitFlag } from "./limits.js";
-import { redactSecrets } from "./memory.js";
+import { redactRoute, redactSecrets } from "./memory.js";
+import { SARIF_ANCHOR_FALLBACKS, checkSarifAnchor, sarifFileFor, sarifLocation } from "./sarif.js";
 import { httpErrorDetail, httpStatusOf } from "./oracles.js";
 export const CHECK_SEVERITIES = ["high", "medium", "low"];
 export const FAIL_ON = [...CHECK_SEVERITIES, "never"];
@@ -65,7 +67,11 @@ export const CHECK_RULES = {
         title: "Control covered by pinned chrome",
         help: "A fixed or sticky element sits on top of the control, so clicks land on it instead.",
     },
-    "clipped-control": { severity: "medium", title: "Control unreachable", help: "The control is clipped inside a container that cannot scroll." },
+    "clipped-control": {
+        severity: "medium",
+        title: "Control unreachable",
+        help: "The control is clipped inside a container that cannot scroll and has no control beside it to page it.",
+    },
     "offpage-control": { severity: "medium", title: "Control outside the page", help: "The control is laid out where no scrolling can reach it." },
     "overlapping-controls": { severity: "low", title: "Controls overlap", help: "Two controls in the same layer cover most of each other." },
     "broken-image": { severity: "medium", title: "Broken image", help: "The browser could not render the image." },
@@ -78,7 +84,11 @@ export const CHECK_RULES = {
     contrast: { severity: "low", title: "Text contrast below WCAG", help: "Text needs 4.5:1 (3:1 when large) against its background." },
     "focus-indicator": { severity: "low", title: "No visible focus indicator", help: "Tabbing to the control changes nothing on screen." },
     "horizontal-scroll": { severity: "medium", title: "Page scrolls sideways", help: "Content is wider than the viewport." },
-    "tiny-target": { severity: "low", title: "Small click target", help: "Below the 24px WCAG 2.2 target-size minimum." },
+    "tiny-target": {
+        severity: "low",
+        title: "Small click target",
+        help: "Below the 24px WCAG 2.2 target-size minimum, measured on what the user clicks (a native input's label or drop zone), with another target inside its 24px circle.",
+    },
     "clipped-text": { severity: "low", title: "Text clipped", help: "Text is wider than its box and cut off without an ellipsis." },
     "image-aspect": { severity: "low", title: "Image distorted", help: "The rendered box does not match the image's proportions." },
     "flow-step-failed": {
@@ -86,6 +96,11 @@ export const CHECK_RULES = {
         title: "Saved flow broke",
         help: "A step of a flow saved in .scenescout/flows could not be done, or what it expected was not there. The evidence names the flow, the step and what happened instead.",
     },
+    [VISUAL_RULE]: {
+        severity: "high",
+        title: "Differs from its visual baseline",
+        help: "A page or element listed in the baselines' targets.json no longer looks like its baseline (--baseline compare): more of its pixels changed than --baseline-threshold allows, or its size changed. It is also filed when the page or element could not be captured at all, or its baseline cannot be used (half there, unreadable, or taken with other settings). An intended change is approved by running the check with --baseline update (and committing the new baseline, where the project keeps baselines in a folder it commits).",
+    },
 };
 /**
  * Rules whose measurement is exact and whose meaning depends on a convention
@@ -189,16 +204,28 @@ export function geometryRule(line) {
  *
  * A fact under a worth-a-look rule goes to `worthALook` instead, deduplicated
  * the same way; the two lists never share an entry.
+ *
+ * Visual baselines add one issue per target that is not met (baseline.ts
+ * decides which). Each target is its own fact already, so these skip the
+ * dedup, and their fingerprint comes from the target, not the evidence: the
+ * evidence carries this run's percentage, and the same target changing by a
+ * different amount is still the same alert.
  */
-export function checkFindings(routes, origin, ignore = [], flows = []) {
+export function checkFindings(routes, origin, ignore = [], flows = [], baselines = null) {
     const byKey = new Map();
     const looks = new Map();
+    /** Evidence as it is written: no origin, no secret, and bounded. */
+    const cleanEvidence = (evidence) => redactSecrets(withoutOrigin(evidence, origin)).slice(0, 300);
     const add = (rule, evidence, route, opts = {}) => {
         if (ignore.includes(rule))
             return;
-        const clean = redactSecrets(withoutOrigin(evidence, origin)).slice(0, 300);
+        const clean = cleanEvidence(evidence);
         const key = `${rule}\u0000${clean}`;
-        const found = byKey.get(key) ?? looks.get(key);
+        const issue = byKey.get(key);
+        // A fact a crawled page and a flow both show points at the flow: the flow is the file that reproduces it.
+        if (issue && opts.flow && !issue.flow)
+            issue.flow = opts.flow;
+        const found = issue ?? looks.get(key);
         if (found) {
             if (!found.routes.includes(route))
                 found.routes.push(route);
@@ -215,6 +242,7 @@ export function checkFindings(routes, origin, ignore = [], flows = []) {
             evidence: clean,
             routes: [route],
             ...(opts.embed ? { embed: opts.embed } : {}),
+            ...(opts.flow ? { flow: opts.flow } : {}),
             fingerprint,
         });
     };
@@ -251,13 +279,28 @@ export function checkFindings(routes, origin, ignore = [], flows = []) {
     }
     for (const f of flows) {
         for (const { path, violation } of f.violations)
-            add(violationRule(violation), violation.detail, path, { embed: violation.embed });
+            add(violationRule(violation), violation.detail, path, { embed: violation.embed, flow: f.file });
         // A refused step is not the app's defect: the check reports it as "could not run" (refusedFlowReason).
         if (f.outcome.status === "failed")
-            add("flow-step-failed", flowStepEvidence(f), f.outcome.path);
+            add("flow-step-failed", flowStepEvidence(f), f.outcome.path, { flow: f.file });
+    }
+    const visual = [];
+    if (baselines && !ignore.includes(VISUAL_RULE)) {
+        for (const r of baselines.results) {
+            const evidence = baselineEvidence(r, baselines);
+            if (evidence === null)
+                continue;
+            visual.push({
+                rule: VISUAL_RULE,
+                severity: CHECK_RULES[VISUAL_RULE].severity,
+                evidence: cleanEvidence(evidence),
+                routes: [r.path],
+                fingerprint: baselineFingerprint(baselines.engine, r),
+            });
+        }
     }
     return {
-        issues: [...byKey.values()].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.rule.localeCompare(b.rule)),
+        issues: [...byKey.values(), ...visual].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.rule.localeCompare(b.rule)),
         worthALook: [...looks.values()].sort((a, b) => a.rule.localeCompare(b.rule)),
     };
 }
@@ -299,15 +342,8 @@ export function withoutOwnResponse(r) {
     const own = httpErrorDetail("GET", r.url.replace(/#.*$/, ""), r.status);
     return { ...r, violations: r.violations.filter((v) => !(v.kind === "http_error" && v.detail === own)) };
 }
-/**
- * Routes are links the app printed, and a link can carry a token
- * (`?reset=…`, `?api_key=…`). Evidence is redacted where issues are built;
- * this does the same for every route string before anything is written.
- */
-export function redactRoute(route) {
-    // The trailing "[n secrets redacted]" note belongs to prose; in a route it would read as part of the path.
-    return redactSecrets(route).replace(/ \[\d+ secrets? redacted\]$/, "");
-}
+/** Lives beside redactSecrets so the baselines' file names (baseline.ts) use it too; exported here as before. */
+export { redactRoute };
 export function redactRoutes(routes) {
     const clean = redactRoute;
     return routes.map((r) => ({
@@ -317,6 +353,16 @@ export function redactRoutes(routes) {
         violations: r.violations.map((v) => ({ ...v, url: clean(v.url) })),
     }));
 }
+/**
+ * The same redaction for visual baselines: a target's path, and the reason a
+ * picture could not be taken, which can quote a URL the app redirected to.
+ */
+export function redactBaselineRun(run) {
+    return {
+        ...run,
+        results: run.results.map((r) => ({ ...r, path: redactRoute(r.path), ...(r.detail !== undefined ? { detail: redactSecrets(r.detail) } : {}) })),
+    };
+}
 /** The same redaction for what flows measured: the page paths and the request URLs their violations quote. */
 export function redactFlowRuns(runs) {
     return runs.map((f) => ({
@@ -374,6 +420,10 @@ export const CHECK_OPTION_NAMES = [
     "gate-retests",
     "action-timeout-ms",
     "nav-timeout-ms",
+    "baseline",
+    "baselines",
+    "baseline-threshold",
+    "sarif-file-anchor",
 ];
 export const MAX_CHECK_ROUTES = 150;
 /** Link discovery rounds: each crawl reveals the routes its pages link to. Past a few, a site is paginating rather than revealing. */
@@ -476,6 +526,22 @@ export function parseCheckArgs(args, cwd) {
     const gateRetests = oneOf("gate-retests", GATE_RETESTS, DEFAULT_SETTINGS.gateRetests);
     if (!gateRetests)
         return { ok: false, error: `--gate-retests must be one of ${GATE_RETESTS.join(", ")}` };
+    const baseline = oneOf("baseline", BASELINE_MODES, "off");
+    if (!baseline)
+        return { ok: false, error: `--baseline must be one of ${BASELINE_MODES.join(", ")}` };
+    const threshold = parseThreshold(flags.get("baseline-threshold"));
+    if (!threshold.ok)
+        return threshold;
+    const baselinesDir = flags.get("baselines");
+    if (baselinesDir !== undefined && baselinesDir.trim() === "")
+        return { ok: false, error: "--baselines needs a directory" };
+    // A setting that would do nothing is a mistake to point out, not to ignore: the check would run without the baselines asked for.
+    if (baseline === "off" && (baselinesDir !== undefined || flags.has("baseline-threshold"))) {
+        return { ok: false, error: "--baselines and --baseline-threshold apply only with --baseline compare or --baseline update" };
+    }
+    const anchor = flags.has("sarif-file-anchor") ? checkSarifAnchor(flags.get("sarif-file-anchor")) : undefined;
+    if (anchor && !anchor.ok)
+        return anchor;
     const resolve = (p) => resolveArgPath(cwd, p);
     return {
         ok: true,
@@ -497,6 +563,10 @@ export function parseCheckArgs(args, cwd) {
             flowWrites,
             onRefusedStep,
             gateRetests,
+            baseline,
+            ...(baselinesDir !== undefined ? { baselinesDir: resolve(baselinesDir) } : {}),
+            baselineThreshold: threshold.value,
+            ...(anchor ? { sarifFileAnchor: anchor.value } : {}),
         },
     };
 }
@@ -550,10 +620,13 @@ export function describeSettings(result) {
 }
 const SARIF_LEVEL = { high: "error", medium: "warning", low: "note" };
 /**
- * SARIF 2.1.0, for code-scanning dashboards. A UI check has no source file to
- * point at, so each result's location is the route, relative to the checked
- * app (the APP base id). Fingerprints come from the evidence, not the
- * location, so a preview deployment on a new URL does not reopen every alert.
+ * SARIF 2.1.0, for code-scanning dashboards. Code scanning keeps a result
+ * only when its location is a repository file, so each result points at one
+ * (sarif.ts says which) and carries its routes in logical locations, in
+ * `properties.routes` and in its message. Fingerprints come from the
+ * evidence, not the location, so a preview deployment on a new URL does not
+ * reopen every alert; an unmet visual baseline's comes from its target and
+ * browser instead.
  */
 const RETEST_SARIF_RULE = {
     id: "open-finding-reproduces",
@@ -562,39 +635,39 @@ const RETEST_SARIF_RULE = {
     help: { text: "A finding an earlier run filed and left open failed the same way when its page loaded again. It gates according to --gate-retests." },
     defaultConfiguration: { level: "error" },
 };
-function sarifLocation(route) {
-    return route === SHARED_CHROME_ROUTE
-        ? {
-            physicalLocation: { artifactLocation: { uri: "", uriBaseId: "APP" } },
-            message: { text: "the app's shared shell, on every page that renders it" },
-        }
-        : { physicalLocation: { artifactLocation: { uri: route.replace(/^\//, ""), uriBaseId: "APP" } } };
+function routeLocation(file, route) {
+    return route === SHARED_CHROME_ROUTE ? sarifLocation(file, route, "the app's shared shell, on every page that renders it") : sarifLocation(file, route);
+}
+/** Where a result was seen, for its message: the first three routes and how many more. */
+function onRoutes(routes) {
+    return ` — on ${routes.slice(0, 3).join(", ")}${routes.length > 3 ? ` and ${routes.length - 3} more` : ""}`;
 }
-export function toSarif(result, toolVersion) {
+/** `files` defaults to package.json as the anchor, with no flows directory; the CLI always passes what it resolved. */
+export function toSarif(result, toolVersion, files = { anchor: SARIF_ANCHOR_FALLBACKS[0] }) {
     const used = [...new Set(result.issues.map((i) => i.rule))];
     const lookRules = [...new Set(result.worthALook.map((o) => o.rule))];
-    const base = new URL(result.url);
     const reproducing = retestGateFailures(result);
     const refused = result.flows.filter((f) => f.outcome.status === "refused");
     const issueResults = result.issues.map((i) => ({
         ruleId: i.rule,
         level: SARIF_LEVEL[i.severity],
         message: {
-            text: `${CHECK_RULES[i.rule].title}: ${i.evidence}${i.routes.length > 1 ? ` (on ${i.routes.length} routes)` : ""}${i.embed ? ` (in an embed of ${i.embed})` : ""}`,
+            text: `${CHECK_RULES[i.rule].title}: ${i.evidence}${i.embed ? ` (in an embed of ${i.embed})` : ""}${onRoutes(i.routes)}`,
         },
-        locations: i.routes.slice(0, 10).map(sarifLocation),
+        locations: i.routes.slice(0, 10).map((route) => routeLocation(sarifFileFor(files, i.flow), route)),
         partialFingerprints: { "scenescoutCheck/v1": i.fingerprint },
+        properties: { routes: i.routes, ...(i.flow ? { flow: i.flow } : {}) },
     }));
     // Always "note", whatever --fail-on says: a result a code-scanning dashboard shows, never one that reads as an error.
     const lookResults = result.worthALook.map((o) => ({
         ruleId: o.rule,
         level: "note",
         message: {
-            text: `Worth a look — ${WORTH_A_LOOK_RULES[o.rule].title}: ${o.evidence}${o.routes.length > 1 ? ` (on ${o.routes.length} routes)` : ""}. A defect only if your project uses ${o.convention}.`,
+            text: `Worth a look — ${WORTH_A_LOOK_RULES[o.rule].title}: ${o.evidence}${onRoutes(o.routes)}. A defect only if your project uses ${o.convention}.`,
         },
-        locations: o.routes.slice(0, 10).map(sarifLocation),
+        locations: o.routes.slice(0, 10).map((route) => routeLocation(files.anchor, route)),
         partialFingerprints: { "scenescoutCheck/v1": o.fingerprint },
-        properties: { tier: "worth-a-look", convention: o.convention },
+        properties: { tier: "worth-a-look", convention: o.convention, routes: o.routes },
     }));
     // Only the re-tests that fail the gate are results: a reviewer reading code scanning sees what failed it.
     const retestResults = reproducing.map((r) => ({
@@ -602,9 +675,10 @@ export function toSarif(result, toolVersion) {
         // The severity the finding was filed at, as the page rules map theirs; an unknown one reads as the worst.
         level: SARIF_LEVEL[CHECK_SEVERITIES.includes(r.severity) ? r.severity : "high"],
         message: {
-            text: `Open finding still reproduces: [${r.severity}] ${r.title} (${r.id}) — ${r.signatures.join(", ")} (gated by --gate-retests ${result.settings.gateRetests})`,
+            text: `Open finding still reproduces: [${r.severity}] ${r.title} (${r.id}) — ${r.signatures.join(", ")}${onRoutes([r.path])} (gated by --gate-retests ${result.settings.gateRetests})`,
         },
-        locations: [{ physicalLocation: { artifactLocation: { uri: r.path.replace(/^\//, ""), uriBaseId: "APP" } } }],
+        locations: [routeLocation(files.anchor, r.path)],
+        properties: { routes: [r.path] },
         partialFingerprints: { "scenescoutCheck/v1": createHash("sha256").update(`retest\u0000${r.id}`).digest("hex").slice(0, 32) },
     }));
     return {
@@ -648,7 +722,7 @@ export function toSarif(result, toolVersion) {
                         })),
                     },
                 ],
-                originalUriBaseIds: { APP: { uri: `${base.origin}/` } },
+                properties: { app: new URL(result.url).origin },
                 results: [...issueResults, ...lookResults, ...retestResults],
             },
         ],
@@ -679,6 +753,69 @@ function routeList(routes) {
     const shown = routes.slice(0, 3).map(code);
     return shown.join(", ") + (routes.length > 3 ? ` and ${routes.length - 3} more` : "");
 }
+const BASELINE_MARK = {
+    matches: "✓",
+    changed: "✗",
+    "no-baseline": "○",
+    unusable: "✗",
+    "not-captured": "⊘",
+    updated: "↻",
+};
+/** One target's line in the report. */
+function baselineLine(r, run) {
+    const what = `${BASELINE_MARK[r.status]} ${code(r.element)} on ${code(r.path)}`;
+    const notes = [r.platformNote, r.partial]
+        .filter(Boolean)
+        .map((n) => ` _(${cell(n)})_`)
+        .join("");
+    switch (r.status) {
+        case "matches":
+            return `- ${what}: ${run.mode === "update" ? `within the threshold of its baseline (${r.diff?.percent ?? 0}% changed), which was left as it was` : `matches (${r.diff?.percent ?? 0}% changed)`}${notes}`;
+        case "changed": {
+            const files = r.files ? ` — expected ${code(r.files.expected)}, now ${code(r.files.actual)}, diff ${code(r.files.diff)}` : "";
+            return `- ${what}: ${r.diff ? describeChange(r.diff, run.threshold) : "it no longer matches its baseline"}${files}${notes}`;
+        }
+        case "no-baseline":
+            return `- ${what}: no baseline yet${notes}`;
+        case "unusable":
+            return `- ${what}: its baseline cannot be used: ${cell(r.detail ?? "no reason given")}`;
+        case "not-captured":
+            return `- ${what}: could not be captured: ${cell(r.detail ?? "no reason given")}${run.mode === "update" ? "; its baseline was not written" : ""}`;
+        case "updated":
+            return `- ${what}: baseline written to ${code(r.baseline)} (${cell(r.detail ?? "updated")})${notes}`;
+    }
+}
+/** The report's section on visual baselines: every target and what became of it. */
+function formatBaselines(run) {
+    const c = countStatuses(run.results);
+    const counts = [
+        ["changed", "changed"],
+        ["unusable", "unusable"],
+        ["not-captured", "not captured"],
+        ["no-baseline", "no baseline yet"],
+        ["updated", "updated"],
+        ["matches", run.mode === "update" ? "left as they were" : "match"],
+    ]
+        .filter(([k]) => c[k] > 0)
+        .map(([k, label]) => `${c[k]} ${label}`)
+        .join(" · ");
+    const lines = [
+        `## Visual baselines (${run.results.length})`,
+        "",
+        `${run.mode === "update" ? "Updated" : "Compared"} in ${run.engine}, baselines in ${code(run.dir)} · ${run.threshold}% of a picture's pixels may change · ${counts}`,
+        "",
+        ...run.results.map((r) => baselineLine(r, run)),
+    ];
+    if (c.changed > 0)
+        lines.push("", "The pictures are beside this report, under `visual/` (in the job's artifact on CI): the baseline, the picture now, and the changed pixels in red.");
+    if (c["no-baseline"] > 0 || c.unusable > 0) {
+        lines.push("", "A target with no baseline yet is listed and never fails; one whose baseline cannot be used fails until it is taken again. Run the check with `--baseline update` to take them.");
+    }
+    if (run.results.some((r) => r.platformNote)) {
+        lines.push("", "_Some baselines were taken on another operating system. Each one draws text differently, so a change there may be the system's rather than the app's: take baselines where the check runs._");
+    }
+    return lines;
+}
 /** One markdown list item for an issue: its title, rule, evidence and routes. */
 export function issueLine(i) {
     return `**${CHECK_RULES[i.rule].title}** \`${i.rule}\`: ${cell(i.evidence)}${i.embed ? ` _(in an embed of ${i.embed}: its behaviour, not the app's)_` : ""} — ${routeList(i.routes)}`;
@@ -740,6 +877,8 @@ export function formatCheck(result) {
     lines.push(`${result.url} · ${result.routes.length} route(s) · mode ${result.mode} · gate: ${result.failOn === "never" ? "report only" : `fail on ${result.failOn}${result.failOn === "low" ? "" : " or worse"}`}`);
     lines.push("");
     const unaudited = unauditedRoutes(result.routes).length;
+    // Nothing compared is not a match: a target with no baseline yet is named beside the verdict, as an unmeasured design is.
+    const uncompared = result.baselines?.mode === "compare" ? countStatuses(result.baselines.results)["no-baseline"] : 0;
     const failingText = retestsFailing > 0
         ? `${failing} failing the gate (${failing - retestsFailing} issue(s), ${retestsFailing} re-tested finding(s))`
         : `${failing} issue(s) at the gate's severity`;
@@ -748,6 +887,7 @@ export function formatCheck(result) {
             ? `${couldNotRun > 0 ? "passed" : "**PASSED**"} — ${counts.high} high · ${counts.medium} medium · ${counts.low} low`
             : `${couldNotRun > 0 ? "failed" : "**FAILED**"} — ${failingText} · ${counts.high} high · ${counts.medium} medium · ${counts.low} low`) +
         (unaudited > 0 ? ` · design not measured on ${unaudited} route(s)` : "") +
+        (uncompared > 0 ? ` · ${uncompared} visual target(s) not compared: no baseline yet` : "") +
         (result.worthALook.length > 0 ? ` · ${result.worthALook.length} worth a look, never gated` : ""));
     // Right under the verdict: what a green check was allowed to do is part of what it means.
     lines.push("", `Settings — ${describeSettings(result)}`);
@@ -772,6 +912,8 @@ export function formatCheck(result) {
         for (const s of result.skippedFlows)
             lines.push(`- skipped ${code(s.file)}: ${cell(s.reason)}`);
     }
+    if (result.baselines)
+        lines.push("", ...formatBaselines(result.baselines));
     if (result.retest && result.retest.open > 0) {
         const { open, results } = result.retest;
         lines.push("", `## Open findings re-tested (${results.length} of ${open})`, "");
@@ -837,6 +979,7 @@ export function toSummaryJson(result, toolVersion) {
         })),
         skippedFlows: result.skippedFlows,
         retest: result.retest,
+        baselines: result.baselines ?? null,
         issues: result.issues,
         // Apart from `issues` and `counts`, which the gate reads: none of these is counted or gated.
         worthALook: result.worthALook,

package/dist/engine/ci-lanes.js

@@ -0,0 +1,215 @@
+/**
+ * Lanes for `scenescout ci` (--lanes): the app split between several model
+ * loops that explore at once, each in its own browser session and its own
+ * part of the app, drawing on the run's one budget, with their findings folded
+ * into the one report. This file holds the rules, none of which needs a
+ * browser or a network: which routes the planning crawl found, how they are
+ * split (brief.ts, the split scout_lane_brief makes), what each lane is told,
+ * 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 { 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";
+/** Crawls the planning step makes at most: each visits the routes the pages of the one before linked to. */
+export const PLAN_CRAWL_ROUNDS = 3;
+/** The most routes a lane's first message lists, and the most crawl lines it is handed. */
+const LIST_MAX = 40;
+/**
+ * A lane's tools: an exploring run's, less scout_report. The run writes one
+ * report for every lane once all are done; a lane that wrote its own would
+ * report the others' work as unfinished.
+ */
+export const LANE_TOOLS = CI_TOOLS.filter((t) => t !== "scout_report");
+// ── what the planning crawl found ───────────────────────────────────────────
+/**
+ * A route line of a scout_crawl result: `<path> — <status> · <n> el …`, or
+ * `<path> — LOAD FAILED`. The path is what the crawl visited, as the browser
+ * opened it.
+ */
+const CRAWL_LINE = /^(\/\S*) — (.+)$/;
+/** The heading of the crawl's problem list, whose entries name a route and say what is wrong on it. */
+const PROBLEMS_HEADING = /^PROBLEM ROUTES \(\d+\):$/;
+/** A problem entry's first line: the route, then ` → …`, `: <why it did not load>`, or nothing (its detail lines follow, indented). */
+const PROBLEM_LINE = /^(\/\S*?)(?: →.*|: .*)?$/;
+/**
+ * What a scout_crawl result says about each route it visited: the route's own
+ * line, then whatever its problem list says about it. Routes it skipped as
+ * off-origin are not the app's, and are left out.
+ */
+export function crawlNotes(text) {
+    const notes = new Map();
+    const add = (route, line) => {
+        const list = notes.get(route);
+        if (list)
+            list.push(line);
+        else
+            notes.set(route, [line]);
+    };
+    let inProblems = false;
+    let current = null;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trimEnd();
+        if (PROBLEMS_HEADING.test(line)) {
+            inProblems = true;
+            continue;
+        }
+        if (!inProblems) {
+            const m = CRAWL_LINE.exec(line);
+            if (m && !/^SKIPPED/.test(m[2]))
+                add(m[1], line);
+            continue;
+        }
+        if (line === "") {
+            // A blank line ends the entry it follows, not the list.
+            current = null;
+            continue;
+        }
+        if (!/^(\/|\s)/.test(line)) {
+            // A line that is neither a route nor a detail (the coverage line) ends the list.
+            inProblems = false;
+            current = null;
+            continue;
+        }
+        if (/^\s/.test(line)) {
+            if (current)
+                add(current, line);
+            continue;
+        }
+        const p = PROBLEM_LINE.exec(line);
+        current = p && notes.has(p[1]) ? p[1] : null;
+        if (current)
+            add(current, line);
+    }
+    return notes;
+}
+/** Whether a crawl had nothing left to visit, so another round would find nothing either. */
+export function crawlFoundNothing(text) {
+    return /^(?:\[session [^\]]*\]\s*)?(Nothing to crawl|Nothing new to crawl|No routes to crawl yet)/m.test(text);
+}
+/** The path a target URL opens, as a route: the planning crawl never lists the page the run attached on. */
+function routeOf(url) {
+    try {
+        const u = new URL(url);
+        return `${u.pathname}${u.search}`;
+    }
+    catch {
+        return "/";
+    }
+}
+/**
+ * Session names for the lanes: the lane's own name, unless another lane or the
+ * planner already has it. A session name is at most 40 characters.
+ */
+export function laneSessions(names) {
+    const taken = new Set([PLANNER_SESSION]);
+    return names.map((name, i) => {
+        let session = name;
+        for (let k = i + 1; taken.has(session); k += 1)
+            session = `${name.slice(0, 40 - `-${k}`.length)}-${k}`;
+        taken.add(session);
+        return session;
+    });
+}
+/**
+ * Split what the planning crawl found between `count` lanes, by brief.ts: whole
+ * modules (a route's first path segment) per lane, balanced by route count.
+ * Fewer lanes come back when there are fewer modules. With fewer than two the
+ * 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()])];
+    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 });
+    if (briefs.length < 2) {
+        const where = briefs[0]?.modules[0];
+        return {
+            lanes: [],
+            oneLoop: `the planning crawl found ${routes.length} route(s), all in ${where ? `one module (${where})` : "no module"}, so there was nothing to split`,
+        };
+    }
+    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),
+        })),
+    };
+}
+// ── what a lane is told ─────────────────────────────────────────────────────
+/**
+ * The system prompt every lane is given: the method, then the rules of an
+ * unattended run as one lane of several. The same for every lane of a run, so
+ * the provider's prompt cache serves them all; what differs goes in the
+ * lane's first message (ciLaneKickoff).
+ */
+export function ciLaneSystemPrompt(playbook, o) {
+    return (`${playbook}\n\n---\n\n` +
+        `# Running in CI, as one lane of several\n\n` +
+        `You are running unattended in a CI job, as one of several lanes exploring the same app at once, each in its own browser session and its own part of the app. There is no person to ask: never ask a question or wait for an answer; decide, and say in findings and notes what you assumed.\n\n` +
+        `- Your browser is already attached to the target in ${o.mode} mode, as your lane's own session. scout_attach, scout_close, scout_session, scout_playbook and scout_report are not available: the mode, the target and the session are fixed for this run, and the method is the text above. Skip the Setup steps that choose them, and never pass \`session\`.\n` +
+        `- The planner has crawled the routes it found, so route coverage may already read as complete. Your first message lists the routes your lane owns, from that crawl, and what it saw on them; the other lanes own the rest, at the same time. A route under your modules that the crawl did not list is yours too.\n` +
+        LANE_RULES.map((rule) => `- ${rule}\n`).join("") +
+        `- The level is ${o.level}. The run writes one report for every lane once all are done, and its contract counts what every lane did: do your share of it on your routes, the design audits included.\n` +
+        `- Tool results are text only; screenshots are not available. Long results are cut: prefer calls that return less, and snapshots only where you act.\n` +
+        `- When your routes are done, or your share of the budget is nearly spent, reply with a short summary and no tool call. That ends your lane; the others go on.\n`);
+}
+const n = (x) => x.toLocaleString("en-US");
+/** A lane's first message: which lane it is, what it owns, where its browser is, what the crawl saw there, and its share of the budget. */
+export function ciLaneKickoff(o) {
+    const { lane } = o;
+    const share = Math.max(1, Math.floor(o.caps.turns / o.laneCount));
+    return [
+        `Run an exploratory test session following the method, as lane "${lane.session}", one of ${o.laneCount} running at once.`,
+        `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` : ""}`,
+        `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}`,
+        `Level: ${o.level}`,
+        `Write mode: ${o.mode}`,
+        o.focus ? `Focus: ${o.focus}` : "",
+        `Budget: the run's ${o.caps.turns} model turns, ${n(o.caps.tokens)} tokens and ${Math.round(o.caps.wallMs / 60_000)} minutes are shared by the ${o.laneCount} lanes: plan on about ${share} turns. Several tool calls in one turn cost one turn. Every lane stops at the first cap the run reaches, and the report is written as it stands.`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+// ── how the lanes' endings become the run's ─────────────────────────────────
+/** Caps in the order capReached checks them, so a run ended by two names the one checked first. */
+const CAP_ORDER = ["time", "tokens", "turns"];
+/**
+ * What ended a run whose exploration was split into lanes. A model API failure
+ * in any lane is the run's, since it is what the workflow must fix, and so is
+ * a lane that broke after attaching (could-not-start on an attached lane: the
+ * run could not finish, exit 2). Otherwise the run ended at a cap if any lane
+ * was stopped by one, a lane the time cap left no time to attach included, and
+ * the model finished it only when every lane that ran finished by itself. A
+ * lane whose browser could not attach does not change that, but is named in
+ * the detail; when none could, the run could not start.
+ */
+export function mergeLaneStops(lanes) {
+    const failed = lanes.find((l) => l.attached && l.stop === "provider-error");
+    if (failed)
+        return { stop: "provider-error", stopDetail: `lane ${failed.session}${failed.stopDetail ? `: ${failed.stopDetail}` : ""}` };
+    const broke = lanes.find((l) => l.attached && l.stop === "could-not-start");
+    if (broke)
+        return { stop: "could-not-start", stopDetail: `lane ${broke.session}: ${broke.stopDetail ?? "it stopped for no reason it gave"}` };
+    const unattached = lanes.filter((l) => !l.attached && l.stop === "could-not-start").map((l) => l.session);
+    if (unattached.length === lanes.length) {
+        const first = lanes.find((l) => l.stopDetail);
+        return { stop: "could-not-start", stopDetail: `no lane could attach${first ? ` (${first.session}: ${first.stopDetail})` : ""}` };
+    }
+    const note = unattached.length > 0 ? { stopDetail: `${unattached.length} of ${lanes.length} lanes could not attach: ${unattached.join(", ")}` } : {};
+    for (const cap of CAP_ORDER)
+        if (lanes.some((l) => l.stop === cap))
+            return { stop: cap, ...note };
+    return { stop: "done", ...note };
+}