@molecule/api-ai-tools 1.9.18 → 1.10.0

package/dist/trace-artifacts.js

@@ -197,6 +197,11 @@ function messageOf(value) {
   return null
 }
 
+// A fill/type/selectOption records what the test typed; the note compares it with the body the
+// page submitted (m173: the Settings form sent bio:"" although the test had just typed a value).
+// Only those actions keep it, so a click's selector does not ride every row.
+const FILLING_ACTION = /\\.(?:fill|type|pressSequentially|selectOption)$/
+
 // The text a failing assertion waited for, named by its own error: a \`has-text(…)\` CSS
 // pseudo-class, a \`getByText(…)\` locator, or a \`toContainText(…)\` expectation. A strict-mode
 // violation is not this shape — two elements DID match the text — and neither is a wait on a
@@ -279,6 +284,40 @@ function gotText(buf, entries, r) {
   return (websocketText(raw) || raw).slice(0, MAX_WS)
 }
 
+// The boolean-valued fields a response body carries, however deeply its entity is wrapped
+// ({"profile":{…,"following":true}}) — what a read of the same field can contradict.
+// A body that does not parse (the trace read bounds what it keeps) names no field.
+function booleanFieldsOf(text) {
+  let parsed
+  try { parsed = JSON.parse(text) } catch (e) { return null }
+  const out = {}
+  function walk(value, depth) {
+    if (depth > 4 || value === null || typeof value !== 'object') return
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) walk(value[i], depth + 1)
+      return
+    }
+    for (const key of Object.keys(value)) {
+      const item = value[key]
+      if (typeof item === 'boolean') {
+        if (!Object.prototype.hasOwnProperty.call(out, key)) out[key] = item
+      } else walk(item, depth + 1)
+    }
+  }
+  walk(parsed, 0)
+  return Object.keys(out).length > 0 ? out : null
+}
+
+// The resource a write acts on: its last path segment is the action (follow, favorite), so
+// /api/profiles/alice/follow is the resource a GET /api/profiles/alice reads.
+function resourceBaseOf(path) {
+  const clean = String(path).split(/[?#]/)[0]
+  const parts = clean.split('/').filter(function (segment) { return segment !== '' })
+  if (parts.length === 0) return clean
+  parts.pop()
+  return '/' + parts.join('/')
+}
+
 let origin = ''
 function pathOf(url) {
   try {
@@ -446,14 +485,19 @@ for (const one of found.slice(0, MAX_TRACES)) {
       if (!entry || entry.type !== 'before') continue
       if (typeof entry.class !== 'string' || typeof entry.method !== 'string') continue
       if (entry.class === 'Test' || typeof entry.startTime !== 'number') continue
+      const api = entry.class + '.' + entry.method
+      const params = entry.params && typeof entry.params === 'object' ? entry.params : {}
+      const filling = FILLING_ACTION.test(api)
       const action = {
-        api: entry.class + '.' + entry.method,
+        api: api,
         start: entry.startTime,
         end: typeof ended[entry.callId] === 'number' ? ended[entry.callId] : null,
         context: ctx.id,
         pageId: typeof entry.callId === 'string' ? pageByCall[entry.callId] : undefined,
         frameId: undefined,
         stepId: typeof entry.stepId === 'string' ? entry.stepId : undefined,
+        ...(filling && typeof params.selector === 'string' ? { selector: params.selector } : {}),
+        ...(filling && typeof params.value === 'string' ? { value: params.value } : {}),
       }
       if (action.pageId !== undefined) {
         for (const frame of ctx.frames) {
@@ -819,6 +863,66 @@ for (const one of found.slice(0, MAX_TRACES)) {
       if (got) lead.got = got
     }
   }
+  // A write that answered a boolean field and a LATER GET of the same resource that answered the
+  // opposite — the read route never saw the viewer (m181's follow: the write answered
+  // {"following":true}, the next profile GET answered false). Both bodies are the trace's own
+  // facts; the note leads with them and sends the run to the route's middleware, not the page.
+  function readContradictionOf() {
+    const writes = []
+    for (let i = 0; i < requests.length; i++) {
+      const r = requests[i]
+      if (!/^(?:POST|PUT|PATCH|DELETE)$/.test(r.method)) continue
+      if (r.status < 200 || r.status >= 300) continue
+      if (r.type !== 'fetch' && r.type !== 'xhr') continue
+      writes.push({ index: i, request: r })
+    }
+    for (let w = 0; w < writes.length; w++) {
+      const write = writes[w].request
+      const writeGot = gotText(buf, entries, write)
+      const writeFields = writeGot ? booleanFieldsOf(writeGot) : null
+      if (!writeFields) continue
+      const base = resourceBaseOf(write.path)
+      let read = null
+      let readFields = null
+      for (let j = writes[w].index + 1; j < requests.length; j++) {
+        const candidate = requests[j]
+        if (candidate.method !== 'GET') continue
+        if (candidate.status < 200 || candidate.status >= 300) continue
+        if (candidate.type !== 'fetch' && candidate.type !== 'xhr') continue
+        // The same page only: another context's read is not this page's answer.
+        if (candidate.pageId !== undefined && write.pageId !== undefined &&
+          candidate.pageId !== write.pageId) continue
+        if (candidate.context !== undefined && write.context !== undefined &&
+          candidate.context !== write.context) continue
+        // LATER, on the trace's own clock when it recorded one.
+        if (typeof candidate.startedAt === 'number' && typeof write.startedAt === 'number' &&
+          candidate.startedAt <= write.startedAt) continue
+        if (String(candidate.path).split(/[?#]/)[0] !== base) continue
+        const got = gotText(buf, entries, candidate)
+        const fields = got ? booleanFieldsOf(got) : null
+        if (!fields) continue
+        read = candidate
+        readFields = fields
+        break
+      }
+      if (read === null || readFields === null) continue
+      for (const key of Object.keys(writeFields)) {
+        if (!Object.prototype.hasOwnProperty.call(readFields, key)) continue
+        if (readFields[key] === writeFields[key]) continue
+        write.got = writeGot
+        read.got = gotText(buf, entries, read)
+        return {
+          field: key,
+          writeValue: writeFields[key],
+          readValue: readFields[key],
+          write: wire(write),
+          read: wire(read),
+        }
+      }
+    }
+    return null
+  }
+  const readContradiction = readContradictionOf()
   const failing = []
   const api = []
   const pending = []
@@ -924,6 +1028,7 @@ for (const one of found.slice(0, MAX_TRACES)) {
     // plus the answered ones (xr-molecule-flash-m112's note listed only -1s and 200s).
     requests: chosen.slice(0, MAX_REQUESTS),
     ...(missingText === null ? {} : { missingText: missingText }),
+    ...(readContradiction === null ? {} : { readContradiction: readContradiction }),
     console: keptConsole.slice(0, MAX_CONSOLE).map(function (text) { return text.slice(0, 300) }),
     actions: actions.slice(-MAX_ACTIONS),
     ...(unattributed ? { unattributed: true } : {}),
@@ -978,6 +1083,29 @@ function parseMissingText(value) {
         return null;
     return { text: raw.text, method: raw.method, path: raw.path };
 }
+/**
+ * One `readContradiction` out of a `TRACE` line's json, or null when the value is not one.
+ *
+ * Both requests must parse and the two values must be booleans: a partial fact never becomes a
+ * claim about the route.
+ *
+ * @param value - The line's `readContradiction`.
+ * @returns The write, the later read and the field they disagree on, or null.
+ */
+function parseReadContradiction(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value;
+    if (typeof raw.field !== 'string' || raw.field === '')
+        return null;
+    if (typeof raw.writeValue !== 'boolean' || typeof raw.readValue !== 'boolean')
+        return null;
+    const write = parseTraceRequest(raw.write);
+    const read = parseTraceRequest(raw.read);
+    if (write === null || read === null)
+        return null;
+    return { field: raw.field, writeValue: raw.writeValue, readValue: raw.readValue, write, read };
+}
 /**
  * One `lastAction` out of a `TRACE` line's json, or null when the value is not one.
  *
@@ -1024,6 +1152,7 @@ export function parseTraceArtifacts(stdout) {
             const lead = parseTraceRequest(raw.lead);
             const lastAction = parseLastAction(raw.lastAction);
             const missingText = parseMissingText(raw.missingText);
+            const readContradiction = parseReadContradiction(raw.readContradiction);
             const otherContexts = Array.isArray(raw.otherContexts)
                 ? raw.otherContexts
                     .filter((c) => typeof c === 'object' && c !== null)
@@ -1054,10 +1183,13 @@ export function parseTraceArtifacts(stdout) {
                     ...(typeof a.context === 'string' ? { context: a.context } : {}),
                     ...(typeof a.pageId === 'string' ? { pageId: a.pageId } : {}),
                     ...(typeof a.frameId === 'string' ? { frameId: a.frameId } : {}),
+                    ...(typeof a.selector === 'string' && a.selector ? { selector: a.selector } : {}),
+                    ...(typeof a.value === 'string' ? { value: a.value } : {}),
                 })),
                 ...(otherContexts.length === 0 ? {} : { otherContexts }),
                 ...(raw.unattributed === true ? { unattributed: true } : {}),
                 ...(missingText === null ? {} : { missingText }),
+                ...(readContradiction === null ? {} : { readContradiction }),
             });
         }
         catch (_error) {
@@ -1589,6 +1721,33 @@ function credentialExchangeBody(sent) {
         return false;
     return (CREDENTIAL_IDENTITY.test(text) || /"(?:credentials|grant_type|refresh_token)"\s*:/i.test(text));
 }
+/**
+ * Whether a request PATH asks the app to mint a credential — a login, a registration, a token
+ * endpoint — as opposed to a protected resource that presents one.
+ *
+ * This is the path half of {@link isCredentialExchange}, exported so a caller holding only a
+ * `METHOD path` reads the same classification: a Hurl failing entry says
+ * `POST /api/users/login` and nothing about the body, and the whole-suite note must not explain
+ * a wrong-password login that answered 200 as a cookie-jar effect (xr-molecule-flash-m176).
+ *
+ * @param path - The request path (`/api/users/login`); a query or fragment is ignored.
+ * @param authEndpoints - The endpoints the app's auth config names (`/users/login`).
+ * @returns True when the path names a credential exchange.
+ */
+export function isCredentialExchangePath(path, authEndpoints = []) {
+    const clean = (path.split(/[?#]/)[0] ?? '').replace(/\/+$/, '');
+    if (clean === '')
+        return false;
+    // The app's own config names it: matched as a path suffix, because an auth config writes the
+    // endpoint relative to its API base (`/users/login`) while the trace records the mounted path
+    // (`/api/users/login`).
+    if (authEndpoints.some((endpoint) => {
+        const named = `/${String(endpoint).replace(/^\/+|\/+$/g, '')}`;
+        return named.length > 1 && (clean === named || clean.endsWith(named));
+    }))
+        return true;
+    return CREDENTIAL_EXCHANGE_PATH.test(clean);
+}
 /**
  * Whether a refused request is a CREDENTIAL EXCHANGE: the app was asked to mint a token (a login,
  * a registration, a token endpoint), so it never needed one attached.
@@ -1613,15 +1772,7 @@ function isCredentialExchange(request, authEndpoints) {
     const path = sameOriginPath(request);
     if (path === null)
         return false;
-    // The app's own config names it: matched as a path suffix, because an auth config writes the
-    // endpoint relative to its API base (`/users/login`) while the trace records the mounted path
-    // (`/api/users/login`).
-    if (authEndpoints.some((endpoint) => {
-        const named = `/${String(endpoint).replace(/^\/+|\/+$/g, '')}`;
-        return named.length > 1 && (path === named || path.endsWith(named));
-    }))
-        return true;
-    if (CREDENTIAL_EXCHANGE_PATH.test(path))
+    if (isCredentialExchangePath(path, authEndpoints))
         return true;
     return credentialExchangeBody(request.sent);
 }
@@ -2003,6 +2154,196 @@ function missingTextSentence(missing) {
         `not render it — the page drops it before rendering (a slice/filter/limit in the component ` +
         `that renders that list); find where that response is mapped.`);
 }
+/**
+ * The `name` attribute a locator's selector reads (`textarea[name="bio"]` → `bio`), or null when
+ * the selector names no field.
+ *
+ * Matching the form field to the request body's key is the whole point: a body that carries
+ * `"bio": ""` says nothing unless the trace also says the test typed a bio.
+ *
+ * @param selector - The selector a `fill`/`type`/`selectOption` action carried.
+ * @returns The field name, or null.
+ */
+function fieldNameOf(selector) {
+    const quoted = /\[\s*name\s*=\s*(["'])((?:(?!\1).)*)\1\s*\]/.exec(selector);
+    if (quoted !== null)
+        return quoted[2] === '' ? null : quoted[2];
+    const bare = /\[\s*name\s*=\s*([^\s\]]+)\s*\]/.exec(selector);
+    return bare === null ? null : (bare[1] ?? null);
+}
+/**
+ * Whether a JSON request body carries `key` with an EMPTY value (`""` or null), looking inside the
+ * wrapper object an API nests its entity under (`user`, `data`, `props`).
+ *
+ * A body that does not parse, or carries the key with a real value, is not evidence: the note only
+ * claims the page sent a field empty when it did.
+ *
+ * @param sent - The body the page sent, as the trace recorded it.
+ * @param key - The field name from the filled input's `name` attribute.
+ * @returns True when the body carries that key empty.
+ */
+function bodyCarriesEmptyField(sent, key) {
+    let parsed;
+    try {
+        parsed = JSON.parse(sent);
+    }
+    catch (_error) {
+        // A truncated body (the trace read bounds what it keeps) names no field confidently.
+        return false;
+    }
+    const read = (value, level) => {
+        if (level > 4 || value === null || typeof value !== 'object')
+            return null;
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                const found = read(item, level + 1);
+                if (found !== null)
+                    return found;
+            }
+            return null;
+        }
+        const record = value;
+        if (Object.prototype.hasOwnProperty.call(record, key)) {
+            return record[key] === '' || record[key] === null;
+        }
+        for (const nested of Object.values(record)) {
+            const found = read(nested, level + 1);
+            if (found !== null)
+                return found;
+        }
+        return null;
+    };
+    return read(parsed, 0) === true;
+}
+/**
+ * The field a test typed into that the same page submitted empty, when the trace recorded both.
+ *
+ * This is the Settings race of xr-molecule-flash-m173: `page.fill('textarea[name="bio"]', newBio)`
+ * then `button[type=submit]`, and the `PUT /api/user` carried `"bio": ""`. The form's seeding
+ * effect re-ran between the fill and the submit — on the deployed URL the background session
+ * verification lands later than it does locally, and it handed the form a new user object. The
+ * reading only pairs facts the trace holds: the filled value (its `selector`/`value`), the field
+ * name the selector names, and the next call to the app's API on that page whose body carries
+ * that key empty.
+ *
+ * @param item - One traced failure.
+ * @returns The evidence, or null when no filled field was submitted empty.
+ */
+function formResetOf(item) {
+    const requests = [...(item.lastAction?.requests ?? []), ...item.requests];
+    // A trace read before `actions` existed (or a hand-built one) carries none: no claim.
+    for (const action of item.actions ?? []) {
+        if (action.selector === undefined || action.value === undefined || action.value === '')
+            continue;
+        const field = fieldNameOf(action.selector);
+        if (field === null)
+            continue;
+        let next = null;
+        for (const request of requests) {
+            if (!/^(?:POST|PUT|PATCH)$/.test(request.method) || request.sent === undefined)
+                continue;
+            // The submit follows the typing; a request that started before it cannot have sent it.
+            if (typeof request.startedAt === 'number' && request.startedAt < action.start)
+                continue;
+            // Same page only: another context's set-up call is not this form's submit.
+            if (action.pageId !== undefined &&
+                request.pageId !== undefined &&
+                action.pageId !== request.pageId)
+                continue;
+            if (!bodyCarriesEmptyField(request.sent, field))
+                continue;
+            const earlier = next === null ||
+                (typeof request.startedAt === 'number' &&
+                    (typeof next.startedAt !== 'number' || request.startedAt < next.startedAt));
+            if (earlier)
+                next = request;
+        }
+        if (next !== null)
+            return { value: action.value, selector: action.selector, field, request: next };
+    }
+    return null;
+}
+/**
+ * The sentence for a submitted form field the test had just typed into, sent empty.
+ *
+ * It states the two recorded facts and the one inference they support — the form re-seeded after
+ * the typing — then the fix at the source: copy the loaded data into the form once, on its first
+ * load, instead of on every change of the data it was seeded from.
+ *
+ * @param reset - The filled field and the submit that carried it empty.
+ * @returns The sentence the note leads with.
+ */
+function formResetSentence(reset) {
+    return (`The test typed "${reset.value}" into ${reset.selector}, but ` +
+        `${requestLabel(reset.request)} sent "${reset.field}": "" — the form's state was reset after ` +
+        `typing (an effect re-seeding the form from data that changed identity ran again after the ` +
+        `test typed). Seed the form once, not every time that data changes.`);
+}
+/**
+ * The sentence for a write whose answer a later GET of the same resource contradicted.
+ *
+ * It states the two recorded facts and the one inference they support — the read route never saw
+ * the viewer — then the place to look: the route's middleware, not the page. It names both
+ * possibilities the trace cannot separate (a missing auth/optional-auth middleware on that route,
+ * or a different user), so the run checks the route instead of rewriting the component.
+ *
+ * @param contradiction - The write's answer and the later read's opposite one.
+ * @returns The sentence the note leads with.
+ */
+function readContradictionSentence(contradiction) {
+    return (`The server answered \`${contradiction.field}\`: ${contradiction.writeValue} to ` +
+        `${requestLabel(contradiction.write)} and \`${contradiction.field}\`: ` +
+        `${contradiction.readValue} to ${requestLabel(contradiction.read)} — the read route does not ` +
+        `see the viewer (a missing auth/optional-auth middleware on that route, or a different user); ` +
+        `check the route's middleware, not the page.`);
+}
+/**
+ * Chromium's webfont decode failure: the URL it fetched, and OTS's reason.
+ *
+ * A page that serves its SPA fallback for a missing `.woff` produces exactly this line — the
+ * browser downloads `index.html` and OTS rejects the first four bytes.
+ */
+const FONT_DECODE_FAILURE = /Failed to decode downloaded font:\s*(\S+)\s*\|\s*OTS parsing error:\s*(.+?)\s*$/i;
+/**
+ * Whether an OTS `invalid sfntVersion: <n>` number is four ASCII bytes that start an HTML
+ * document (`<!do` — `0x3C21646F` is the doctype's first four bytes).
+ *
+ * @param reason - The OTS reason text after `OTS parsing error:`.
+ * @returns True when the codec read an HTML signature instead of a font signature.
+ */
+function sfntVersionIsHtml(reason) {
+    const raw = /invalid sfntVersion:\s*(\d+)/i.exec(reason)?.[1];
+    if (raw === undefined)
+        return false;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0 || value > 0xffffffff)
+        return false;
+    const magic = String.fromCharCode((value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff);
+    return magic.startsWith('<');
+}
+/**
+ * One line of a failure row's `console:` list, with the webfont-decode signature explained.
+ *
+ * `Failed to decode downloaded font: <url> | OTS parsing error: invalid sfntVersion: 1008821359`
+ * is not a font to debug: the URL answered HTML (the app's `index.html`, the SPA fallback), so
+ * the file the `@font-face` names is not there. xr-molecule-flash-m186's page fetched
+ * `/fonts/ionicons.woff`, got the index document, and the note printed the raw decode error
+ * while the model went looking elsewhere.
+ *
+ * @param text - The console line, as the trace recorded it.
+ * @returns The line to print, naming the URL that served HTML when it is that failure.
+ */
+function consoleLine(text) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    const failure = FONT_DECODE_FAILURE.exec(normalized);
+    if (!failure)
+        return normalized;
+    const [, url, reason] = failure;
+    if (!sfntVersionIsHtml(reason))
+        return normalized;
+    return (`${url} answered the app's index.html, not a font — the file is missing from ` +
+        `\`app/public/\` (or the asset import); copy/import it`);
+}
 /**
  * The note a failed suite run's result carries: what each failing test's page actually sent, and
  * what came back.
@@ -2042,6 +2383,20 @@ function missingTextSentence(missing) {
  * context and the assertion's page cannot be identified, the note lists the requests and makes NO
  * causal claim — no "the test's last action", no "the page stayed at …" — instead of merging them.
  *
+ * A field the test filled and the page submitted EMPTY ({@link formResetOf}) leads the note: the
+ * trace holds both facts — the value typed into `textarea[name="bio"]` and the `PUT /api/user`
+ * whose body carried `"bio": ""` — so the form's state was reset between the typing and the
+ * submit. The note names the effect that re-seeds a form from data whose identity changed and the
+ * fix at the source (seed the form once). xr-molecule-flash-m173 lost a deploy-and-walk cycle to
+ * this on the deployed URL only, where the background session verification lands later than it
+ * does locally.
+ *
+ * A write whose response said a boolean field is true and a LATER GET of the same resource that
+ * said it is false leads the note first ({@link readContradictionSentence}): the read route never
+ * saw the viewer, so the fix is on that route's middleware, not in the page. xr-molecule-flash-m181
+ * spent ~8 minutes rewriting the profile component over exactly that pair — the write answered
+ * `{"following":true}` and the next profile GET answered `false`.
+ *
  * WHICH rows it spends is evidence, not artifact order (xr-molecule-flash-m112 +53:46): a row
  * needs a recorded response, a real failure or a console line ({@link traceRowEvidence}), rows are
  * deduplicated by the test's location, and they are ordered real failure → repeated from an
@@ -2304,7 +2659,7 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
         if (item.console.length > 0)
             parts.push(`console: ${item.console
                 .slice(0, 2)
-                .map((text) => text.replace(/\s+/g, ' ').trim().slice(0, 160))
+                .map((text) => consoleLine(text).slice(0, 160))
                 .join(' | ')}`);
         // A request from another browser context the test opened is not the failing action's effect:
         // it is set-up work on a different page, and it is named as such rather than merged into the
@@ -2402,7 +2757,38 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
     const missingTextLead = missingTexts.length === 0
         ? ''
         : `${missingTexts.slice(0, 2).map(missingTextSentence).join(' ')}\n\n`;
-    return (missingTextLead +
+    // A write whose answer a later GET of the same resource contradicted: the read route does not
+    // see the viewer (m181's `following` — the write answered true, the next profile GET answered
+    // false). It reads as a frontend race and is not one, so it leads the note before any row and
+    // before the form-reset reading.
+    const readContradictions = [
+        ...new Map(traced
+            .filter((item) => item.readContradiction !== undefined)
+            .map((item) => {
+            const contradiction = item.readContradiction;
+            return [
+                `${contradiction.field}\u0000${contradiction.write.method} ${contradiction.write.path}`,
+                contradiction,
+            ];
+        })).values(),
+    ];
+    const readContradictionLead = readContradictions.length === 0
+        ? ''
+        : `${readContradictions.slice(0, 2).map(readContradictionSentence).join(' ')}\n\n`;
+    // A field the test typed and the page submitted empty: the form re-seeded itself after the
+    // typing (m173's Settings race — the deployed URL lands the background session verification
+    // later than a local run, and its new user object re-ran the form's seeding effect between the
+    // fill and the submit). It is a direct cause of the failing request, so it leads the note.
+    const formResets = [
+        ...new Map(traced
+            .map(formResetOf)
+            .filter((reset) => reset !== null)
+            .map((reset) => [`${reset.request.method} ${reset.request.path}\u0000${reset.field}`, reset])).values(),
+    ];
+    const formResetLead = formResets.length === 0 ? '' : `${formResets.slice(0, 2).map(formResetSentence).join(' ')}\n\n`;
+    return (readContradictionLead +
+        formResetLead +
+        missingTextLead +
         transportLead +
         setupOriginLead +
         stalledLead +

package/dist/types.d.ts

@@ -164,6 +164,25 @@ export interface ToolBuildConfig {
      * @returns The quoted titles the request carves out.
      */
     excludedTestTitles?: () => readonly string[];
+    /**
+     * The `NAME=value` settings the person's request REQUIRES of a suite run (molecule-dev's
+     * `requiredRunSettings` — its mode, say), asked when the cause note composes a narrowed re-run
+     * of a finished run's failures. A re-run composed from the executor's own command inherits what
+     * that command set — and nothing it left out, so a run that measured the suite in `spa` handed
+     * back a re-run that would measure `spa` again (xr-molecule-flash-m182 +12:06: the request names
+     * `TEST_MODE=fullstack`, the run and its re-run both omitted it).
+     *
+     * A getter, not an array: the request is read per turn while the tool set is built once, and
+     * what the suite's own files read is the consumer's reading. Unset answers "nothing required".
+     *
+     * @param command - The command the finished run was started with.
+     * @param cwd - The resolved working directory it ran in.
+     * @returns The settings to put on a re-run of that command.
+     */
+    requiredSuiteEnv?: (command: string, cwd: string) => Promise<readonly {
+        name: string;
+        value: string;
+    }[] | null | undefined>;
     /**
      * The supplied suite's own budget, when the Playwright config a command would load sets
      * different settings, asked BEFORE the run executes. The consumer knows where the suite and its

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/utilities.d.ts

@@ -5,7 +5,7 @@
  * @module
  */
 import { type RunFailureKind } from './failure-kind.js';
-import { type DiagnosisRunContext } from './suite-overlap.js';
+import { type DiagnosisRunContext, type RunEnvSetting } from './suite-overlap.js';
 /**
  * Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
  * single-quoted strings prevent command substitution ($(), backticks) and variable expansion.
@@ -171,15 +171,19 @@ export declare const PLAYWRIGHT_FAILURES_INLINE_ENV = "PLAYWRIGHT_LIST_PRINT_FAI
  * is exactly when the executor reads the log, and without it a running log carries `✘` rows and
  * nothing else (xr-molecule-flash-m99 spent ~90 s on greps of one, then fixed what it guessed).
  *
- * Only the command's last step is touched, and only its reporter, and only when that step runs
- * something: `npx playwright test --list` takes two seconds and writes nothing per test, so
- * neither reporter nor `--retries=0` is added to it ({@link isPlaywrightRunCommand}).
+ * Only the step that runs the suite is touched, and only its reporter, and only when that step
+ * runs something: `npx playwright test --list` takes two seconds and writes nothing per test, so
+ * neither reporter nor `--retries=0` is added to it ({@link isPlaywrightRunCommand}). A trailing
+ * status step (`; echo EXIT $?`, `&& true`) is not the run and is skipped when the run step is
+ * found ({@link isStatusOnlyStep}); a run whose output is redirected to a file is still readable
+ * through that file, which the launch records as the task's own output.
  *
  * A command that starts the suite MORE THAN ONCE is not launched at all: every run it carries is
  * a whole walk of the same suite against the same app, and only the last step is rewritten, so the
  * earlier walks run unmeasured for nothing. X1 xr-molecule-flash-m157 (+14:02) chained two whole
  * walks of one 138-test suite with `;` — 4.5 minutes each — and the second measured nothing the
- * first had not. The platform already refuses a second CONCURRENT run against one app; this is the
+ * first had not. The platform refuses a second CONCURRENT run against one app and database by the
+ * ONE rule ({@link suiteRunInTheWay}) — for every pair, whatever uid a run mints — and this is the
  * same hazard inside one command ({@link suiteRunStatements}). `error` then carries the refusal,
  * naming each suite step and the ONE command to send instead (the last suite step, rewritten as
  * this function rewrites a run), and nothing is launched.
@@ -944,10 +948,21 @@ export interface UniversalCause {
 }
 /**
  * How many tests a run must have walked — with nothing passing since its first failure — before
- * "the page renders nothing" can be its one cause. A handful of failures is a handful of bugs;
- * a page that never painted fails every spec that reaches it, and m141's walk had 36 by +20:30.
- */
-export declare const EMPTY_PAGE_CAUSE_TESTS = 15;
+ * "the page renders nothing" can be its one cause.
+ *
+ * THREE, and the number is the cost of the alternative. The old floor of 15 was chosen when the
+ * reading was only offered at a completed run; once it STOPS the walk, every test waited for is
+ * a test whose result is thrown away, and a blank page costs its per-test budget each time
+ * (m177: 18 tests, ~4.2 minutes, on a page whose thrown error was visible in the first
+ * `pageerror`). Three is the smallest count that is not one page's own bug: the cause additionally
+ * needs three DISTINCT spec files (`UNIVERSAL_CAUSE_FILES`, or the files a narrowed run selected),
+ * each spec waiting for its OWN first element, and no test passing after the first failure. A page
+ * that renders misses elements, but three unrelated specs in three files failing at three
+ * different first locators with nothing passing in between is the page, not three bugs. At the
+ * suite's own 5 s action timeout that verdict lands ~20 s into the walk, so the early stop costs
+ * about one test's worth of time instead of fifteen.
+ */
+export declare const EMPTY_PAGE_CAUSE_TESTS = 3;
 /**
  * How many tests a connection-class cause must cover before the run is stopped even when they
  * are all in one file — see {@link universalCause}.
@@ -1154,8 +1169,8 @@ export declare function failuresByCause(log: string, excluded?: readonly string[
  * @param log - The finished run's output.
  * @param excluded - The test titles the request carves out, if the caller knows them.
  * @param run - How the run was started, when the caller knows it: the narrowed re-run is built
- *   from `command`/`cwd`/`config`, and `log` (the path the output was written to) is what the
- *   "left out" sentence greps when more causes exist than the result has room for.
+ *   from `command`/`cwd`/`config`/`env`, and `log` (the path the output was written to) is what
+ *   the "left out" sentence greps when more causes exist than the result has room for.
  * @returns The note, or null.
  */
 export declare function failureCausesNote(log: string, excluded?: readonly string[], run?: {
@@ -1163,6 +1178,7 @@ export declare function failureCausesNote(log: string, excluded?: readonly strin
     cwd?: string;
     log?: string;
     config?: string | null;
+    env?: readonly RunEnvSetting[];
 }, pageErrors?: readonly CausePageErrors[]): string | null;
 /**
  * The command that re-runs the tests at `locations` the way the run IN FLIGHT ran them: the same
@@ -1177,7 +1193,9 @@ export declare function failureCausesNote(log: string, excluded?: readonly strin
  * refused while the run walks ({@link suiteRunInTheWay}).
  *
  * @param run - The run in flight: the command it was started with, as it was run, the directory
- *   that command ran in, and the config it loaded when the caller knows it.
+ *   that command ran in, the config it loaded when the caller knows it, and the settings the
+ *   request required and the run left out (`env`) — the re-run carries them, so it never
+ *   reproduces the configuration the run was measured under by mistake (m182).
  * @param locations - The failing `file:line`s to re-run, as the run's log printed them.
  * @param excluded - The test titles the request carves out: the re-run inverts them out
  *   (`--grep-invert`) so it cannot report them again.
@@ -1187,6 +1205,7 @@ export declare function rerunOfRunningSuite(run: {
     command: string;
     cwd?: string;
     config?: string | null;
+    env?: readonly RunEnvSetting[];
 }, locations: readonly string[], excluded?: readonly string[]): string | null;
 /**
  * The sentence that names a cause repeating among a running suite's failures, mid-run.
@@ -1233,6 +1252,7 @@ export declare function repeatingFailureNote(found: RepeatingFailure, o: {
     run?: {
         command: string;
         cwd?: string;
+        env?: readonly RunEnvSetting[];
     };
     editsInvalidateRun?: boolean;
 }): string;