scenescout 3.14.1 → 3.16.0

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 };
+}

package/dist/engine/ci.js

@@ -11,9 +11,11 @@
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { BROWSER_ENGINES } from "../browsers.js";
+import { MAX_LANES } from "./brief.js";
 import { markdownCell } from "./check.js";
 import { parseLimitFlag } from "./limits.js";
 import { isWorthALook, redactSecrets } from "./memory.js";
+import { SARIF_ANCHOR_FALLBACKS, checkSarifAnchor, sarifLocation } from "./sarif.js";
 // ── options ─────────────────────────────────────────────────────────────────
 export const PROVIDERS = ["anthropic", "openai"];
 /** Where each provider's key is read from. Nothing else is: no flag, no file, no input. */
@@ -36,8 +38,31 @@ export const DEFAULT_EFFORT = "low";
  */
 export const CI_MODES = ["observe", "read-only", "safe-write", "destructive"];
 export const CI_LEVELS = ["minimal", "medium", "extensive"];
+/**
+ * How a filed finding is told apart from one already stored. `rule`: the
+ * store's rule alone (memory.ts isDuplicateFinding). `judge`: the rule first,
+ * then, for a filing the rule keeps apart, a model asked about the open
+ * findings on the same page (engine/dedup.ts DedupJudge), with the rule's
+ * decision kept whenever the model cannot answer. A CI run already sends
+ * pages to a model and holds a key, so it judges by default; the MCP server
+ * judges only when asked to (DEDUP_ENV or scout_attach {dedup}).
+ */
+export const DEDUP_MODES = ["rule", "judge"];
+export const DEFAULT_CI_DEDUP = "judge";
+/** Turns the dedup judge on for the MCP server: `rule` (the default) or `judge`. An attach's `dedup` wins over it. */
+export const DEDUP_ENV = "SCENESCOUT_DEDUP";
+/** Which provider the MCP server's dedup judge uses when both keys are in its environment. */
+export const DEDUP_PROVIDER_ENV = "SCENESCOUT_DEDUP_PROVIDER";
 export const DEFAULT_CAPS = { turns: 40, tokens: 1_500_000, wallMs: 20 * 60_000 };
 const CAP_BOUNDS = { turns: [1, 500], tokens: [1_000, 20_000_000], minutes: [1, 360] };
