@molecule/api-ai-tools 1.9.16 → 1.9.18

package/dist/trace-artifacts.js

@@ -27,7 +27,6 @@
  * @module
  */
 import { locatedCommandSegments, statementArgumentEnd } from './command-position.js';
-import { isDiagnosisRun } from './suite-overlap.js';
 import { isPlaywrightRunCommand, redactSecrets } from './utilities.js';
 /** How many traces one read reports, newest first. */
 export const MAX_TRACE_ARTIFACTS = 12;
@@ -198,6 +197,27 @@ function messageOf(value) {
   return null
 }
 
+// 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
+// selector with no text argument. The ANSI colouring Playwright leaves in the message is dropped
+// before the read, or the quotes it wraps around a locator would never parse.
+function waitedTextOf(message) {
+  if (!message) return null
+  const text = String(message).replace(/\\u001b\\[[0-9;]*m/g, '')
+  if (text.indexOf('strict mode violation') !== -1) return null
+  const quoted = function (pattern) {
+    const m = pattern.exec(text)
+    return m === null ? null : m[2]
+  }
+  const hasText = quoted(/has-text\\(\\s*(['"])((?:(?!\\1).)*)\\1/)
+  if (hasText !== null) return hasText
+  const byText = quoted(/getByText\\(\\s*(['"])((?:(?!\\1).)*)\\1/)
+  if (byText !== null) return byText
+  if (text.indexOf('toContainText') === -1) return null
+  return quoted(/Expected(?: string)?:\\s*(["'])((?:(?!\\1).)*)\\1/)
+}
+
 // A request/response body exactly as Playwright stored it: inline on the value, or in a resource
 // entry the value names. Bounded, and binary is dropped — a JSON body is what this is for, and a
 // multipart upload would print bytes.
@@ -459,6 +479,7 @@ for (const one of found.slice(0, MAX_TRACES)) {
   let failedStepId = null
   let failedStep = null
   let failedEnd = null
+  let failedError = ''
   let failureSpec = null
   let failureLine = 0
   let lastSpec = null
@@ -468,6 +489,7 @@ for (const one of found.slice(0, MAX_TRACES)) {
     if (entry.type === 'after' && entry.error && typeof entry.callId === 'string' && failedStepId === null) {
       failedStepId = entry.callId
       failedEnd = typeof entry.endTime === 'number' ? entry.endTime : null
+      failedError = messageOf(entry.error) || ''
     }
   }
   // The fallback location — the last step that names a spec — is read from every member, runner
@@ -710,6 +732,26 @@ for (const one of found.slice(0, MAX_TRACES)) {
     if (sent) r.sent = sent
     if (got) r.got = got
   }
+  // The text the failing assertion waited for, and a response the SAME page received that carried
+  // it (m169). The assertion's own error names the text; the network log says whether it ever
+  // reached the browser. Only an answered fetch/xhr can say the API returned it — a 4xx body is an
+  // error message, not data. The most focused response wins (smallest body): an articles list also
+  // carries tag names in its \`tagList\`, while the tags response is the collection whose membership
+  // the assertion tests.
+  const waitedText = waitedTextOf(failedError)
+  let missingText = null
+  if (waitedText !== null && !unattributed) {
+    let best = null
+    for (const r of requests) {
+      if (r.type !== 'fetch' && r.type !== 'xhr') continue
+      if (r.status < 200 || r.status >= 400) continue
+      const got = gotText(buf, entries, r)
+      if (!got || got.indexOf(waitedText) === -1) continue
+      if (best === null || got.length < best.got.length) best = { request: r, got: got }
+    }
+    if (best !== null)
+      missingText = { text: waitedText, method: best.request.method, path: best.request.path }
+  }
   function wire(r) {
     return {
       method: r.method,
@@ -881,6 +923,7 @@ for (const one of found.slice(0, MAX_TRACES)) {
     // tail here dropped every failed request as soon as a page made more than MAX_REQUESTS of them
     // 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 }),
     console: keptConsole.slice(0, MAX_CONSOLE).map(function (text) { return text.slice(0, 300) }),
     actions: actions.slice(-MAX_ACTIONS),
     ...(unattributed ? { unattributed: true } : {}),
@@ -917,6 +960,24 @@ function parseTraceRequest(value) {
         ...(typeof r.pageId === 'string' && r.pageId ? { pageId: r.pageId } : {}),
     };
 }
+/**
+ * One `missingText` out of a `TRACE` line's json, or null when the value is not one.
+ *
+ * @param value - The line's `missingText`.
+ * @returns The awaited text and the response that carried it, or null.
+ */
+function parseMissingText(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value;
+    if (typeof raw.text !== 'string' || raw.text === '')
+        return null;
+    if (typeof raw.method !== 'string' || raw.method === '')
+        return null;
+    if (typeof raw.path !== 'string' || raw.path === '')
+        return null;
+    return { text: raw.text, method: raw.method, path: raw.path };
+}
 /**
  * One `lastAction` out of a `TRACE` line's json, or null when the value is not one.
  *
@@ -962,6 +1023,7 @@ export function parseTraceArtifacts(stdout) {
             const actions = Array.isArray(raw.actions) ? raw.actions : [];
             const lead = parseTraceRequest(raw.lead);
             const lastAction = parseLastAction(raw.lastAction);
+            const missingText = parseMissingText(raw.missingText);
             const otherContexts = Array.isArray(raw.otherContexts)
                 ? raw.otherContexts
                     .filter((c) => typeof c === 'object' && c !== null)
@@ -995,6 +1057,7 @@ export function parseTraceArtifacts(stdout) {
                 })),
                 ...(otherContexts.length === 0 ? {} : { otherContexts }),
                 ...(raw.unattributed === true ? { unattributed: true } : {}),
+                ...(missingText === null ? {} : { missingText }),
             });
         }
         catch (_error) {
@@ -1500,6 +1563,68 @@ function sameOriginPath(request) {
         return null;
     return raw.replace(/\/+$/, '');
 }
+/**
+ * The path segments a request ASKS FOR a credential through — a login, a registration, a token
+ * endpoint — as opposed to a protected resource that presents one.
+ */
+const CREDENTIAL_EXCHANGE_PATH = /(?:^|\/)(?:login|log-in|signin|sign-in|register|signup|sign-up|token)(?:\/|$)/i;
+/** The field a credential payload carries: a password, a grant, or a refresh token. */
+const CREDENTIAL_FIELD = /"(?:password|credentials|grant_type|refresh_token)"\s*:/i;
+/** The field that pairs with a password in a login/registration body. */
+const CREDENTIAL_IDENTITY = /"(?:email|username)"\s*:/i;
+/**
+ * Whether a request's recorded body is a credential payload — the shape a login, a registration
+ * or a token exchange sends, never a protected write (an article, a comment, a profile).
+ *
+ * @param sent - What the request sent, as the trace recorded it (bounded).
+ * @returns True for a body carrying credentials.
+ */
+function credentialExchangeBody(sent) {
+    if (!sent)
+        return false;
+    const text = sent.slice(0, MAX_TRACED_BODY_CHARS);
+    // A password alone is a profile write as often as a login; the exchange is a password beside
+    // an identity, or a token grant.
+    if (!CREDENTIAL_FIELD.test(text))
+        return false;
+    return (CREDENTIAL_IDENTITY.test(text) || /"(?:credentials|grant_type|refresh_token)"\s*:/i.test(text));
+}
+/**
+ * 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.
+ *
+ * Three readings, weakest last: the app's own auth config names the endpoint (a project may mount
+ * `/session` or `/auth/signin`), the path's own last segments name it (`/users/login`), or the
+ * body is a credential payload (`{"user":{"email":…,"password":…}}` sends a registration).
+ *
+ * xr-molecule-flash-m165 (+10:22): `POST /api/users/login → 401
+ * {"errors":{"credentials":["invalid"]}}` was answered with the missing-token sentence — "the
+ * client did not attach the token … The API handler is not the problem" — for a request whose
+ * whole purpose is to obtain a token. The model read helpers and configs for 40 minutes instead of
+ * the real cause: the suite's setup had seeded `https://api.realworld.show`, not this app.
+ *
+ * @param request - The refused request (401/403).
+ * @param authEndpoints - The endpoints the app's auth config names (`/users/login`).
+ * @returns True when the request is a credential exchange.
+ */
+function isCredentialExchange(request, authEndpoints) {
+    if (request.method !== 'POST')
+        return false;
+    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))
+        return true;
+    return credentialExchangeBody(request.sent);
+}
 /**
  * The sentence a 401/403 on the app's own API gets: which half of the wire refused the request.
  *
@@ -1521,6 +1646,15 @@ function sameOriginPath(request) {
  * sent through. When the trace carries that line, the no-header sentence names the ordering fix
  * instead of leaving the run to re-derive it.
  *
+ * xr-molecule-flash-m165 (+10:22): a `POST /api/users/login → 401
+ * {"errors":{"credentials":["invalid"]}}` is a CREDENTIAL EXCHANGE — the request is how a token is
+ * obtained, so an absent `Authorization` header is the request being what it is, not a client bug.
+ * The note said "the client did not attach the token … The API handler is not the problem" and the
+ * run went looking through the app instead of at the credentials or the setup's API origin. The
+ * exchange branch names the credentials, the account's origin, and the response body; the
+ * categorical handler sentence is gone from the no-header branch too, because a route that
+ * requires a token where the app allows anonymous access is the handler's own mistake.
+ *
  * The trace cannot name the file that made the call: a real HAR entry carries the request, response,
  * `_resourceType`, `_monotonicTime` and a frame ref, but no initiator stack. So the sentence names
  * the shared client and the auth bond instead of guessing a file.
@@ -1528,14 +1662,30 @@ function sameOriginPath(request) {
  * @param request - The refused request, a 401 or 403 on the app's own origin.
  * @param unbondedClient - Whether the traced page logged `no client is bonded`, which explains a
  *   request that carried no `Authorization` header.
+ * @param authEndpoints - The endpoints the app's auth config names, so a credential exchange is
+ *   recognised even under a path the segment list does not.
  * @returns The sentence the note appends.
  */
-function authRefusalSentence(request, unbondedClient = false) {
+function authRefusalSentence(request, unbondedClient = false, authEndpoints = []) {
     const label = requestLabel(request);
     // The header's scheme, when it parsed; presence alone is still the server's half of the wire.
     const carried = request.authorization !== undefined
         ? `with \`Authorization: ${request.authorization} …\``
         : 'with an `Authorization` header';
+    // A credential exchange asks the app to MINT a token: no token is expected to be attached, so a
+    // refusal here is about the credentials themselves — never the client's omission (m165).
+    if (isCredentialExchange(request, authEndpoints)) {
+        const got = request.got
+            ? ` got ${bodyLine(redactSecrets(request.got), TRACE_NOTE_GOT_CHARS)}`
+            : '';
+        return (`The browser sent \`${label}\`${got} and the API answered ${request.status} — this is a ` +
+            'credential exchange (a login/registration/token endpoint), so the client is not expected ' +
+            'to attach a token: the credentials were rejected. Check that the account the test logs in ' +
+            'with was created on THIS app — the same database and origin this run drives; a user seeded ' +
+            'somewhere else is unknown here — and read the response body’s `errors` (a login answers 401 ' +
+            '`{"errors":{"credentials":["invalid"]}}` for a wrong email/password or a user that does not ' +
+            'exist here).');
+    }
     // The console line names the mechanism the no-header branch otherwise has to guess at:
     // `getClient()` ran before `setupHttpDefault()` and the token was mirrored into the
     // client that later setup replaced (xr-molecule-flash-m156).
@@ -1573,21 +1723,23 @@ function authRefusalSentence(request, unbondedClient = false) {
             ? 'The request did carry a `Cookie` header, so if this app signs in with a session cookie ' +
                 'that is the credential the server did not accept. '
             : '') +
-        'The API handler is not the problem.' +
         unbonded);
 }
 /**
  * The note's credential-refusal advice, one sentence per distinct shape — at most two.
  *
- * The shapes are `(status, Authorization scheme, cookie present)`: m148's ten walks repeated one
- * shape (`401`, no header) on every failing test, and repeating its sentence per row would bury
- * the fact rather than state it.
+ * The shapes are `(status, Authorization scheme, cookie present, credential exchange)`: m148's ten
+ * walks repeated one shape (`401`, no header) on every failing test, and repeating its sentence per
+ * row would bury the fact rather than state it. A login and a protected request that both carry no
+ * header are DIFFERENT shapes — one is the credentials being checked, the other is a token that was
+ * never attached (m165).
  *
  * @param items - The traces the note is about.
+ * @param authEndpoints - The endpoints the app's auth config names.
  * @returns The sentences to append (each led by a space), or '' when no same-origin 401/403 was
  *   traced.
  */
-function authRefusalAdvice(items) {
+function authRefusalAdvice(items, authEndpoints = []) {
     const sentences = [];
     const seen = new Set();
     // A page that logged `no client is bonded` explains every request it sent without a
@@ -1604,11 +1756,12 @@ function authRefusalAdvice(items) {
             // ignores it and clears the session, and the page owes the navigation (m156).
             if (isLogoutRequest(request))
                 continue;
-            const key = `${request.status} ${request.sentAuthorization ? (request.authorization ?? 'header') : 'none'} ${request.sentCookie ? 'cookie' : ''}`;
+            const exchange = isCredentialExchange(request, authEndpoints);
+            const key = `${request.status} ${exchange ? 'exchange' : request.sentAuthorization ? (request.authorization ?? 'header') : 'none'} ${request.sentCookie ? 'cookie' : ''}`;
             if (seen.has(key))
                 continue;
             seen.add(key);
-            sentences.push(authRefusalSentence(request, unbondedClient));
+            sentences.push(authRefusalSentence(request, unbondedClient, authEndpoints));
             if (sentences.length === 2)
                 return ` ${sentences.join(' ')}`;
         }
@@ -1674,6 +1827,117 @@ function tracedApiPrefixes(items) {
     }
     return [...prefixes].sort();
 }
+/**
+ * Every API path prefix the traces support: the one the app's client config names and the ones the
+ * traces' own same-origin requests show ({@link tracedApiPrefixes}).
+ *
+ * @param items - The traces the note is about.
+ * @param apiPrefixes - Prefixes the app's client config names (`['/api']`), never a literal.
+ * @returns The one-segment prefixes, without duplicates.
+ */
+function knownApiPrefixes(items, apiPrefixes) {
+    const prefixes = new Set([...apiPrefixes, ...tracedApiPrefixes(items)]
+        .map((prefix) => `/${String(prefix).replace(/^\/+|\/+$/g, '')}`)
+        .filter((prefix) => prefix !== '/'));
+    return [...prefixes];
+}
+/** A URL written in full (`https://api.realworld.show/api/articles`). */
+const ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+/**
+ * The API requests a trace made to an origin other than the page's own — set-up traffic that ran
+ * against someone else's server.
+ *
+ * The trace reader relativises every request whose origin is the page's (`pathOf`), so a request
+ * recorded with an absolute URL went to ANOTHER origin by construction. It counts as set-up/API
+ * traffic when its path carries a prefix the app's own API is known to use ({@link
+ * knownApiPrefixes}) — a CDN font or a third-party script has no `/api` under it, and with no
+ * known prefix nothing is claimed.
+ *
+ * xr-molecule-flash-m165 (+10:22): the suite's helper defaulted `API_BASE` to
+ * `https://api.realworld.show/api` and its set-up seeded rows there, while the browser drove this
+ * app — whose own `/api` answers a login for none of those users. The trace's absolute-URL rows
+ * were the evidence, and the note said nothing about them.
+ *
+ * @param items - The traces the note is about.
+ * @param apiPrefixes - Prefixes the app's client config names (`['/api']`).
+ * @returns One entry per distinct (origin, prefix), in trace order.
+ */
+function foreignOriginApiRequests(items, apiPrefixes) {
+    const prefixes = knownApiPrefixes(items, apiPrefixes);
+    if (prefixes.length === 0)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const item of items) {
+        for (const request of item.requests) {
+            const raw = String(request.path ?? '');
+            if (!ABSOLUTE_URL.test(raw))
+                continue;
+            let parsed;
+            try {
+                parsed = new URL(raw);
+            }
+            catch (_error) {
+                // Not a URL this can parse: it is not evidence of another origin.
+                continue;
+            }
+            const prefix = prefixes.find((one) => parsed.pathname === one || parsed.pathname.startsWith(`${one}/`));
+            if (prefix === undefined)
+                continue;
+            const key = `${parsed.origin}${prefix}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ origin: parsed.origin, prefix, request });
+        }
+    }
+    return out;
+}
+/**
+ * The origin a run's target names, when it names one: a URL (`http://localhost:4173`), or the
+ * deployed host the note prints (`loopcheck-….apps.mlcl.dev`). Null for the note's descriptive
+ * targets ("the deployed app", "the local app").
+ *
+ * @param target - Where the run went, as {@link failureTraceNote} names it.
+ * @returns The origin, or null.
+ */
+function appOriginOfTarget(target) {
+    const text = target.trim();
+    try {
+        if (ABSOLUTE_URL.test(text))
+            return new URL(text).origin;
+        if (/^[a-z0-9.-]+(?::\d+)?$/i.test(text))
+            return new URL(`https://${text}`).origin;
+    }
+    catch (_error) {
+        // A target that is not a URL names no origin.
+    }
+    return null;
+}
+/**
+ * The sentence naming the foreign origin a run's set-up traffic went to, and the setting that
+ * points it at this app instead.
+ *
+ * It leads the note because it is the cheapest possible wrong result: every row the suite creates
+ * lands in a database this app never reads, so the failure says nothing about the app's code.
+ * xr-molecule-flash-m165 spent the walk after its failed login reading helpers and configs for a
+ * missing token, when the command's `BASE_URL`/`API_BASE` disagreement was the cause.
+ *
+ * @param found - The foreign-origin request the trace holds.
+ * @param target - Where the run went, for the app's own origin when the note knows it.
+ * @returns The sentence, led by nothing and closed by a blank line.
+ */
+function foreignOriginSentence(found, target) {
+    const appOrigin = appOriginOfTarget(target);
+    const where = appOrigin ?? 'this app’s origin';
+    const apiBase = `${appOrigin ?? '<this app’s origin>'}${found.prefix}`;
+    return (`The suite’s setup ran against ${found.origin}, not this app ` +
+        `(\`${requestLabel(found.request)}\`) — its set-up/API traffic went to another origin while ` +
+        `this app serves its own API at \`${found.prefix}\` on ${where}. Set ` +
+        `\`API_BASE=${apiBase}\` on the run — the supplied suite reads it (verify the variable name ` +
+        `in the suite’s own helpers before writing it) — so the rows it creates are in the database ` +
+        `this app reads.\n\n`);
+}
 /**
  * The failed 404s whose path carries none of the known API prefixes.
  *
@@ -1687,12 +1951,9 @@ function tracedApiPrefixes(items) {
  * @returns One entry per distinct failed 404, in trace order.
  */
 function missingApiPrefixRequests(items, apiPrefixes) {
-    const prefixes = new Set([...apiPrefixes, ...tracedApiPrefixes(items)]
-        .map((prefix) => `/${String(prefix).replace(/^\/+|\/+$/g, '')}`)
-        .filter((prefix) => prefix !== '/'));
-    if (prefixes.size === 0)
+    const known = knownApiPrefixes(items, apiPrefixes);
+    if (known.length === 0)
         return [];
-    const known = [...prefixes];
     const out = [];
     const seen = new Set();
     for (const item of items) {
@@ -1726,6 +1987,22 @@ function missingApiPrefixSentence(request) {
         `without the \`${request.prefix}\` prefix — the HTTP client's base URL is not set: is ` +
         '`setupProviders()` (which runs the HTTP bond setup) called in `main.tsx`?');
 }
+/**
+ * The sentence for a failing assertion whose awaited text a same-page API response carried.
+ *
+ * It names the response and the fact the trace proves — the value reached the browser and the page
+ * did not render it — and stops there. Which cut drops it (a slice, a filter, a limit) is in the
+ * component that maps the response, and the note cannot see that component; naming the mapping
+ * step is the whole instruction (xr-molecule-flash-m169).
+ *
+ * @param missing - The awaited text and the response that carried it.
+ * @returns The sentence the note leads with.
+ */
+function missingTextSentence(missing) {
+    return (`The API returned "${missing.text}" (in ${missing.method} ${missing.path}), but the page did ` +
+        `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 note a failed suite run's result carries: what each failing test's page actually sent, and
  * what came back.
@@ -1803,6 +2080,13 @@ function missingApiPrefixSentence(request) {
  * xr-molecule-flash-m148 (+29:18) hit this exactly: six local walks read
  * `POST …/favorite → 401 {"errors":{"token":["is missing"]}}` as a handler bug.
  *
+ * A credential EXCHANGE (a login/registration/token endpoint, read from the app's auth config, the
+ * path or the body) is never that shape: the request's purpose is to obtain a token, so an absent
+ * header is not a client omission ({@link isCredentialExchange}). xr-molecule-flash-m165's login
+ * 401 was answered as one for 40 minutes; the trace also showed the suite's SET-UP traffic going
+ * to `https://api.realworld.show/api` instead of this app, which is what the note leads with
+ * ({@link foreignOriginApiRequests}).
+ *
  * @param items - The traces {@link parseTraceArtifacts} read.
  * @param target - Where the run went — the deployed host, as the note names it.
  * @param earlierFailures - The failing `file:line`s earlier walks of this suite left, so a repeat
@@ -1870,7 +2154,12 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
     // Every recorded failure is the logout endpoint answering 4xx: the row's own sentence explains
     // it, and neither the handler lead nor the credential reading applies (m156 +24:02).
     const onlyLogoutFailures = failedRequests.length > 0 && failedRequests.every((request) => isLogoutRequest(request));
-    const authAdvice = authRefusalAdvice(traced);
+    const authAdvice = authRefusalAdvice(traced, report.authEndpoints ?? []);
+    // Set-up traffic the trace shows going to an origin other than the app's (m165): the rows it
+    // creates are not in this app's database, so the note says it before any app-side reading.
+    const foreignOrigins = foreignOriginApiRequests(traced, apiPrefixes);
+    const [firstForeign] = foreignOrigins;
+    const setupOriginLead = firstForeign === undefined ? '' : foreignOriginSentence(firstForeign, target);
     // The stalled-navigation reading, per traced test: non-null only when the RUNNER says this
     // test's failing operation is a navigation and a document subresource still pending at the end
     // started inside that wait ({@link stalledNavigation}).
@@ -2098,7 +2387,24 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
             `does not define is always undefined, and a missing effect dependency on the route means ` +
             `the fetch never re-runs — before touching the markup or the CSS.\n\n`
         : '';
-    return (transportLead +
+    // An assertion whose awaited text a same-page API response carried: the fact the run needs
+    // first, before any row, is that the value arrived and the page dropped it (m169's missing
+    // "trending" came back from GET /api/tags while the sidebar rendered a cut list). Each distinct
+    // response is named once; the note makes no claim about which cut did it.
+    const missingTexts = [
+        ...new Map(traced
+            .filter((item) => item.missingText !== undefined)
+            .map((item) => {
+            const missing = item.missingText;
+            return [`${missing.method} ${missing.path}\u0000${missing.text}`, missing];
+        })).values(),
+    ];
+    const missingTextLead = missingTexts.length === 0
+        ? ''
+        : `${missingTexts.slice(0, 2).map(missingTextSentence).join(' ')}\n\n`;
+    return (missingTextLead +
+        transportLead +
+        setupOriginLead +
         stalledLead +
         staleRouteLead +
         `The platform read the failing tests' own Playwright traces from the run against ${target} ` +
@@ -2289,24 +2595,27 @@ async function readRunConfig(command, cwd, readFile) {
     return '';
 }
 /**
- * The command a DIAGNOSIS run needs to leave a readable trace behind, when the suite's config
+ * The command a Playwright run needs to leave a readable trace behind, when the suite's config
  * would record none.
  *
  * The failing tests' requests are only readable if the run wrote them down (see the module doc),
  * and the config is where the decision about that lives — the platform does not edit the suite's
- * config, so it passes the flag instead, and only where it can do no harm: on a run narrowed to a
- * part of the suite or capped ({@link isDiagnosisRun}), never on the whole-suite proof run, and
- * never over a `--trace` the executor wrote itself. A capped walk is exactly the run whose
- * failures someone is about to work on; the proof run is graded as it is.
+ * config, so it passes the flag instead, on every Playwright run that starts tests and does not
+ * already decide its own `--trace`. That includes the whole-suite proof run, which an earlier
+ * version of this function skipped on the reasoning that its flags are graded: the flag changes
+ * what is RETAINED, not what passes. `retain-on-failure` keeps the trace only of a test that
+ * fails — Playwright records it and deletes it when the test passes (playwright's
+ * `_shouldAbandonTrace` unlinks the temporary trace files of a passing test) — so a green proof
+ * run keeps nothing extra. A failing one keeps the network log its failures need.
+ * xr-molecule-flash-m163 (+24:58) is why the proof run is no longer skipped: its one deployed
+ * failure left only an `error-context.md`, the executor spent the next calls hunting a `trace.zip`
+ * that could not exist, and then shipped a guessed fix.
  *
  * @param args - The command, the directory it starts in, and the backend's file read.
  * @returns The command to run and the sentence to report, or the command unchanged.
  */
 export async function diagnosisTraceCommand(args) {
     const unchanged = { command: args.command, change: null };
-    // The proof run is the one run this must never touch: its flags are graded.
-    if (!isDiagnosisRun(args.command))
-        return unchanged;
     if (namesTraceMode(args.command))
         return unchanged;
     // Only a Playwright run leaves a trace to read.
@@ -2330,7 +2639,8 @@ export async function diagnosisTraceCommand(args) {
     return {
         command: `${args.command.slice(0, at)} ${DIAGNOSIS_TRACE_FLAG}${args.command.slice(at)}`,
         change: `Added \`${DIAGNOSIS_TRACE_FLAG}\`: the suite's config records no trace for a failure` +
-            `${/trace:/.test(config) ? '' : ' (it sets none)'}, and this diagnosis run's failures are ` +
-            'what the platform reads the network log from. The proof run keeps the suite’s own settings.',
+            `${/trace:/.test(config) ? '' : ' (it sets none)'}, and a failing test's own network log is ` +
+            'what the platform reads the cause from. It keeps a trace only for a test that fails, so a ' +
+            'green run retains nothing.',
     };
 }

package/dist/types.d.ts

@@ -49,6 +49,29 @@ export interface ExecutionBackend {
         exitCode: number;
     }>;
 }
+/**
+ * The supplied suite's own settings, put back on a run whose runner config changes them.
+ *
+ * A graded suite is walked by the grader under its own per-test budget, worker count and
+ * timeouts. An executor's run that reads a config setting different numbers measures a run the
+ * grader never sees: a shorter budget fails tests the graded walk passes, a longer one passes
+ * tests the graded walk times out on. The platform that knows the suite supplies these values
+ * before the run ({@link ToolBuildConfig.suiteBudget}); the shared tool puts the flags on the
+ * runner's own command line, where Playwright lets them win over every config file.
+ */
+export interface SuiteBudgetPin {
+    /**
+     * The Playwright flags that carry the suite's own settings onto the command
+     * (`--timeout=15000`, `--workers=1`), as the consumer's own scan reads them. Empty when the
+     * difference is in settings no flag carries — the pin is then the sentence alone.
+     */
+    flags: string[];
+    /**
+     * One sentence for the run's result: this run uses the suite's own budget, and which settings
+     * a config keeps because Playwright has no flag for them.
+     */
+    note: string;
+}
 /**
  * Configuration for building the tool set.
  * Allows consumers to customize security, callbacks, and tool selection.
@@ -141,6 +164,22 @@ export interface ToolBuildConfig {
      * @returns The quoted titles the request carves out.
      */
     excludedTestTitles?: () => readonly string[];
+    /**
+     * 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
+     * base config live; this shared package does not, so the reading is the consumer's and the
+     * mechanics — putting the flags on the runner's own arguments, before the pipeline and outside
+     * any redirect or group closer — are this tool's.
+     *
+     * Called for a Playwright suite command only, and only the LAST suite step is touched. A run
+     * that already keeps the suite's settings, or a sandbox with no supplied suite, answers `null`.
+     * Unset (or a hook that throws) changes nothing: the command runs as the model wrote it.
+     *
+     * @param command - The shell command, as the model sent it.
+     * @param cwd - The resolved working directory it will run in.
+     * @returns The flags and the sentence, or null when nothing is put back.
+     */
+    suiteBudget?: (command: string, cwd: string) => Promise<SuiteBudgetPin | null | undefined>;
     /** Post-write hook (e.g. auto-format via Prettier/ESLint). Called after every write_file/edit_file. */
     onAfterWrite?: (path: string) => Promise<void>;
     /** Diff tracking callback. Called before writes with old/new content. */

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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"}