@molecule/api-ai-tools 1.9.6 → 1.9.8

package/dist/trace-artifacts.js

@@ -49,6 +49,12 @@ export const TRACE_NOTE_URL_CHARS = 96;
 export const TRACE_NOTE_SENT_CHARS = 160;
 /** How much of the response body the note prints — the API's first error line. */
 export const TRACE_NOTE_GOT_CHARS = 120;
+/**
+ * How much of the FAILING STEP's response body the note prints. Longer than
+ * {@link TRACE_NOTE_GOT_CHARS}: it is the one line that answers "what did the click actually get
+ * back", and an app's own body (`{"profile":{…}}`) can carry the answer past its first clause.
+ */
+export const TRACE_NOTE_LEAD_GOT_CHARS = 200;
 /** How much of a network error's own text (`net::ERR_CONNECTION_REFUSED`) the note prints. */
 const TRACE_NOTE_FAILURE_CHARS = 120;
 /**
@@ -244,10 +250,38 @@ for (const one of found.slice(0, MAX_TRACES)) {
     if (sent) r.sent = sent
     if (got) r.got = got
   }
+  // The page's own actions, timed. before/after pair on the call id, and only the LIBRARY
+  // traces carry a class and a method (Frame.goto, Locator.fill); the test runner's own
+  // trace times its hooks and fixtures with class Test, which is not a page action. Read BEFORE
+  // the request buckets: whether the navigation itself finished decides whether a subresource
+  // with no response is evidence (see \`navigationOpen\` below).
+  const ended = {}
+  for (const entry of trace) {
+    if (entry && entry.type === 'after' && typeof entry.callId === 'string' && typeof entry.endTime === 'number')
+      ended[entry.callId] = entry.endTime
+  }
+  const actions = []
+  for (const entry of trace) {
+    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
+    actions.push({
+      api: entry.class + '.' + entry.method,
+      start: entry.startTime,
+      end: typeof ended[entry.callId] === 'number' ? ended[entry.callId] : null,
+    })
+  }
+  // A \`page.goto\` that has no end time: the page never finished loading. When that is the
+  // failure, a document subresource with no response is the reason — the navigation waits for
+  // its stylesheets and scripts — and it is evidence, not the aborted noise a finished
+  // navigation leaves behind (xr-molecule-flash-m135: three goto timeouts on a deployed app
+  // where one 88 KB stylesheet fetch stalled 27 s, and the trace of each held the pending CSS).
+  const navigationOpen = actions.some(function (a) { return /\\.goto$/.test(a.api) && a.end === null })
   // The page shell's own requests (a service worker probe, a manifest, a font) are not the
   // failing step's dependencies: a 404 on one, or no response at all, is not a cause and takes
   // no row (xr-molecule-flash-m125 +29:33 — "GET /sw.js; GET /fonts/ionicons.woff" sent the
-  // model to write a caching service worker into the app).
+  // model to write a caching service worker into the app). A document's OWN stylesheet or
+  // script is not shell noise: the navigation blocks on it.
   const SHELL_TYPE = { font: 1, image: 1, stylesheet: 1, script: 1, manifest: 1 }
   function shellPath(path) {
     return /^\\/(?:sw|service-worker)\\.js(?:[?#]|$)|\\/manifest\\.webmanifest(?:[?#]|$)|\\/favicon[^/]*(?:[?#]|$)|\\/fonts?\\//.test(path) ||
@@ -257,6 +291,13 @@ for (const one of found.slice(0, MAX_TRACES)) {
     if (r.type === 'document') return false
     return SHELL_TYPE[r.type] === 1 || shellPath(r.path)
   }
+  // The shell requests that stay noise even when they never finished: the PWA worker, the
+  // manifest, a favicon, a font. A pending \`/assets/*.css\` is the document's dependency.
+  function incidentalShell(r) {
+    if (r.type === 'document') return false
+    return r.type === 'font' || r.type === 'manifest' ||
+      /^\\/(?:sw|service-worker)\\.js(?:[?#]|$)|\\/manifest\\.webmanifest(?:[?#]|$)|\\/favicon[^/]*(?:[?#]|$)|\\/fonts?\\//.test(r.path)
+  }
   // A failed request: a 4xx/5xx, or no response at all WITH Playwright's error text (a refused
   // connection). No response and no text is an aborted/pending request, not a failure. A 404 on
   // the page shell is excepted, for the reason above.
@@ -264,18 +305,72 @@ for (const one of found.slice(0, MAX_TRACES)) {
     if (shellRequest(r) && r.status === 404) return false
     return r.status >= 400 || (r.status <= 0 && typeof r.failure === 'string')
   }
+  // No response and no error text at all — still in flight when the test ended.
+  function neverFinished(r) {
+    return r.status <= 0 && typeof r.failure !== 'string'
+  }
+  // The request the failing step itself sent: the page's LAST call to the app's own origin (a
+  // click's fetch/xhr), else the document load. It leads the test's line, because the request a
+  // click sent answers "why did nothing change?" — xr-molecule-flash-m135 clicked Follow and sent
+  // a DELETE (its \`following\` state was stale), and the trace held the whole exchange while the
+  // result listed only the test's earlier, answered requests.
+  //
+  // Never a request that is still in flight (no response, no error text): it says nothing about
+  // what came back, and the note has its own honest row for it (m112 +30:45). Never the page
+  // shell's own probe (a refused \`/sw.js\` is not the step's request — m125 +29:33).
+  function leadCandidate(r) {
+    if (r.status <= 0 && typeof r.failure !== 'string') return false
+    if (r.type === 'document') return true
+    if (r.type !== 'fetch' && r.type !== 'xhr') return false
+    // The request the page makes for its own shell is not the step's (m125 +29:33). The recorded
+    // path can be an absolute URL when the probe's origin differs from the document's, so judge
+    // its pathname.
+    var p = r.path
+    try { p = new URL(r.path, 'http://trace.local').pathname } catch (e) { p = String(r.path).split(/[?#]/)[0] }
+    return !shellPath(p)
+  }
+  let leadIndex = -1
+  for (let i = requests.length - 1; i >= 0; i--) {
+    const r = requests[i]
+    if ((r.type === 'fetch' || r.type === 'xhr') && leadCandidate(r)) { leadIndex = i; break }
+  }
+  if (leadIndex === -1) {
+    for (let i = requests.length - 1; i >= 0; i--) {
+      if (requests[i].type === 'document' && leadCandidate(requests[i])) { leadIndex = i; break }
+    }
+  }
+  let lead = null
+  if (leadIndex !== -1) {
+    const r = requests[leadIndex]
+    const sent = bodyText(buf, entries, r.postData, MAX_BODY)
+    const got = bodyText(buf, entries, r.content, MAX_BODY)
+    lead = {
+      method: r.method,
+      path: r.path,
+      status: r.status,
+      failure: r.failure,
+      type: r.type || undefined,
+      ...(sent ? { sent: sent } : {}),
+      ...(got ? { got: got } : {}),
+    }
+  }
   const failing = []
   const api = []
+  const pending = []
   const rest = []
   for (let i = 0; i < requests.length; i++) {
     const r = requests[i]
     // An answered/aborted shell request is no evidence at all — do not spend a kept row on it.
-    if (shellRequest(r) && !failedRequest(r)) continue
+    // The exception is a document subresource that never finished while the navigation was
+    // still open: that IS what the timeout waited on.
+    if (shellRequest(r) && !failedRequest(r) && !(navigationOpen && neverFinished(r) && !incidentalShell(r))) continue
     if (failedRequest(r)) failing.push(i)
     else if (r.type === 'fetch' || r.type === 'xhr' || r.type === 'document') api.push(i)
+    else if (navigationOpen && neverFinished(r)) pending.push(i)
     else rest.push(i)
   }
-  const keep = failing.slice(-MAX_REQUESTS).concat(api.slice(-MAX_REQUESTS)).concat(rest.slice(-2))
+  const keep = failing.slice(-MAX_REQUESTS).concat(api.slice(-MAX_REQUESTS))
+    .concat(pending.slice(-MAX_REQUESTS)).concat(rest.slice(-2))
   const chosen = []
   const seen = new Set()
   for (const i of keep.sort(function (a, b) {
@@ -297,25 +392,6 @@ for (const one of found.slice(0, MAX_TRACES)) {
       type: r.type || undefined,
     })
   }
-  // The page's own actions, timed. before/after pair on the call id, and only the LIBRARY
-  // traces carry a class and a method (Frame.goto, Locator.fill); the test runner's own
-  // trace times its hooks and fixtures with class Test, which is not a page action.
-  const ended = {}
-  for (const entry of trace) {
-    if (entry && entry.type === 'after' && typeof entry.callId === 'string' && typeof entry.endTime === 'number')
-      ended[entry.callId] = entry.endTime
-  }
-  const actions = []
-  for (const entry of trace) {
-    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
-    actions.push({
-      api: entry.class + '.' + entry.method,
-      start: entry.startTime,
-      end: typeof ended[entry.callId] === 'number' ? ended[entry.callId] : null,
-    })
-  }
   const consoleErrors = []
   let spec = null
   let line = 0
@@ -343,6 +419,7 @@ for (const one of found.slice(0, MAX_TRACES)) {
     dir: path.relative(ROOT, path.dirname(one.file)),
     spec: spec,
     line: line,
+    lead: lead,
     // Failures first, per the sort above; the keep-window is the HEAD of that order. Taking the
     // 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).
@@ -352,6 +429,26 @@ for (const one of found.slice(0, MAX_TRACES)) {
   }) + '\\n')
 }
 `;
+/**
+ * One request out of a `TRACE` line's json, or null when the value is not an object.
+ *
+ * @param value - One entry of the line's `requests` array, or its `lead`.
+ * @returns The request, or null.
+ */
+function parseTraceRequest(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const r = value;
+    return {
+        method: String(r.method ?? ''),
+        path: String(r.path ?? ''),
+        status: Number(r.status ?? 0) || 0,
+        ...(typeof r.failure === 'string' && r.failure ? { failure: r.failure } : {}),
+        ...(typeof r.sent === 'string' && r.sent ? { sent: r.sent } : {}),
+        ...(typeof r.got === 'string' && r.got ? { got: r.got } : {}),
+        ...(typeof r.type === 'string' && r.type ? { type: r.type } : {}),
+    };
+}
 /**
  * The traces {@link traceArtifactsScript} printed, parsed.
  *
@@ -371,20 +468,14 @@ export function parseTraceArtifacts(stdout) {
             const requests = Array.isArray(raw.requests) ? raw.requests : [];
             const consoleMessages = Array.isArray(raw.console) ? raw.console : [];
             const actions = Array.isArray(raw.actions) ? raw.actions : [];
+            const lead = parseTraceRequest(raw.lead);
             out.push({
                 spec: typeof raw.spec === 'string' ? raw.spec : null,
                 line: typeof raw.line === 'number' ? raw.line : 0,
                 requests: requests
-                    .filter((r) => typeof r === 'object' && r !== null)
-                    .map((r) => ({
-                    method: String(r.method ?? ''),
-                    path: String(r.path ?? ''),
-                    status: Number(r.status ?? 0) || 0,
-                    ...(typeof r.failure === 'string' && r.failure ? { failure: r.failure } : {}),
-                    ...(typeof r.sent === 'string' && r.sent ? { sent: r.sent } : {}),
-                    ...(typeof r.got === 'string' && r.got ? { got: r.got } : {}),
-                    ...(typeof r.type === 'string' && r.type ? { type: r.type } : {}),
-                })),
+                    .map(parseTraceRequest)
+                    .filter((request) => request !== null),
+                ...(lead === null ? {} : { lead }),
                 console: consoleMessages.map(String),
                 actions: actions
                     .filter((a) => typeof a === 'object' && a !== null)
@@ -445,6 +536,31 @@ function requestLine(request) {
         : '';
     return `${head}${sent}${got}`;
 }
+/**
+ * The failing step's own request as the note writes it first: `the failing step sent DELETE
+ * /api/profiles/x/follow → 200 got {"profile":{…}}`.
+ *
+ * It prints the response body whatever the status — an ANSWERED request is the point: m135's
+ * Follow click sent the DELETE an unfollow sends, got a 200 and a profile with `following: false`,
+ * and nothing in the result said which verb the click used.
+ *
+ * @param request - The trace's `lead` request.
+ * @returns The clause the test's row opens with.
+ */
+function leadRequestLine(request) {
+    const status = request.status > 0
+        ? String(request.status)
+        : request.failure
+            ? `no response (${bodyLine(redactSecrets(request.failure), TRACE_NOTE_FAILURE_CHARS)})`
+            : 'no response';
+    const sent = request.sent
+        ? ` sent ${bodyLine(redactSecrets(request.sent), TRACE_NOTE_SENT_CHARS)}`
+        : '';
+    const got = request.got
+        ? ` got ${bodyLine(redactSecrets(request.got), TRACE_NOTE_LEAD_GOT_CHARS)}`
+        : '';
+    return `the failing step sent ${requestLabel(request)} → ${status}${sent}${got}`;
+}
 /** Whether a sent body is an object whose only top-level key is `data` — the wrapped-body trap. */
 function wrappedInData(text) {
     try {
@@ -534,6 +650,33 @@ export function unansweredRequest(request) {
         return false;
     return request.status <= 0 && request.failure === undefined;
 }
+/**
+ * Whether a trace recorded a DOCUMENT SUBRESOURCE that never finished: a stylesheet, script or
+ * other asset the page itself loads, with no response and no error text — still in flight when
+ * the navigation timed out.
+ *
+ * The page shell's own incidental requests (`/sw.js`, the manifest, a favicon, a font) are
+ * excepted for the reason {@link isStaticAssetRequest} documents: m125's run was sent to write a
+ * caching service worker by an aborted `/sw.js`. A pending `/assets/*.css` is different — the
+ * navigation blocks on it, so it is the reason `page.goto` ran out of time rather than one of the
+ * app's API calls (xr-molecule-flash-m135 +34:10: three deployed `page.goto` timeouts on tests that
+ * pass locally, one 88 KB stylesheet fetch measured at 27 s, and the failing tests' traces each
+ * held the never-answered CSS while the note said "the cause is in the page").
+ *
+ * @param request - One request a trace recorded.
+ * @returns True when the request is a document subresource that never finished.
+ */
+export function stalledDocumentSubresource(request) {
+    if (request.status > 0 || request.failure !== undefined)
+        return false;
+    if (request.type === 'document')
+        return false;
+    if (request.type === 'font' || request.type === 'manifest')
+        return false;
+    if (STATIC_ASSET_PATH.test(requestPath(request)))
+        return false;
+    return isStaticAssetRequest(request);
+}
 /**
  * How far a trace's last recorded step can sit after an earlier walk's failing test and still be
  * that test. The trace names the LINE of the last step it recorded (the click, the wait), while the
@@ -591,14 +734,19 @@ function repeatsEarlierFailure(item, earlier) {
  * hidden in "… and 7 more traced failures".
  *
  * A request the page shell made (m125 +29:33: `/sw.js`, a font) is not evidence about the step
- * either, answered or not.
+ * either, answered or not. The exception is a document subresource that never finished while the
+ * page's own navigation was still open: the navigation waits on it, so it is the reason the
+ * `page.goto` timed out ({@link stalledDocumentSubresource}).
  *
  * @param item - One traced failure.
  * @returns True when the trace holds a request or console error worth a row.
  */
 function traceRowEvidence(item) {
     return (item.console.length > 0 ||
-        item.requests.some((request) => !isStaticAssetRequest(request) && !unansweredRequest(request)));
+        item.requests.some((request) => !isStaticAssetRequest(request) && !unansweredRequest(request)) ||
+        // The one shape in which a subresource with no response IS the cause: the navigation it was
+        // part of never finished (see {@link stalledDocumentSubresource}).
+        (navigationNeverFinished(item) && item.requests.some(stalledDocumentSubresource)));
 }
 /**
  * The note's row order: a row with a REAL failure first, then a row whose failure an earlier walk
@@ -609,6 +757,10 @@ function traceRowEvidence(item) {
 function traceRowTier(item, earlier) {
     if (item.requests.some(failedRequest))
         return 0;
+    // A navigation that never finished because its own subresource never got a response is as
+    // strong a cause as a failed request — it is the one fact the timeout was waiting on (m135).
+    if (navigationNeverFinished(item) && item.requests.some(stalledDocumentSubresource))
+        return 0;
     if (repeatsEarlierFailure(item, earlier))
         return 1;
     return 2;
@@ -658,6 +810,94 @@ function transportFailure(items) {
     }
     return null;
 }
+/**
+ * A request's path when the trace recorded a same-origin path — `/users` — or null for an
+ * absolute URL (another origin's path is no evidence about this app's API).
+ *
+ * @param request - One request a trace recorded.
+ * @returns The path without a query or trailing slash, or null.
+ */
+function sameOriginPath(request) {
+    const raw = String(request.path ?? '').split(/[?#]/)[0] ?? '';
+    if (!raw.startsWith('/') || raw === '/')
+        return null;
+    return raw.replace(/\/+$/, '');
+}
+/**
+ * The API path prefixes the traced requests themselves show.
+ *
+ * A request whose path ends with another traced request's path carries that other path's prefix
+ * (`/api/users` beside `/users` → `/api`) — the trace's own evidence, with no literal in the code.
+ *
+ * @param items - The traces the note is about.
+ * @returns The one-segment prefixes (`/api`), sorted; empty when the traces show none.
+ */
+function tracedApiPrefixes(items) {
+    const paths = items.flatMap((item) => item.requests.map(sameOriginPath).filter((path) => path !== null));
+    const prefixes = new Set();
+    for (const longer of paths) {
+        for (const shorter of paths) {
+            if (longer === shorter || shorter.length < 2 || !longer.endsWith(shorter))
+                continue;
+            const prefix = longer.slice(0, longer.length - shorter.length);
+            if (/^\/[^/]+$/.test(prefix))
+                prefixes.add(prefix);
+        }
+    }
+    return [...prefixes].sort();
+}
+/**
+ * The failed 404s whose path carries none of the known API prefixes.
+ *
+ * Only a run where the prefix is KNOWABLE diagnoses: the caller reads it from the app's client
+ * config, and the traces' own requests add what they show ({@link tracedApiPrefixes}). With no
+ * known prefix, an unprefixed path is just a path — assuming `/api` is how a correct request gets
+ * a wrong note.
+ *
+ * @param items - The traces the note is about.
+ * @param apiPrefixes - Prefixes the app's client config names (`['/api']`), never a literal.
+ * @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)
+        return [];
+    const known = [...prefixes];
+    const out = [];
+    const seen = new Set();
+    for (const item of items) {
+        for (const request of item.requests) {
+            // A document navigation is a page route, never an API call — a 404 on one says nothing
+            // about the client's base URL.
+            if (request.status !== 404 || request.type === 'document' || !failedRequest(request))
+                continue;
+            const path = sameOriginPath(request);
+            if (path === null)
+                continue;
+            if (known.some((prefix) => path === prefix || path.startsWith(`${prefix}/`)))
+                continue;
+            const key = `${request.method} ${path}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ method: request.method, path, prefix: known[0] ?? '' });
+        }
+    }
+    return out;
+}
+/**
+ * The sentence naming a request that reached the page origin without the app's API prefix.
+ *
+ * @param request - The failed request and the prefix its sibling calls carry.
+ * @returns The sentence the note appends.
+ */
+function missingApiPrefixSentence(request) {
+    return (`\`${request.method} ${request.path}\` → 404: this request went to \`${request.path}\` ` +
+        `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 note a failed suite run's result carries: what each failing test's page actually sent, and
  * what came back.
@@ -678,6 +918,12 @@ function transportFailure(items) {
  * line rather than inferred from the status; when one of those bodies is an object whose only key
  * is `data`, the note names the call shape that produces it (xr-molecule-flash-m111 +11:36).
  *
+ * Every row opens with the request the failing step ITSELF sent ({@link TraceArtifact.lead}) and
+ * its response — whatever its status — because the question a `waiting for locator` failure asks
+ * is what the click did: xr-molecule-flash-m135's Follow click sent `DELETE …/follow → 200` (an
+ * unfollow, from a stale `following` state) and the run's result named only the test's earlier
+ * answered requests, so the executor spent 14 minutes on its own browser probes.
+ *
  * 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 error ({@link traceRowEvidence}), rows are
  * deduplicated by the test's location, and they are ordered real failure → repeated from an
@@ -689,14 +935,31 @@ function transportFailure(items) {
  * transport error (`net::ERR_CONTENT_DECODING_FAILED` and friends) and the document it hit: nothing
  * rendered, so no row below is app evidence (xr-molecule-flash-m118 +37:09).
  *
+ * When a navigation never finished and one of the document's own subresources (a stylesheet, a
+ * script, an asset under `/assets/`) never got a response either, that request takes a row and the
+ * note says the page was waiting on it. It is not an API call, but on a `page.goto` timeout it is
+ * the only request that can explain the timeout — the deployed app was serving the page while one
+ * fetch stalled for 27 s (xr-molecule-flash-m135 +34:10). The page shell's incidental requests
+ * (`/sw.js`, the manifest, a favicon, a font) stay out, for m125's reason.
+ *
+ * A 404 whose path lacks the API prefix the app's own calls carry is called out with that prefix
+ * ({@link missingApiPrefixRequests}): xr-molecule-flash-m145 posted `/users` to `vite preview`,
+ * whose 404 was answered by the static server because the HTTP client's `baseURL` was never set —
+ * and the note printed "read the handler this route reaches in your own source", which presumes a
+ * request that never reached the API. The prefix is READ (the caller passes what the app's client
+ * config names; the traces add what their own requests show) and never assumed to be `/api`.
+ *
  * @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
  *   is ranked above a one-off. Empty when the caller knows of no earlier walk.
+ * @param apiPrefixes - The API path prefixes the app's client config names (`['/api']`), read from
+ *   the app by the caller. Empty when the caller could not read one; the traces' own requests may
+ *   still supply it. Never a hard-coded literal.
  * @returns The note, or null when no trace held a recorded response, a real failure or a console
  *   error.
  */
-export function failureTraceNote(items, target, earlierFailures = []) {
+export function failureTraceNote(items, target, earlierFailures = [], apiPrefixes = []) {
     const candidates = items.filter(traceRowEvidence);
     if (candidates.length === 0)
         return null;
@@ -720,21 +983,68 @@ export function failureTraceNote(items, target, earlierFailures = []) {
     const wrapped = traced.some((item) => item.requests.some((request) => request.sent !== undefined && wrappedInData(request.sent)));
     // The "one of these requests failing" answer is only honest when a listed request really failed.
     const anyFailed = traced.some((item) => item.requests.some(failedRequest));
+    // m145's shape: the app's HTTP client lost its base URL, so every API call reached the page
+    // origin without the prefix the app mounts its routes under. The prefix is READ — the caller's
+    // client config plus what the traces show — never assumed to be `/api`.
+    const missingPrefix = missingApiPrefixRequests(traced, apiPrefixes);
+    const failedRequests = traced.flatMap((item) => item.requests.filter(failedRequest));
+    const missingKeys = new Set(missingPrefix.map((request) => `${request.method} ${request.path}`));
+    const everyFailureLacksPrefix = failedRequests.length > 0 &&
+        failedRequests.every((request) => {
+            const path = sameOriginPath(request);
+            return path !== null && missingKeys.has(`${request.method} ${path}`);
+        });
+    // The route advice goes when every failure is one of these: a request that never reached the
+    // API has no handler to read (m145's note sent the run to the PWA and then to the handler).
+    const prefixAdvice = missingPrefix.length > 0
+        ? ` ${missingPrefix.slice(0, 2).map(missingApiPrefixSentence).join(' ')}`
+        : '';
+    // The document subresources that never finished anywhere in this read — the assets a timed-out
+    // navigation was waiting on, when there is no failed request to explain the timeout.
+    const stalledAssets = [
+        ...new Set(traced
+            .filter(navigationNeverFinished)
+            .flatMap((item) => item.requests.filter(stalledDocumentSubresource))
+            .map(requestLabel)),
+    ];
     const rows = [];
     for (const [index, item] of traced.entries()) {
+        // The request the failing step itself sent LEADS the row (m135): a click that changed nothing
+        // is answered by the request it sent and what came back, whether or not that request failed.
+        // It is not repeated in the buckets below.
+        const lead = item.lead;
+        const isLead = (request) => lead !== undefined &&
+            request.method === lead.method &&
+            request.path === lead.path &&
+            request.status === lead.status;
         // The page shell's own requests take no row, in any bucket: an aborted `/sw.js` would
         // otherwise be printed as an "answered" request with no response (m125 +29:33).
-        const requests = item.requests.filter((request) => !isStaticAssetRequest(request));
+        const requests = item.requests.filter((request) => !isStaticAssetRequest(request) && !isLead(request));
         const failed = requests.filter(failedRequest);
         const unanswered = requests.filter(unansweredRequest);
         const answered = requests.filter((request) => !failedRequest(request) && !unansweredRequest(request));
+        // A document subresource that never finished, on a trace whose navigation never finished:
+        // the page was waiting on it when the test's budget ran out (m135).
+        const stalled = navigationNeverFinished(item)
+            ? item.requests.filter(stalledDocumentSubresource)
+            : [];
         let room = MAX_TRACE_NOTE_REQUESTS;
         const parts = [];
+        if (lead !== undefined) {
+            parts.push(leadRequestLine(lead));
+            room -= 1;
+        }
         if (failed.length > 0) {
             const shown = failed.slice(0, room);
             room -= shown.length;
             parts.push(`failed: ${shown.map(requestLine).join('; ')}`);
         }
+        if (stalled.length > 0 && room > 0) {
+            const shown = stalled.slice(0, room);
+            room -= shown.length;
+            parts.push(`never finished: ${shown.map(requestLabel).join('; ')} — a document subresource with no ` +
+                'response, still in flight when the navigation timed out');
+        }
         if (unanswered.length > 0 && room > 0) {
             const shown = unanswered.slice(0, room);
             room -= shown.length;
@@ -775,17 +1085,45 @@ export function failureTraceNote(items, target, earlierFailures = []) {
                     '`MOL_E2E_PREVIEW_PLUGIN=0 npx vite preview --host 127.0.0.1 --port 4173 --strictPort`. '
                 : '') +
             'Fix the server before the app.\n\n';
+    // A navigation that never finished WITH a subresource that never got a response, and no
+    // transport error: the page was waiting on the asset when the budget ran out. That is the host
+    // or the network serving that file, not the app's state — say it before any app-side reading
+    // (xr-molecule-flash-m135 +34:10: three deployed goto timeouts on tests passing locally in
+    // 1.2-5.6 s, one 88 KB stylesheet fetch measured at 27 s, and the note said "the cause is in
+    // the page").
+    const stalledLead = transport !== null || stalledAssets.length === 0
+        ? ''
+        : `Every failure this run traced is a \`page.goto\` that never finished, and the document's ` +
+            `own ${stalledAssets.length === 1 ? 'subresource' : 'subresources'} ${stalledAssets.join(', ')} ` +
+            `never got a response — the navigation was waiting on ${stalledAssets.length === 1 ? 'it' : 'them'} ` +
+            `when the test's budget ran out. That is the host or the network serving the asset, not the ` +
+            `app's state or a selector: re-run the same tests once, unchanged, against ${target} before ` +
+            `editing anything, and if the stall repeats measure that exact fetch ` +
+            `(\`curl -o /dev/null -w '%{time_starttransfer} %{time_total}' <url>\`) before treating it as ` +
+            `the app's.\n\n`;
     return (transportLead +
+        stalledLead +
         `The platform read the failing tests' own Playwright traces from the run against ${target} ` +
-        `(what each page sent and got: the requests that failed, the ones that got no response, and ` +
-        `its last answered ones):\n` +
+        `(what each page sent and got — first the request the failing step itself sent, then the ` +
+        `requests that failed, the ones that got no response, and its last answered ones):\n` +
         `${rows.join('\n')}${more}\n` +
         (anyFailed
-            ? 'A click that changed nothing is usually one of these requests failing, not the selector: ' +
-                'read the handler this route reaches in your own source, and stop `catch`-ing the request of a ' +
-                'user action silently — log it.'
-            : 'No listed request failed — none got a 4xx/5xx or a network error — so the cause is in the ' +
-                'page, not the API: read the state the failing test waited on.') +
+            ? everyFailureLacksPrefix
+                ? ''
+                : 'A click that changed nothing is usually one of these requests failing, not the selector: ' +
+                    'read the handler this route reaches in your own source, and stop `catch`-ing the request of a ' +
+                    'user action silently — log it.'
+            : stalledAssets.length > 0
+                ? 'No listed request failed — none got a 4xx/5xx or a network error — but the document did ' +
+                    'not finish loading because its own subresource never answered. Do not read this as a ' +
+                    'page-state bug: re-run these tests against the same URL first, and change the app only ' +
+                    'if the same navigation times out again with no stalled asset in the trace.'
+                : 'No listed request failed — none got a 4xx/5xx or a network error — so the cause is in the ' +
+                    'page, not the API. Start with the request the failing step sent (the first line of each ' +
+                    'row): if it is not the request the test meant — an unfollow sent where the test clicked ' +
+                    'follow — the state the click read was stale before it. Otherwise read the state the ' +
+                    'failing test waited on.') +
+        prefixAdvice +
         (wrapped
             ? ' The API received a body wrapped in `data`: app-http’s `post(url, data, config)` / ' +
                 '`put(url, data, config)` / `patch(url, data, config)` take the body as their SECOND ' +