+/**
+ * How many model loops explore at once, each in its own browser session and
+ * its own part of the app (engine/ci-lanes.ts). 1 is the single loop. The most
+ * is scout_lane_brief's, since the split is the same one. Why the default is
+ * what it is: docs/benchmark.md, "Unattended runs".
+ */
+export const DEFAULT_LANES = 1;
+export const MAX_CI_LANES = MAX_LANES;
 /** Every option `scenescout ci` accepts; the ci action's inputs are these names (ci-test holds them equal). */
 export const CI_OPTION_NAMES = [
     "provider",
@@ -47,6 +72,7 @@ export const CI_OPTION_NAMES = [
     "max-turns",
     "max-tokens",
     "max-minutes",
+    "lanes",
     "price-in",
     "price-cached-in",
     "price-out",
@@ -62,6 +88,8 @@ export const CI_OPTION_NAMES = [
     "out",
     "show",
     "compare-url",
+    "dedup",
+    "sarif-file-anchor",
 ];
 /** The longest --show description: it becomes a line of the model's prompt. */
 export const MAX_SHOW = 200;
@@ -155,9 +183,13 @@ export function parseCiArgs(args, cwd) {
     const turns = whole("max-turns", CAP_BOUNDS.turns, DEFAULT_CAPS.turns);
     const tokens = whole("max-tokens", CAP_BOUNDS.tokens, DEFAULT_CAPS.tokens);
     const minutes = whole("max-minutes", CAP_BOUNDS.minutes, DEFAULT_CAPS.wallMs / 60_000);
-    for (const v of [turns, tokens, minutes])
+    const lanes = whole("lanes", [1, MAX_CI_LANES], DEFAULT_LANES);
+    for (const v of [turns, tokens, minutes, lanes])
         if (typeof v === "string")
             return { ok: false, error: v };
+    // The lanes share the run's turns rather than getting a cap each: fewer turns than lanes would leave a lane none.
+    if (lanes > turns)
+        return { ok: false, error: `--lanes ${lanes} needs --max-turns of at least ${lanes}: the lanes share the run's turns, and each needs one` };
     const price = {};
     for (const [flag, field] of [
         ["price-in", "input"],
@@ -202,6 +234,8 @@ export function parseCiArgs(args, cwd) {
         return { ok: false, error: `--show is at most ${MAX_SHOW} characters` };
     if (flags.has("show") && !show)
         return { ok: false, error: '--show needs a few words describing the element, e.g. --show "the Save button"' };
+    if (show && lanes > 1)
+        return { ok: false, error: "--lanes splits an exploration between model loops, and --show explores nothing: give one or the other" };
     let compareUrl;
     if (flags.has("compare-url")) {
         if (!show)
@@ -225,6 +259,12 @@ export function parseCiArgs(args, cwd) {
     const navTimeout = parseLimitFlag("nav", flags.get("nav-timeout-ms"));
     if (!navTimeout.ok)
         return navTimeout;
+    const dedup = flags.get("dedup") ?? DEFAULT_CI_DEDUP;
+    if (!DEDUP_MODES.includes(dedup))
+        return { ok: false, error: `--dedup must be one of ${DEDUP_MODES.join(", ")}` };
+    const anchor = flags.has("sarif-file-anchor") ? checkSarifAnchor(flags.get("sarif-file-anchor")) : undefined;
+    if (anchor && !anchor.ok)
+        return anchor;
     const resolve = (p) => (p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) ? p : `${cwd.replace(/[\\/]$/, "")}/${p}`);
     return {
         ok: true,
@@ -237,6 +277,7 @@ export function parseCiArgs(args, cwd) {
             ...(effort ? { effort } : {}),
             ...(baseUrl ? { baseUrl } : {}),
             caps: { turns: turns, tokens: tokens, wallMs: minutes * 60_000 },
+            lanes: lanes,
             ...(Object.keys(price).length > 0 ? { price } : {}),
             mode: mode,
             level: level,
@@ -247,9 +288,24 @@ export function parseCiArgs(args, cwd) {
             ...(compareUrl ? { compareUrl } : {}),
             ...(actionTimeout.value !== undefined ? { actionTimeoutMs: actionTimeout.value } : {}),
             ...(navTimeout.value !== undefined ? { navTimeoutMs: navTimeout.value } : {}),
+            dedup: dedup,
+            ...(anchor ? { sarifFileAnchor: anchor.value } : {}),
         },
     };
 }
+/**
+ * Why scout_attach did not leave a session the run can use, or null when it
+ * did: an error result, or a saved sign-in the app no longer accepts (the
+ * attach succeeds, and says so on a line of its own).
+ */
+export function attachFailure(r) {
+    const authFailed = r.text.split("\n").find((l) => l.startsWith("⚠ AUTH FAILED"));
+    if (authFailed)
+        return authFailed;
+    if (r.isError || /^ERROR:/.test(r.text))
+        return r.text.replace(/^ERROR:\s*/, "");
+    return null;
+}
 const present = (env, name) => (env[name] ?? "").trim() !== "";
 /**
  * Which provider a run uses: the one whose key is set. With both set the
@@ -278,6 +334,57 @@ export function detectProvider(env, options) {
         return { ok: false, error: `--effort must be one of ${EFFORTS[provider].join(", ")} for ${provider}` };
     return { ok: true, resolved: { provider, model: options.model ?? DEFAULT_MODEL[provider], effort, baseUrl: options.baseUrl ?? DEFAULT_BASE_URL[provider] } };
 }
+// ── the dedup judge's model ─────────────────────────────────────────────────
+/**
+ * The effort the dedup judge asks at: the lowest the provider's API takes.
+ * Measured, effort none judged as well as low and changed no verdict
+ * (docs/benchmark.md); the Messages API has no none, so Anthropic gets low.
+ */
+export function judgeEffort(provider) {
+    return EFFORTS[provider][0];
+}
+/** The MCP server's dedup mode from its environment: `rule` when unset. A value that is neither is refused, naming the variable. */
+export function dedupModeFromEnv(env) {
+    const raw = (env[DEDUP_ENV] ?? "").trim();
+    if (raw === "")
+        return "rule";
+    if (!DEDUP_MODES.includes(raw))
+        throw new Error(`${DEDUP_ENV} must be one of ${DEDUP_MODES.join(", ")}, not ${JSON.stringify(raw)}`);
+    return raw;
+}
+/**
+ * The key and model the MCP server's dedup judge uses when no CI run answers
+ * for it: the provider whose key is in the server's environment (with both,
+ * the one DEDUP_PROVIDER_ENV names), its default model and its lowest effort.
+ * A missing key is an answer (`ok: false`, and the rule decides); a provider
+ * name that is neither is refused.
+ */
+export function judgeKeyConfig(env) {
+    const named = (env[DEDUP_PROVIDER_ENV] ?? "").trim();
+    if (named !== "" && !PROVIDERS.includes(named))
+        throw new Error(`${DEDUP_PROVIDER_ENV} must be one of ${PROVIDERS.join(", ")}, not ${JSON.stringify(named)}`);
+    const withKey = PROVIDERS.filter((p) => present(env, KEY_ENV[p]));
+    let provider;
+    if (named !== "") {
+        provider = named;
+        if (!withKey.includes(provider))
+            return { ok: false, error: `${DEDUP_PROVIDER_ENV}=${provider} needs ${KEY_ENV[provider]} in the server's environment` };
+    }
+    else if (withKey.length === 0) {
+        return { ok: false, error: `the judge needs ${KEY_ENV.anthropic} or ${KEY_ENV.openai} in the server's environment` };
+    }
+    else if (withKey.length > 1) {
+        return { ok: false, error: `both ${KEY_ENV.anthropic} and ${KEY_ENV.openai} are set: set ${DEDUP_PROVIDER_ENV} to anthropic or openai to choose` };
+    }
+    else {
+        provider = withKey[0];
+    }
+    return {
+        ok: true,
+        resolved: { provider, model: DEFAULT_MODEL[provider], effort: judgeEffort(provider), baseUrl: DEFAULT_BASE_URL[provider] },
+        key: (env[KEY_ENV[provider]] ?? "").trim(),
+    };
+}
 /**
  * The environment the MCP server and its browser are started with: this
  * process's, without the keys. Nothing on that side needs them, and a key a
@@ -291,6 +398,12 @@ export function childEnv(env) {
             out[k] = v;
     // Nobody watches a CI run: the live view would only hold a port open.
     out.SCENESCOUT_LIVE = "off";
+    // ...and an unattended run opens nothing in a browser, even on a desktop, unless the user set it.
+    if (!out.SCENESCOUT_OPEN?.trim())
+        out.SCENESCOUT_OPEN = "none";
+    // The loop is text-only (toolResultText), so a finding's picture is kept for the report, never sent back. A choice the job made is its own.
+    if (!out.SCENESCOUT_EVIDENCE?.trim())
+        out.SCENESCOUT_EVIDENCE = "file";
     return out;
 }
 // ── never printing a key ────────────────────────────────────────────────────
@@ -321,7 +434,8 @@ export function addUsage(a, b) {
 /**
  * Which cap, if any, stops the run before its next model call. Checked
  * between turns: one turn's usage is only known after it, so a run can end
- * up to one turn over the token cap, and the report says by how much.
+ * up to one turn over the token cap (one per lane in a run split into lanes:
+ * see Budget), and the report says by how much.
  */
 export function capReached(spend, caps, now) {
     if (now - spend.startedAt >= caps.wallMs)
@@ -336,6 +450,31 @@ export function capReached(spend, caps, now) {
 export function wallLeftMs(spend, caps, now) {
     return Math.max(0, caps.wallMs - (now - spend.startedAt));
 }
+export function newBudget(caps, startedAt) {
+    return { caps, startedAt, turns: 0, usage: { ...NO_USAGE }, inFlight: 0 };
+}
+/** What the budget's loops have spent between them. */
+export function budgetSpend(b) {
+    return { turns: b.turns, usage: { ...b.usage }, startedAt: b.startedAt };
+}
+/** Take the next turn for one loop, or name the cap that refuses it. */
+export function takeTurn(b, now) {
+    const cap = capReached({ turns: b.turns + b.inFlight, usage: b.usage, startedAt: b.startedAt }, b.caps, now);
+    if (cap === null)
+        b.inFlight += 1;
+    return cap;
+}
+/** A taken turn's call has ended: counted with the usage it reported, or given back when it failed. */
+export function settleTurn(b, usage) {
+    // A settle with no turn taken would count a call nobody reserved: a bug in the caller, not a state to carry on from.
+    if (b.inFlight <= 0)
+        throw new Error("settleTurn without a turn taken: every settle must follow a takeTurn that returned null");
+    b.inFlight -= 1;
+    if (!usage)
+        return;
+    b.turns += 1;
+    b.usage = addUsage(b.usage, usage);
+}
 export const EXIT_CI = { completed: 0, couldNotRun: 2 };
 /**
  * A CI run reports and never gates, so its findings never set the exit code.
@@ -415,7 +554,8 @@ export function usageLine(spend, model, endedAt, override) {
  * closes itself, so the mode and the target cannot change), scout_session,
  * scout_playbook (the method is the system prompt), scout_screenshot (the
  * loop is text-only), scout_resolve (scout_verify records re-tests), and the
- * lane tools (one agent, ADR 14).
+ * lane tools (a run split into lanes is planned and folded by the run itself,
+ * not by a model: engine/ci-lanes.ts, ADR 20).
  */
 export const CI_TOOLS = [
     "scout_scan",
@@ -576,6 +716,14 @@ export function findingsThisRun(before, after) {
     const runsBefore = new Map(before.map((f) => [f.id, f.runs]));
     return after.filter((f) => f.status !== "resolved" && (!runsBefore.has(f.id) || f.runs > (runsBefore.get(f.id) ?? 0)));
 }
+/** One line on how a run deduplicated, for the summary. */
+export function dedupLine(d) {
+    if (d.by === "rule")
+        return "the rule alone";
+    const tokens = d.usage.input + d.usage.output;
+    return (`the rule, then the model judge${d.effort ? ` at effort ${d.effort}` : ""} for filings it kept apart: ${d.calls} call(s)` +
+        `${d.failed ? `, ${d.failed} without an answer (the rule decided those)` : ""}, ${n(tokens)} tokens (in the usage below), ${(d.ms / 1000).toFixed(1)}s`);
+}
 const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
 function pathOf(url) {
     try {
@@ -604,11 +752,15 @@ export function ciSummaryMarkdown(r, secrets = []) {
         ...(r.capture ? [] : [`| Level | ${r.level} — completion contract ${r.contractMet ? "met" : "not met (the report's gap ledger says what is missing)"} |`]),
         `| Mode | ${r.mode} |`,
         `| Model | ${r.provider} ${cell(r.model, secrets)}, effort ${r.effort} |`,
+        ...(r.lanes ? [`| Lanes | ${lanesCell(r.lanes, secrets)} |`] : []),
+        ...(r.dedup ? [`| Finding dedup | ${dedupLine(r.dedup)} |`] : []),
         `| Usage | ${usageLine(r.spend, r.model, r.endedAt, r.price)} |`,
         ``,
     ];
     if (r.capture)
         lines.push(...captureSummaryLines(r.capture, secrets));
+    if (r.lanes && r.lanes.sessions.length > 0)
+        lines.push(...laneSummaryLines(r.lanes, secrets));
     if (defects.length > 0) {
         lines.push(`| Severity | Category | Finding | Page |`, `|---|---|---|---|`);
         for (const f of defects.slice(0, 50))
@@ -627,6 +779,22 @@ export function ciSummaryMarkdown(r, secrets = []) {
     lines.push(r.capture ? `The pictures are in shots/.` : `The full report, with repro steps and the gap ledger, is report.md.`, ``);
     return lines.join("\n");
 }
+function lanesCell(l, secrets) {
+    if (l.oneLoop)
+        return `${l.asked} asked; explored in one loop: ${cell(l.oneLoop, secrets)}`;
+    const ran = l.sessions.filter((s) => s.attached).length;
+    const planned = l.sessions.length;
+    return (`${ran} of ${l.asked} asked ran at once, sharing the caps below` +
+        (planned < l.asked ? `; the app split into ${planned}` : "") +
+        (ran < planned ? `; ${planned - ran} could not attach` : ""));
+}
+function laneSummaryLines(l, secrets) {
+    const out = [`| Lane | Owns | Routes | Turns | Tokens | Ended |`, `|---|---|---:|---:|---:|---|`];
+    for (const s of l.sessions)
+        out.push(`| ${cell(s.session, secrets)} | ${cell(s.modules.join(", "), secrets)} | ${s.routes} | ${s.turns} | ${n(s.usage.input + s.usage.output)} | ${s.stop}${s.stopDetail ? `: ${cell(s.stopDetail, secrets)}` : ""} |`);
+    out.push(``);
+    return out;
+}
 function captureSummaryLines(c, secrets) {
     const out = [`**Asked to show:** ${cell(c.what, secrets)}`, ``];
     if (c.status !== "captured")
@@ -668,6 +836,23 @@ export function ciSummaryJson(r, version, secrets = []) {
             seconds: Math.round((r.endedAt - r.spend.startedAt) / 1000),
             estimatedCostUsd: estimateCost(r.model, r.spend.usage, r.price),
         },
+        ...(r.dedup
+            ? {
+                dedup: {
+                    by: r.dedup.by,
+                    ...(r.dedup.by === "judge"
+                        ? {
+                            effort: r.dedup.effort,
+                            calls: r.dedup.calls,
+                            failed: r.dedup.failed,
+                            inputTokens: r.dedup.usage.input,
+                            outputTokens: r.dedup.usage.output,
+                            seconds: Math.round(r.dedup.ms / 100) / 10,
+                        }
+                        : {}),
+                },
+            }
+            : {}),
         counts: {
             high: r.findings.filter((f) => !isWorthALook(f) && f.severity === "high").length,
             medium: r.findings.filter((f) => !isWorthALook(f) && f.severity === "medium").length,
@@ -684,6 +869,28 @@ export function ciSummaryJson(r, version, secrets = []) {
             ...(isWorthALook(f) ? { tier: "worth-a-look", convention: clean(f.convention ?? "") } : {}),
         })),
         ...(r.capture ? { capture: cleanCapture(r.capture, clean) } : {}),
+        ...(r.lanes ? { lanes: lanesJson(r.lanes, clean) } : {}),
+    };
+}
+/** The lanes as ci.json holds them. Module paths and lane names come from the app's routes: redacted like the rest. */
+function lanesJson(l, clean) {
+    return {
+        asked: l.asked,
+        planned: l.sessions.length,
+        ran: l.sessions.filter((s) => s.attached).length,
+        ...(l.oneLoop ? { oneLoop: clean(l.oneLoop) } : {}),
+        sessions: l.sessions.map((s) => ({
+            session: clean(s.session),
+            modules: s.modules.map(clean),
+            routes: s.routes,
+            attached: s.attached,
+            stop: s.stop,
+            ...(s.stopDetail ? { detail: clean(s.stopDetail) } : {}),
+            turns: s.turns,
+            inputTokens: s.usage.input,
+            cachedInputTokens: s.usage.cachedInput,
+            outputTokens: s.usage.output,
+        })),
     };
 }
 /** The capture as ci.json holds it: the words a person or a model wrote, and the URLs, passed through the same redaction as the rest. */
@@ -705,8 +912,13 @@ function appOrigin(url) {
         return url;
     }
 }
-/** This run's findings as SARIF 2.1.0: one rule per category, the finding's id as its fingerprint. */
-export function ciSarif(r, version, secrets = []) {
+/**
+ * This run's findings as SARIF 2.1.0: one rule per category, the finding's id
+ * as its fingerprint. Code scanning keeps only results located in a repository
+ * file, so each points at the anchor (sarif.ts) and carries its page as a
+ * logical location, in `properties.route` and in its message.
+ */
+export function ciSarif(r, version, secrets = [], anchor = SARIF_ANCHOR_FALLBACKS[0]) {
     const clean = (s) => redactKeys(redactSecrets(s), secrets);
     const categories = [...new Set(r.findings.map((f) => f.category))].sort();
     return {
@@ -723,19 +935,22 @@ export function ciSarif(r, version, secrets = []) {
                     },
                 },
                 invocations: [{ executionSuccessful: r.stop !== "provider-error" && r.stop !== "could-not-start", properties: { stop: r.stop } }],
-                originalUriBaseIds: { APP: { uri: `${appOrigin(r.url)}/` } },
-                results: r.findings.map((f) => ({
-                    ruleId: `finding/${f.category}`,
-                    level: isWorthALook(f) ? "note" : SARIF_LEVEL[f.severity],
-                    message: {
-                        text: isWorthALook(f)
-                            ? `Worth a look — ${clean(f.title)}. A defect only if your project uses ${clean(f.convention ?? "a convention")}.`
-                            : `[${f.severity}] ${clean(f.title)}${f.evidence ? ` — ${clean(f.evidence)}` : ""}`,
-                    },
-                    locations: [{ physicalLocation: { artifactLocation: { uri: clean(pathOf(f.url)).replace(/^\//, ""), uriBaseId: "APP" } } }],
-                    partialFingerprints: { "scenescoutFinding/v1": createHash("sha256").update(f.id).digest("hex").slice(0, 32) },
-                    ...(isWorthALook(f) ? { properties: { tier: "worth-a-look", convention: clean(f.convention ?? "") } } : {}),
-                })),
+                properties: { app: clean(appOrigin(r.url)) },
+                results: r.findings.map((f) => {
+                    const route = clean(pathOf(f.url));
+                    return {
+                        ruleId: `finding/${f.category}`,
+                        level: isWorthALook(f) ? "note" : SARIF_LEVEL[f.severity],
+                        message: {
+                            text: isWorthALook(f)
+                                ? `Worth a look — ${clean(f.title)} — on ${route}. A defect only if your project uses ${clean(f.convention ?? "a convention")}.`
+                                : `[${f.severity}] ${clean(f.title)}${f.evidence ? ` — ${clean(f.evidence)}` : ""} — on ${route}`,
+                        },
+                        locations: [sarifLocation(anchor, route)],
+                        partialFingerprints: { "scenescoutFinding/v1": createHash("sha256").update(f.id).digest("hex").slice(0, 32) },
+                        properties: { route, ...(isWorthALook(f) ? { tier: "worth-a-look", convention: clean(f.convention ?? "") } : {}) },
+                    };
+                }),
             },
         ],
     };