scenescout 3.15.0 → 3.17.0

package/dist/engine/fingerprint.js

@@ -4,16 +4,41 @@ const HEX_RE = /^[0-9a-f]{12,}$/i;
 const NUM_RE = /^\d+$/;
 /** Query params that name a UI state (a different screen), not transient data. */
 const UI_STATE_PARAM_RE = /^(tab|view|mode|step|panel|section)$/i;
+/** Letters, digits and single `-`/`_` separators: the alphabet a code-shaped record id is written in. */
+const CODE_ALPHABET_RE = /^[A-Za-z0-9]+(?:[-_][A-Za-z0-9]+)*$/;
+/** An upper-case prefix, then digits: `WID-2025-001`, `INV2024`, `PO_77`. */
+const CODE_PREFIX_RE = /^[A-Z]{1,6}[-_]?\d[A-Za-z0-9_-]*$/;
+/**
+ * Whether a segment reads as a code-shaped record id (`WID-2025-001`,
+ * `A1B2C3`) rather than a word or a slug. Every record such an id addresses
+ * would otherwise be its own route. Words are kept: a slug whose digits are a
+ * small part of it (`how-to-2024-guide`, `iphone-15-pro`), a short one with a
+ * digit or two (`v2`, `2fa`, `q3`), and anything outside the id alphabet.
+ * An upper-case prefix followed by digits is an id with two digits or more;
+ * otherwise it takes three digits making up at least half the characters.
+ */
+function isCodeId(seg) {
+    if (!CODE_ALPHABET_RE.test(seg))
+        return false;
+    const digits = (seg.match(/\d/g) ?? []).length;
+    if (CODE_PREFIX_RE.test(seg) && digits >= 2)
+        return true;
+    const chars = seg.replace(/[-_]/g, "").length;
+    return digits >= 3 && digits * 2 >= chars;
+}
 /**
  * Whether a path segment is an id that route identity collapses to `:id`: a
- * UUID or long hex string anywhere, a number from the second real segment on.
- * `index` counts as `path.split("/")` does, so the first real segment of a
- * leading-slash path is 1 (see the note on numeric first segments below).
+ * UUID or long hex string anywhere, and from the second real segment on, a
+ * number or a code-shaped id (isCodeId). `index` counts as `path.split("/")`
+ * does, so the first real segment of a leading-slash path is 1 (see the note
+ * on numeric first segments below).
  */
 export function isIdSegment(seg, index) {
     if (UUID_RE.test(seg) || HEX_RE.test(seg))
         return true;
-    return NUM_RE.test(seg) && index > 1;
+    if (index <= 1)
+        return false;
+    return NUM_RE.test(seg) || isCodeId(seg);
 }
 /**
  * Normalize a URL into a route-class identity:
@@ -62,6 +87,39 @@ export function normalizePath(rawUrl) {
         normalized += `?${kept.sort().join("&")}`;
     return normalized;
 }
+/**
+ * Whether refs a snapshot took at `from` may still be used at `to`: the same
+ * origin and the exact same path (hash-route path included), differing at
+ * most in query parameters that are not UI state, or in an in-page fragment.
+ * A search box's "Clear" or a filter that rewrites only `?q=` leaves the same
+ * screen with the same controls; a tab parameter, another path or an id in the
+ * path does not. A record chosen by a query parameter (`?id=6`) does keep them,
+ * so the action checks the element it finds (test id and name) before acting:
+ * a list that now shows other rows under the same paths cannot hand it another one.
+ */
+export function refsSurviveUrlChange(from, to) {
+    if (from === to)
+        return true;
+    let a;
+    let b;
+    try {
+        a = new URL(from);
+        b = new URL(to);
+    }
+    catch {
+        return false;
+    }
+    if (a.origin !== b.origin || a.pathname !== b.pathname)
+        return false;
+    const hashPath = (u) => (u.hash.startsWith("#/") ? u.hash.split("?")[0] : "");
+    if (hashPath(a) !== hashPath(b))
+        return false;
+    return normalizePath(from) === normalizePath(to);
+}
+/** A route without its UI-state query: the screen whose tabs are its variants ("/things/:id?tab=history" → "/things/:id"). */
+export function routeBase(route) {
+    return route.split("?")[0];
+}
 /**
  * Paths that are not UI pages, however they entered the route list: API
  * endpoints and file downloads.
@@ -89,6 +147,36 @@ export function elementKey(el) {
     const name = el.name.toLowerCase().replace(/\s+/g, " ").trim().slice(0, 60);
     return `${el.role}:${name}`;
 }
+/**
+ * Element keys made unique within one snapshot: the first holder of a base key
+ * keeps it, later ones get `~1`, `~2` in document order.
+ */
+export function ordinalKeys(baseKeys) {
+    const counts = new Map();
+    return baseKeys.map((base) => {
+        const count = counts.get(base) ?? 0;
+        counts.set(base, count + 1);
+        return count === 0 ? base : `${base}~${count}`;
+    });
+}
+/**
+ * Each key the earlier name rule gave a control that the current rule names
+ * differently, as current key → earlier key, from both rules' base keys in
+ * document order. Ordinals are worked out under each rule separately, so when
+ * one of two unnamed image buttons gains a name, the other's move from `~1`
+ * to the bare key is listed too. Only keys in `tracked` are listed: an
+ * element coverage does not count needs no alias.
+ */
+export function keyAliases(bases) {
+    const now = ordinalKeys(bases.map((b) => b.base));
+    const before = ordinalKeys(bases.map((b) => b.prior));
+    const out = {};
+    bases.forEach((b, i) => {
+        if (b.tracked && now[i] !== before[i])
+            out[now[i]] = before[i];
+    });
+    return out;
+}
 /**
  * Fingerprint a UI state: normalized route + hash of the set of interactable
  * element classes. Same page with different data → same fingerprint; a page

package/dist/engine/flow.js

@@ -190,13 +190,14 @@ const flowSchema = z
         ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["steps", 0, "action"], message: 'must be "navigate": a flow starts from a page it names' });
     }
 });
-/** `steps[2].target`, the way a person would look for it in the file. */
-function fieldPath(p) {
+/** `steps[2].target`, the way a person would look for it in the file. Shared with the baselines' targets file (baseline.ts). */
+export function fieldPath(p) {
     if (p.length === 0)
         return "(the whole file)";
     return p.map((part, i) => (typeof part === "number" ? `[${part}]` : i === 0 ? part : `.${part}`)).join("");
 }
-function issueMessage(issue) {
+/** One schema problem as a person reads it. Shared with the baselines' targets file (baseline.ts). */
+export function issueMessage(issue) {
     if (issue.code === "unrecognized_keys")
         return `unknown field(s) ${issue.keys.map((k) => `"${k}"`).join(", ")}`;
     if (issue.code === "invalid_union_discriminator")
@@ -205,8 +206,12 @@ function issueMessage(issue) {
         return "is required";
     return issue.message;
 }
-/** Validate one flow file's text. Every mistake names the file and the field. */
-export function parseFlow(text, file) {
+/**
+ * Parse a JSON file a person wrote against its schema. Every mistake names the
+ * file and the field, up to five of them. Shared by flows and the baselines'
+ * targets file (baseline.ts), so both read their errors the same way.
+ */
+export function parseJsonFile(text, file, schema) {
     let json;
     try {
         json = JSON.parse(text);
@@ -214,12 +219,19 @@ export function parseFlow(text, file) {
     catch (err) {
         return { ok: false, error: `${file}: not valid JSON (${err instanceof Error ? err.message : String(err)})` };
     }
-    const parsed = flowSchema.safeParse(json);
+    const parsed = schema.safeParse(json);
     if (!parsed.success) {
         const issues = parsed.error.issues.slice(0, 5).map((i) => `${fieldPath(i.path)} ${issueMessage(i)}`);
         const more = parsed.error.issues.length > 5 ? ` (and ${parsed.error.issues.length - 5} more)` : "";
         return { ok: false, error: `${file}: ${issues.join("; ")}${more}` };
     }
+    return { ok: true, data: parsed.data };
+}
+/** Validate one flow file's text. Every mistake names the file and the field. */
+export function parseFlow(text, file) {
+    const parsed = parseJsonFile(text, file, flowSchema);
+    if (!parsed.ok)
+        return parsed;
     return { ok: true, flow: { name: parsed.data.name ?? file.replace(/\.json$/i, ""), file, steps: parsed.data.steps } };
 }
 /**

package/dist/engine/forms.js

@@ -124,6 +124,13 @@ export const TEXT_ENTRY_TYPES = new Set([
     "week",
     "time",
 ]);
+/**
+ * Text-entry types an app commonly fills in itself before anyone types (a
+ * date or time set to now). Left at that value, such a field counts as
+ * blank for the empty submit (FieldFacts.filled). Free text is not here: a
+ * pre-filled text field is an edit form holding its record.
+ */
+export const APP_FILLED_TYPES = new Set(["date", "datetime-local", "month", "week", "time"]);
 /**
  * Input types in which Enter submits the form (the HTML standard's implicit
  * submission). Not checkboxes, radios or buttons: Enter does nothing there.
@@ -202,14 +209,34 @@ export function isNavigationTeardown(message) {
 const FORM_HELPERS_SRC = `
   const visible = ${VISIBLE_SRC};
   const xpathOf = ${XPATH_OF_SRC};
-  const facts = (f) => ({
-    tag: f.tagName.toLowerCase(),
-    type: f.tagName.toLowerCase() === "input" ? String(f.type || "text").toLowerCase() : "",
-    disabled: f.matches(":disabled"),
-    readOnly: f.readOnly === true,
-    visible: visible(f),
-    filled: typeof f.value === "string" && f.value !== "",
-  });
+  // Each field's value when the inventory first read it: what the app put
+  // there before the session typed anything. Kept in the page, by element,
+  // under a registry symbol the app has no reason to touch.
+  const initialKey = Symbol.for("scenescout.form-initial-values");
+  const initials = window[initialKey] || (window[initialKey] = new WeakMap());
+  // remember: the inventory records a field's first value; the probe at
+  // submit time only compares, so a field first met at the submit counts as
+  // filled whenever it holds anything. Only date and time fields: an app
+  // pre-fills those with "now" on a create form, while a pre-filled text
+  // field is an edit form's record, and saving that unchanged is not the
+  // empty submit.
+  // Held equal to APP_FILLED_TYPES by memory-test; a literal, not a
+  // JSON.stringify, so this script is built from constants alone.
+  const pickerTypes = ["date", "datetime-local", "month", "week", "time"];
+  const facts = (f, remember) => {
+    const value = typeof f.value === "string" ? f.value : "";
+    const type = f.tagName.toLowerCase() === "input" ? String(f.type || "text").toLowerCase() : "";
+    const picker = pickerTypes.includes(type);
+    if (picker && remember && !initials.has(f)) initials.set(f, value);
+    return {
+      tag: f.tagName.toLowerCase(),
+      type,
+      disabled: f.matches(":disabled"),
+      readOnly: f.readOnly === true,
+      visible: visible(f),
+      filled: value !== "" && !(picker && value === initials.get(f)),
+    };
+  };
   // The type PROPERTY: a button with no type, or an unknown one, reports "submit".
   const isSubmit = (el) => {
     const tag = el.tagName.toLowerCase();
@@ -219,11 +246,11 @@ const FORM_HELPERS_SRC = `
   // Each DISTINCT set of field facts once. The rules ask whether any field is
   // text entry and whether every one is blank, which repeats do not change,
   // and a form of 2000 identical rows would otherwise ship 2000 objects back.
-  const fieldFactsOf = (form) => {
+  const fieldFactsOf = (form, remember) => {
     const seen = new Map();
     for (const c of Array.from(form.elements)) {
       if (!/^(input|textarea|select)$/i.test(c.tagName) || c.type === "hidden") continue;
-      const f = facts(c);
+      const f = facts(c, remember);
       const id = f.tag + "|" + f.type + "|" + f.disabled + "|" + f.readOnly + "|" + f.visible + "|" + f.filled;
       if (!seen.has(id)) seen.set(id, f);
     }
@@ -258,7 +285,7 @@ export const FORMS_INVENTORY_SCRIPT = `(() => {
     out.push({
       attrs: attrsOf(form),
       submit: xpathOf(submits[0]),
-      fields: fieldFactsOf(form),
+      fields: fieldFactsOf(form, true),
       submitDisabled: submits.every((s) => s.matches(":disabled")),
     });
   }
@@ -282,16 +309,14 @@ export const FORM_PROBE_BODY = `
     submit: xpathOf(submits[0]),
     submitTestid: submits[0].getAttribute("data-testid"),
     submitName: accessibleName(submits[0]),
-    fields: fieldFactsOf(form),
-    self: facts(node),
+    fields: fieldFactsOf(form, false),
+    self: facts(node, false),
     selfIsSubmit: isSubmit(node),
     defaultDisabled: submits[0].matches(":disabled"),
   };
 `;
-/** The probe as an expression over a node expression, for a page-level evaluate. */
-export function formProbeExpression(nodeExpression) {
-    return `((node) => {${FORM_PROBE_BODY}})(${nodeExpression})`;
-}
+/** The probe over the focused element, as an expression for a page-level evaluate. */
+export const FORM_PROBE_OF_ACTIVE_ELEMENT = `((node) => {${FORM_PROBE_BODY}})(document.activeElement)`;
 /**
  * The scout_coverage lines for forms no session has submitted empty this
  * run. Empty when there is nothing to say.
@@ -301,7 +326,145 @@ export function formatNeverSubmittedEmpty(forms) {
         return [];
     return [
         "Forms never submitted empty this run (submit each once with every text field blank: a submit that silently does nothing — no request, no message — hides there):",
-        ...forms.slice(0, 15).map((f) => `  ${f.route} ${f.key}`),
+        ...forms.slice(0, 15).map((f) => `  ${f.route} ${f.key}${f.seenBy && f.seenBy.length > 0 ? ` (seen by ${f.seenBy.join(", ")})` : ""}`),
         ...(forms.length > 15 ? [`  … +${forms.length - 15} more`] : []),
     ];
 }
+/**
+ * Which option of a dropdown a requested value means, decided before any pick
+ * so a value that names none fails at once instead of waiting out the action
+ * limit. Tried in order, first tier with a match wins:
+ *   1. an option whose value is exactly the request;
+ *   2. an option whose label is exactly the request;
+ *   3. a value or label equal to it ignoring case and surrounding space;
+ *   4. a label that starts with it, ignoring case ("Low" for "Low — minor impact").
+ * In tiers 1 and 2 the first match is taken, as the browser takes it. Tiers 3
+ * and 4 are guesses, so they must find exactly one option; two or more is
+ * refused, naming them. A disabled option is refused: no user can choose it.
+ */
+export function matchOption(options, requested) {
+    const indexed = options.map((option, index) => ({ option, index }));
+    const fold = (s) => s.trim().toLowerCase();
+    const want = fold(requested);
+    const tiers = [
+        { hits: indexed.filter(({ option }) => option.value === requested), guess: false },
+        { hits: indexed.filter(({ option }) => option.label === requested), guess: false },
+        { hits: indexed.filter(({ option }) => fold(option.value) === want || fold(option.label) === want), guess: true },
+        { hits: want === "" ? [] : indexed.filter(({ option }) => fold(option.label).startsWith(want)), guess: true },
+    ];
+    for (const { hits, guess } of tiers) {
+        if (hits.length === 0)
+            continue;
+        if (guess && hits.length > 1) {
+            return { refused: `${JSON.stringify(requested)} matches more than one option: ${listOptions(hits.map((h) => h.option))}. Pass one of the values.` };
+        }
+        const hit = hits[0];
+        if (hit.option.disabled)
+            return { refused: `option ${describeOption(hit.option)} is disabled, so it cannot be chosen.` };
+        return hit;
+    }
+    return { refused: `no option matches ${JSON.stringify(requested)}; options: ${listOptions(options)}.` };
+}
+function describeOption(o) {
+    const cap = (t) => (t.length > 60 ? `${t.slice(0, 59)}…` : t);
+    const shown = o.value === "" ? '""' : cap(o.value);
+    return o.label && o.label !== o.value ? `${shown} (${JSON.stringify(cap(o.label))})` : shown;
+}
+/** The options as a refusal lists them: value, then label where it differs; at most 15. */
+function listOptions(options) {
+    if (options.length === 0)
+        return "none";
+    const shown = options.slice(0, 15).map((o) => describeOption(o) + (o.disabled ? " [disabled]" : ""));
+    return shown.join(", ") + (options.length > 15 ? `, … +${options.length - 15} more` : "");
+}
+/** The format each date and time input type takes, with an example, for a refusal. */
+const DATE_FORMATS = {
+    date: "YYYY-MM-DD (e.g. 2026-09-20)",
+    "datetime-local": "YYYY-MM-DDTHH:MM (e.g. 2026-09-20T10:00)",
+    time: "HH:MM or HH:MM:SS, 24-hour (e.g. 14:30)",
+    month: "YYYY-MM (e.g. 2026-09)",
+    week: "YYYY-Www (e.g. 2026-W38)",
+};
+function realDate(y, m, d) {
+    const t = new Date(Date.UTC(y, m - 1, d));
+    return t.getUTCFullYear() === y && t.getUTCMonth() === m - 1 && t.getUTCDate() === d;
+}
+function realTime(h, min, sec) {
+    return h < 24 && min < 60 && (sec === null || sec < 60);
+}
+const pad = (n, width = 2) => String(n).padStart(width, "0");
+/** ISO 8601 week of a calendar date, as `YYYY-Www`. */
+function isoWeek(y, m, d) {
+    const t = new Date(Date.UTC(y, m - 1, d));
+    const day = t.getUTCDay() || 7;
+    t.setUTCDate(t.getUTCDate() + 4 - day);
+    const yearStart = Date.UTC(t.getUTCFullYear(), 0, 1);
+    const week = Math.ceil(((t.getTime() - yearStart) / 86_400_000 + 1) / 7);
+    return `${t.getUTCFullYear()}-W${pad(week)}`;
+}
+/**
+ * A value for a date or time input (`date`, `datetime-local`, `time`, `month`,
+ * `week`), in the one format the browser accepts there. Anything else fails
+ * the fill with a bare "Malformed value", so an obvious near miss is put in
+ * that format — a date into a date-and-time field gets T00:00, a space between
+ * date and time becomes "T", a date into a month field keeps its month — and
+ * anything else is refused, naming the format. Any other type, and an empty
+ * value (which clears the field), pass through unchanged.
+ */
+export function normaliseDateValue(type, text) {
+    const format = DATE_FORMATS[type];
+    if (!format || text === "")
+        return { value: text };
+    const v = text.trim();
+    const refused = { refused: `a ${type} field takes ${format}; ${JSON.stringify(text)} is not in that form.` };
+    const changed = (value) => (value === text ? { value } : { value, note: `entered as ${value}, the form a ${type} field takes` });
+    const dateRe = /^(\d{4})-(\d{1,2})-(\d{1,2})/;
+    const timeRe = /^(\d{1,2}):(\d{2})(?::(\d{2})(\.\d{1,3})?)?$/;
+    const timeOf = (s) => {
+        const t = timeRe.exec(s);
+        if (!t)
+            return null;
+        const [h, min, sec] = [Number(t[1]), Number(t[2]), t[3] === undefined ? null : Number(t[3])];
+        if (!realTime(h, min, sec))
+            return null;
+        return `${pad(h)}:${pad(min)}${sec === null ? "" : `:${pad(sec)}${t[4] ?? ""}`}`;
+    };
+    if (type === "time") {
+        const t = timeOf(v);
+        return t ? changed(t) : refused;
+    }
+    if (type === "week") {
+        const w = /^(\d{4})-[Ww](\d{1,2})$/.exec(v);
+        if (w) {
+            const week = Number(w[2]);
+            return week >= 1 && week <= 53 ? changed(`${w[1]}-W${pad(week)}`) : refused;
+        }
+    }
+    if (type === "month") {
+        const m = /^(\d{4})-(\d{1,2})$/.exec(v);
+        if (m)
+            return Number(m[2]) >= 1 && Number(m[2]) <= 12 ? changed(`${m[1]}-${pad(Number(m[2]))}`) : refused;
+    }
+    const d = dateRe.exec(v);
+    if (!d)
+        return refused;
+    const [y, mo, day] = [Number(d[1]), Number(d[2]), Number(d[3])];
+    if (!realDate(y, mo, day))
+        return refused;
+    const date = `${d[1]}-${pad(mo)}-${pad(day)}`;
+    const rest = v.slice(d[0].length);
+    // What may follow the date: nothing, or a time after "T" or a space.
+    const time = rest === "" ? "" : /^[T ]/.test(rest) ? timeOf(rest.slice(1)) : null;
+    if (time === null)
+        return refused;
+    switch (type) {
+        case "date":
+            return changed(date);
+        case "month":
+            return changed(date.slice(0, 7));
+        case "week":
+            return changed(isoWeek(y, mo, day));
+        default:
+            return changed(`${date}T${time || "00:00"}`);
+    }
+}

package/dist/engine/journey.js

@@ -7,6 +7,7 @@
  * are table-tested here instead of being reachable only through a browser.
  */
 import { normalizePath } from "./fingerprint.js";
+import { IDLE_GAP_MS, sayDuration } from "./pace.js";
 /** More distinct screens than this for one task is worth questioning. */
 const MANY_SCREENS = 4;
 /** More interactions than this for one task is worth questioning. */
@@ -53,12 +54,39 @@ export function measureJourney(log, completed) {
         verdict.push(`✓ efficient — direct path, no backtracking, proportionate interaction count`);
     return { interactions, navigations, routeSeq, distinctScreens, backtracks, shortcuts, policyBlocks, refusals, verdict };
 }
+/**
+ * The time a journey took, measured as pace.ts measures a run: the gaps
+ * between consecutive moments (the start, each action of this session, the
+ * end) summed, leaving out any gap over IDLE_GAP_MS. A journey left open
+ * across a long pause between agent turns reported its whole wall-clock
+ * span — 23660 s for ten interactions — as the user's time on the task.
+ */
+export function journeyTime(startMs, actionMs, endMs, idleMs = IDLE_GAP_MS) {
+    const moments = [startMs, ...actionMs.filter((t) => Number.isFinite(t) && t >= startMs && t <= endMs).sort((a, b) => a - b), endMs];
+    let activeMs = 0;
+    let idleGaps = 0;
+    for (let i = 1; i < moments.length; i++) {
+        const gap = moments[i] - moments[i - 1];
+        if (gap > idleMs)
+            idleGaps += 1;
+        else
+            activeMs += gap;
+    }
+    return { activeMs, wallMs: Math.max(0, endMs - startMs), idleGaps };
+}
+/** The time figure a journey's result quotes: active seconds, and what was left out when anything was. */
+export function sayJourneyTime(t) {
+    const active = `${Math.round(t.activeMs / 1000)}s`;
+    if (t.idleGaps === 0)
+        return active;
+    return `${active} active (${t.idleGaps} idle gap${t.idleGaps === 1 ? "" : "s"} over ${sayDuration(IDLE_GAP_MS)} excluded; ${sayDuration(t.wallMs)} on the clock)`;
+}
 /** The tool result for a finished journey. */
 export function formatJourney(j, m) {
     return [
         `JOURNEY ${j.completed ? "COMPLETED" : "ABANDONED"} — "${j.goal}"`,
         ``,
-        `Interaction cost: ${m.interactions} interactions · ${m.navigations} navigations · ${m.distinctScreens} distinct screens · ${j.seconds}s`,
+        `Interaction cost: ${m.interactions} interactions · ${m.navigations} navigations · ${m.distinctScreens} distinct screens · ${sayJourneyTime(j.time)}`,
         `Path: ${m.routeSeq.slice(0, 12).join(" → ")}${m.routeSeq.length > 12 ? " → …" : ""}`,
         ...(m.policyBlocks > 0 || m.refusals > 0 ? [`Policy: ${m.policyBlocks} write-policy blocks, ${m.refusals} refusals (tester safety, not app defects)`] : []),
         ...(j.note ? [`Note: ${j.note}`] : []),

package/dist/engine/lane.js

@@ -39,6 +39,8 @@ export const LANE_CONVENTION_MAX = 160;
 export const LANE_NAME_MAX = 40;
 /** A route as the lane saw it, query string included. */
 export const LANE_ROUTE_MAX = 200;
+/** The id scout_finding returned: ten characters today, with room to spare so a longer id never refuses a report. */
+export const LANE_FINDING_MAX = 64;
 export const LANE_SEVERITIES = ["high", "medium", "low"];
 /** The same set scout_finding accepts, so a lane can report every finding it filed. */
 export const LANE_CATEGORIES = FINDING_CATEGORIES;
@@ -78,6 +80,13 @@ export const LaneDecision = z
      */
     // Any string here: its length is checked only on a worth_a_look (below), because on every other verdict it is ignored.
     convention: z.string().nullable().optional(),
+    /**
+     * The id scout_finding returned when the lane filed this observation. It
+     * ties the decision to its finding exactly, where matching the evidence
+     * text misses a lane that reworded it between filing and reporting.
+     * Optional, so a reply written before the field existed still parses.
+     */
+    finding: z.string().min(1).max(LANE_FINDING_MAX).nullable().optional(),
 })
     .strict()
     .superRefine((d, ctx) => {
@@ -297,9 +306,10 @@ export function laneReportInstruction(lane) {
 const LANE_RUBRIC = [
     "Reply with ONE JSON object and nothing else — no prose before or after it, no explanation, no headings. A fenced ```json block is fine; anything outside it is discarded unread, so put nothing there you want kept.",
     `Shape: {"lane":<your lane name>,"status":<${quoteAll(LANE_STATUSES)}>,"decisions":[…],"routes":[…],"blocked_by":<string or null>}.`,
-    `Each decision: {"observation":<a short id for what was observed, unique in the report, at most ${LANE_OBSERVATION_MAX} characters>,"verdict":<${quoteAll(LANE_VERDICTS)}>,"severity":<${quoteAll(LANE_SEVERITIES)} or null>,"category":<${quoteAll(LANE_CATEGORIES)} or null>,"confidence":<0..1>,"evidence":<machine signature such as "GET /api/things 500", or null>,"convention":<string or null>}.`,
+    `Each decision: {"observation":<a short id for what was observed, unique in the report, at most ${LANE_OBSERVATION_MAX} characters>,"verdict":<${quoteAll(LANE_VERDICTS)}>,"severity":<${quoteAll(LANE_SEVERITIES)} or null>,"category":<${quoteAll(LANE_CATEGORIES)} or null>,"confidence":<0..1>,"evidence":<machine signature such as "GET /api/things 500", or null>,"convention":<string or null>,"finding":<the id scout_finding returned for it, or null>}.`,
     `A "defect" must carry a severity and a category. "evidence" is a signature, not a sentence: at most ${LANE_EVIDENCE_MAX} characters. "confidence" is how sure you are of the verdict, calibrated: 0.5 means a coin flip, 0.95 means you would bet on it.`,
     `"worth_a_look" is for an observation that is real but is a defect only under a convention of the project you cannot see (a spacing scale, how navigation links are styled, whether controls carry test ids, whether the app targets touch screens): it must name that convention in "convention", one line of at most ${LANE_CONVENTION_MAX} characters, such as "a 4px spacing scale". On every other verdict leave "convention" null or out: it is ignored there. It is not for "I could not tell": that is "unsure".`,
+    `"finding" is the id scout_finding gave the observation when you filed it, at most ${LANE_FINDING_MAX} characters: it ties the decision to its finding exactly, so name it on every defect you filed. If scout_finding said your filing was merged into a finding that is a different bug, file it again as it says and name the id it gives then.`,
     `"routes" lists the routes you covered, each at most ${LANE_ROUTE_MAX} characters. "blocked_by" is one line of at most ${LANE_BLOCKED_BY_MAX} characters saying what stopped you: required when the status is "blocked", allowed with "partial", null with "complete"; the detail belongs in a finding. The lane name is at most ${LANE_NAME_MAX} characters. At most ${LANE_MAX_ITEMS} decisions and ${LANE_MAX_ITEMS} routes. Unknown keys are refused.`,
     "The object IS your final report: whatever hands it back must hand back the object verbatim, not a summary of it.",
 ];
@@ -376,8 +386,8 @@ export function isTemplateSegment(seg) {
 /**
  * Whether two paths name the same route. A template segment on either side
  * stands for ONE segment that is an id by route identity's own rule
- * (`isIdSegment`: a number after the first segment, a UUID, a long hex
- * string), or for another template. Never for a word: `/users/{id}` is not
+ * (`isIdSegment`: a number or a code-shaped id after the first segment, a
+ * UUID, a long hex string), or for another template. Never for a word: `/users/{id}` is not
  * `/users/me`, `/things/:id` is not `/things/export`, and a path of three stars does
  * not stand for every three-segment path. Same number of segments, every literal
  * equal (case-insensitive), so a template never absorbs a slash or an empty

package/dist/engine/launch.js

@@ -4,9 +4,11 @@
  * For anyone who installed from npm and never ran the setup step, the first
  * attach fails because the browser was never downloaded — and Playwright reports
  * that as a multi-line box of text with a path in it. That is the single most
- * likely first-run failure, so it gets one plain instruction instead.
+ * likely first-run failure, so it gets one plain instruction instead. Before
+ * that, readyBrowser downloads the missing build itself where the setting and
+ * the environment allow, so a first attach needs no terminal step.
  */
-import { APPROX_DISK_MB, launchTarget } from "../browsers.js";
+import { APPROX_DISK_MB, attachDownloadLine, BROWSER_DOWNLOAD_ENV, browserDownloadDecision, launchTarget, } from "../browsers.js";
 /** Playwright's wording when the browser binary is not on disk. */
 const MISSING_BROWSER_RE = /Executable doesn't exist|playwright install|browserType\.launch:.*(not found|ENOENT)/i;
 export function isMissingBrowser(message) {
@@ -20,13 +22,50 @@ export function explainLaunchFailure(message, reaped, need = { engine: "chromium
         const why = target === "chromium" && need.headed
             ? "A headed run needs the full Chromium browser, which has not been downloaded (the headless shell alone cannot open a window)"
             : `The ${target} build has not been downloaded yet`;
-        return (`${why} (one-time, about ${APPROX_DISK_MB[target]} MB on disk). Run this once, then attach again:\n` +
-            `  npx -y scenescout install --browser-only --browsers ${target}\n` +
-            `(from a clone: node dist/cli.js install --browser-only --browsers ${target}). ` +
-            `On Linux, if system libraries are missing: npx playwright install --with-deps ${target}`);
+        return `${why} (one-time, about ${APPROX_DISK_MB[target]} MB on disk). ${installByHand(target)}`;
     }
     const firstLine = message.split("\n")[0];
     return (`browser launch failed twice (${firstLine})` +
         (reaped > 0 ? ` — ${reaped} orphaned browser process(es) were reaped between attempts` : "") +
         `. Check disk space, then run \`scenescout doctor\` to verify the setup.`);
 }
+/** The commands that download one build by hand, ending the message that names them. */
+function installByHand(target) {
+    return (`Run this once, then attach again:\n` +
+        `  npx -y scenescout install --browser-only --browsers ${target}\n` +
+        `(from a clone: node dist/cli.js install --browser-only --browsers ${target}). ` +
+        `On Linux, if system libraries are missing: npx playwright install --with-deps ${target}`);
+}
+/**
+ * Make sure the build an attach is about to launch is on disk, downloading it
+ * the first time when browserDownloadDecision allows. Returns a line for the
+ * attach's answer when it downloaded, null when the build was already there,
+ * and throws with the command to run by hand when it will not or could not.
+ */
+export async function readyBrowser(need, deps) {
+    const target = launchTarget(need.engine, need.headed);
+    if ((await deps.present())[target].installed)
+        return null;
+    const decision = browserDownloadDecision(deps.env);
+    if (decision === "refuse") {
+        throw new Error(`The ${target} build has not been downloaded, and ${BROWSER_DOWNLOAD_ENV}=off keeps SceneScout from downloading it. ${installByHand(target)}`);
+    }
+    if (decision === "tell") {
+        throw new Error(`The ${target} build has not been downloaded. In CI SceneScout downloads a browser only when asked: add the install step below to the job before the tests, ` +
+            `or set ${BROWSER_DOWNLOAD_ENV}=on to let the attach download it. ${installByHand(target)}`);
+    }
+    const now = deps.now ?? Date.now;
+    deps.say(attachDownloadLine(target));
+    const began = now();
+    const result = await deps.download([target]);
+    if (!result.ok) {
+        throw new Error(`The test browser could not be downloaded${result.detail ? ` (${result.detail})` : ""}. Check the network or proxy, or download it by hand. ${installByHand(target)}`);
+    }
+    // The installer's exit code is not the build: look again before saying it is there.
+    if (!(await deps.present())[target].installed) {
+        throw new Error(`The download finished, but the ${target} build is still not where Playwright looks for it. ${installByHand(target)}`);
+    }
+    const line = `The test browser is ready (${target}, downloaded once in ${Math.round((now() - began) / 1000)} s; later tests start straight away).`;
+    deps.say(line);
+    return line;
+}

package/dist/engine/limits.js

@@ -134,6 +134,13 @@ export function limitHint(kind, ms) {
  * line; the call log below it is kept. An error that already carries a hint is
  * returned as it is.
  */
+/** An error's first line, without the driver's "page.goto: " prefix: what a report shows of it. */
+export function firstLineOf(err) {
+    return (err instanceof Error ? err.message : String(err))
+        .split("\n")[0]
+        .replace(/^[a-z]+\.[a-zA-Z]+: /, "")
+        .trim();
+}
 export function explainTimeout(err, kind, ms) {
     if (!(err instanceof Error) || !isTimeoutMessage(err.message) || err.message.includes(HINT_MARK))
         return err;