@molecule/api-ai-tools 1.9.11 → 1.9.13

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-18T07:24:21.171Z
+Generated: 2026-10-18T09:17:15.122Z
 -->
 
 # @molecule/api-ai-tools
@@ -404,6 +404,28 @@ interface TraceRequest {
    * fixture), in which case only recording order is available.
    */
   startedAt?: number
+  /**
+   * Whether the request carried an `Authorization` header at all. Its VALUE is never recorded.
+   *
+   * A 401 cannot be read without this: the API's own body said
+   * `{"errors":{"token":["is missing"]}}` while the note told the run to read the API handler,
+   * when the header's absence proved the CLIENT never attached the token
+   * (xr-molecule-flash-m148 +29:18). A header present moves the answer to the server: the API
+   * refused a token it was sent.
+   */
+  sentAuthorization?: boolean
+  /**
+   * The scheme WORD of an `Authorization` header (`Bearer`, `Token`), or undefined when there is
+   * no header or its first word does not parse as a scheme (a value pasted without one is a
+   * credential, and is never copied here).
+   */
+  authorization?: string
+  /**
+   * Whether the request carried a `Cookie` header — never the cookies themselves. An app that
+   * signs in with a session cookie has no `Authorization` header by design, so this tells a
+   * credential-less request from one whose credential is a cookie.
+   */
+  sentCookie?: boolean
 }
 ```
 
@@ -500,6 +522,52 @@ interface TraceArtifact {
 }
 ```
 
+#### `TraceRunFailure`
+
+What the runner's own report says about ONE failing test: where the test is declared, which
+Playwright call its failure names, and the per-test deadline the failure measured against.
+
+A trace cannot tell a navigation that ran out of budget from a selector wait that did. On
+xr-molecule-flash-m153 a 15 s `page.waitForSelector` timeout left a trace whose `Frame.goto`
+never finished (the test was cut off mid-navigation) with a `/src/components/*.tsx` module still
+pending when the context closed — and the note read that as an asset hang, then sent the run to
+re-run the same tests unchanged against the same dev server while the same result's
+`testRunNote` was telling it to measure a production build.
+
+```typescript
+interface TraceRunFailure {
+  /** The spec file the runner's heading names (`e2e/url-navigation.spec.ts`). */
+  spec: string
+  /** The line the test is DECLARED on, from that heading (`206`). */
+  line: number
+  /** The Playwright call the failure names (`page.waitForSelector`, `page.goto`), or null. */
+  operation: string | null
+  /** The per-test deadline the failure names, in ms (`15000`), or null when it names none. */
+  budgetMs: number | null
+}
+```
+
+#### `TraceRunReport`
+
+The runner's own report, beside the traces it wrote.
+
+```typescript
+interface TraceRunReport {
+  /**
+   * One entry per failing test, as the runner printed them. Empty when the caller supplied none:
+   * without the runner's reported operation a pending asset is never called the cause.
+   */
+  failures?: readonly TraceRunFailure[]
+  /**
+   * True when the same result's `testRunNote` already names a production build as the next
+   * measurement (a local dev-server walk that ran out of its per-test budget). The note then
+   * states the ONE next step instead of directing an unchanged same-target re-run that
+   * contradicts it.
+   */
+  productionBuildAdvised?: boolean
+}
+```
+
 #### `DiagnosisTraceRewrite`
 
 A command with the trace flag this platform decided to add, and the sentence to report it in.
@@ -1931,7 +1999,7 @@ function stalledDocumentSubresource(request: TraceRequest): boolean
 
 **Returns:** True when the request is a document subresource that never finished.
 
-#### `failureTraceNote(items, target, earlierFailures, apiPrefixes)`
+#### `failureTraceNote(items, target, earlierFailures, apiPrefixes, report)`
 
 The note a failed suite run's result carries: what each failing test's page actually sent, and
 what came back.
@@ -1963,6 +2031,7 @@ function failureTraceNote(
   target: string,
   earlierFailures?: readonly string[],
   apiPrefixes?: readonly string[],
+  report?: TraceRunReport,
 ): string | null
 ```
 
@@ -1970,6 +2039,7 @@ function failureTraceNote(
 - `target` — Where the run went — the deployed host, as the note names it.
 - `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.
 - `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.
+- `report` — The runner's own report for this run ({@link TraceRunReport}): each failing test's declared location, the operation its failure names and the deadline it names, plus whether the same result's `testRunNote` already points at a production build. A pending asset is called the cause only when the runner says the failing operation for THAT test is the navigation it was loading; without the report nothing is called a navigation stall.
 
 **Returns:** The note, or null when no trace held a recorded response, a real failure or a console error.
 

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAkJ9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAkOD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAsEnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AAmBlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AA2GD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAu/ExF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAkJ9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAkOD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAsEnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AAmBlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AA2GD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAokFxF"}

package/dist/tools.js

@@ -849,6 +849,65 @@ export function buildTools(backend, config) {
             result = isEnvFilePath(path) ? redactSecrets(result) : redactSecretsInCode(result);
         return result;
     }
+    // ── Binary reads ───────────────────────────────────────────────
+    /** Extensions whose files are never text: a `read_file` on one is refused by name. */
+    const BINARY_FILE_EXTENSIONS = new Set([
+        'avif',
+        'gif',
+        'gz',
+        'ico',
+        'jpeg',
+        'jpg',
+        'otf',
+        'pdf',
+        'png',
+        'tgz',
+        'ttf',
+        'wasm',
+        'webp',
+        'woff',
+        'woff2',
+        'zip',
+    ]);
+    /** How many chars of a read are inspected for binary markers. */
+    const BINARY_SAMPLE_CHARS = 512;
+    /**
+     * A replacement character (a byte UTF-8 could not decode) marks binary only in
+     * bulk: one literal U+FFFD in a source string is ordinary text.
+     */
+    const BINARY_MIN_REPLACEMENTS = 8;
+    const BINARY_REPLACEMENT_DENSITY = 0.05;
+    /**
+     * The kind of a BINARY file, or `null` for text.
+     *
+     * `read_file` asks the backend for a string, so a PNG comes back as UTF-8
+     * replacement characters and used to be handed to the model whole — 21,191
+     * chars of unreadable bytes it cannot look at, ~12k tokens per read, asked for
+     * twice in one run (xr-molecule-flash-m155 +09:58). A known binary extension is
+     * refused by name; a file without one is caught from the bytes themselves, by
+     * a NUL byte or by the density of replacement characters in its first
+     * {@link BINARY_SAMPLE_CHARS} chars.
+     *
+     * @param path - The already-resolved path.
+     * @param content - The content the backend decoded as UTF-8.
+     * @returns The binary kind to name (e.g. `png`, `binary data`), or `null` for text.
+     */
+    function binaryFileKind(path, content) {
+        const ext = posix.extname(path).slice(1).toLowerCase();
+        if (BINARY_FILE_EXTENSIONS.has(ext))
+            return ext;
+        const sample = content.slice(0, BINARY_SAMPLE_CHARS);
+        if (sample.includes('\u0000'))
+            return 'binary data';
+        let replacements = 0;
+        for (const char of sample)
+            if (char === '\uFFFD')
+                replacements += 1;
+        return replacements >= BINARY_MIN_REPLACEMENTS &&
+            replacements / sample.length >= BINARY_REPLACEMENT_DENSITY
+            ? 'binary data'
+            : null;
+    }
     // ── Empty-read verification ────────────────────────────────────
     /**
      * The file's size in bytes as the backend's own shell reports it, or `null`
@@ -1022,6 +1081,19 @@ export function buildTools(backend, config) {
                     ...(verdict.note ? { note: verdict.note } : {}),
                 });
             }
+            // A binary file decoded as UTF-8 is unreadable by definition — say what it
+            // is instead of returning the bytes (see binaryFileKind).
+            const binaryKind = binaryFileKind(path, content);
+            if (binaryKind) {
+                // The read already happened, so the decoded length is the fallback size;
+                // `wc -c` gives the file's real byte count when the backend can run it.
+                const bytes = (await probeFileSize(path)) ?? content.length;
+                return {
+                    error: `${path} is a binary file (${binaryKind}, ${Math.max(1, Math.round(bytes / 1024))} KB). ` +
+                        `read_file returns text only — to look at a page use screenshot_preview; to inspect an ` +
+                        `image you produced, measure it in a script and print the numbers (its size, pixel counts).`,
+                };
+            }
             if (content.length > MAX_READ_SIZE)
                 return {
                     error: `File too large (${Math.round(content.length / 1024)}KB). Maximum is ${MAX_READ_SIZE / 1024 / 1024}MB.`,
@@ -2911,8 +2983,13 @@ export function buildTools(backend, config) {
                 : { piped: false, unplaced: false };
             const reported = suiteRunExitCode(exitCode, output, placement.piped);
             const noCodeNote = suiteExitCodeNote(placement, reported);
+            // A FINISHED result says so, even when the code it would report is withheld: a filtered
+            // pipeline's code is not the run's verdict ({@link FILTERED_EXIT_NOTE}), so `exitCode` alone
+            // cannot tell a caller this is the delivered result rather than a progress return — and a
+            // caller that tracks background tasks would hand the same result back as fresh news later.
             return {
                 taskId,
+                status: 'completed',
                 exitCode: reported,
                 waitedMs,
                 ...(causes || noCodeNote

package/dist/trace-artifacts.d.ts

@@ -67,6 +67,28 @@ export interface TraceRequest {
      * fixture), in which case only recording order is available.
      */
     startedAt?: number;
+    /**
+     * Whether the request carried an `Authorization` header at all. Its VALUE is never recorded.
+     *
+     * A 401 cannot be read without this: the API's own body said
+     * `{"errors":{"token":["is missing"]}}` while the note told the run to read the API handler,
+     * when the header's absence proved the CLIENT never attached the token
+     * (xr-molecule-flash-m148 +29:18). A header present moves the answer to the server: the API
+     * refused a token it was sent.
+     */
+    sentAuthorization?: boolean;
+    /**
+     * The scheme WORD of an `Authorization` header (`Bearer`, `Token`), or undefined when there is
+     * no header or its first word does not parse as a scheme (a value pasted without one is a
+     * credential, and is never copied here).
+     */
+    authorization?: string;
+    /**
+     * Whether the request carried a `Cookie` header — never the cookies themselves. An app that
+     * signs in with a session cookie has no `Authorization` header by design, so this tells a
+     * credential-less request from one whose credential is a cookie.
+     */
+    sentCookie?: boolean;
 }
 /**
  * The test's LAST user action before the failing assertion, and the requests it caused.
@@ -257,6 +279,42 @@ export declare function unansweredRequest(request: TraceRequest): boolean;
  * @returns True when the request is a document subresource that never finished.
  */
 export declare function stalledDocumentSubresource(request: TraceRequest): boolean;
+/**
+ * What the runner's own report says about ONE failing test: where the test is declared, which
+ * Playwright call its failure names, and the per-test deadline the failure measured against.
+ *
+ * A trace cannot tell a navigation that ran out of budget from a selector wait that did. On
+ * xr-molecule-flash-m153 a 15 s `page.waitForSelector` timeout left a trace whose `Frame.goto`
+ * never finished (the test was cut off mid-navigation) with a `/src/components/*.tsx` module still
+ * pending when the context closed — and the note read that as an asset hang, then sent the run to
+ * re-run the same tests unchanged against the same dev server while the same result's
+ * `testRunNote` was telling it to measure a production build.
+ */
+export interface TraceRunFailure {
+    /** The spec file the runner's heading names (`e2e/url-navigation.spec.ts`). */
+    spec: string;
+    /** The line the test is DECLARED on, from that heading (`206`). */
+    line: number;
+    /** The Playwright call the failure names (`page.waitForSelector`, `page.goto`), or null. */
+    operation: string | null;
+    /** The per-test deadline the failure names, in ms (`15000`), or null when it names none. */
+    budgetMs: number | null;
+}
+/** The runner's own report, beside the traces it wrote. */
+export interface TraceRunReport {
+    /**
+     * One entry per failing test, as the runner printed them. Empty when the caller supplied none:
+     * without the runner's reported operation a pending asset is never called the cause.
+     */
+    failures?: readonly TraceRunFailure[];
+    /**
+     * True when the same result's `testRunNote` already names a production build as the next
+     * measurement (a local dev-server walk that ran out of its per-test budget). The note then
+     * states the ONE next step instead of directing an unchanged same-target re-run that
+     * contradicts it.
+     */
+    productionBuildAdvised?: boolean;
+}
 /**
  * The note a failed suite run's result carries: what each failing test's page actually sent, and
  * what came back.
@@ -299,12 +357,16 @@ export declare function stalledDocumentSubresource(request: TraceRequest): boole
  * 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.
+ * When a navigation the runner reports as the failure never finished and one of the document's
+ * own subresources (a stylesheet, a script, an asset under `/assets/`) never got a response either
+ * — having started inside that wait — the 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. An asset merely unfinished when a selector wait
+ * ran out the test budget, or one a teardown/`afterEach` trace holds, is not a cause: the note
+ * says it "had no recorded response when the test ended; that alone does not establish the cause"
+ * (xr-molecule-flash-m153 +13:43).
  *
  * 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`,
@@ -313,6 +375,15 @@ export declare function stalledDocumentSubresource(request: TraceRequest): boole
  * 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`.
  *
+ * A 401/403 on the app's own origin is answered from the request's own credential record instead
+ * ({@link authRefusalSentence}): no `Authorization` header means the CLIENT never attached the
+ * token (the shared HTTP client's `setAuthToken` is what the auth bond mirrors it into), while a
+ * header the API then refused moves the answer to the server. The handler sentence is kept for
+ * the rest — 404/422/500 — and dropped when every failure was a credential refusal, because a
+ * trace that proves the header was never sent cannot be explained by the handler.
+ * xr-molecule-flash-m148 (+29:18) hit this exactly: six local walks read
+ * `POST …/favorite → 401 {"errors":{"token":["is missing"]}}` as a handler bug.
+ *
  * @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
@@ -320,10 +391,15 @@ export declare function stalledDocumentSubresource(request: TraceRequest): boole
  * @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.
+ * @param report - The runner's own report for this run ({@link TraceRunReport}): each failing
+ *   test's declared location, the operation its failure names and the deadline it names, plus
+ *   whether the same result's `testRunNote` already points at a production build. A pending asset
+ *   is called the cause only when the runner says the failing operation for THAT test is the
+ *   navigation it was loading; without the report nothing is called a navigation stall.
  * @returns The note, or null when no trace held a recorded response, a real failure or a console
  *   error.
  */
-export declare function failureTraceNote(items: readonly TraceArtifact[], target: string, earlierFailures?: readonly string[], apiPrefixes?: readonly string[]): string | null;
+export declare function failureTraceNote(items: readonly TraceArtifact[], target: string, earlierFailures?: readonly string[], apiPrefixes?: readonly string[], report?: TraceRunReport): string | null;
 /**
  * Whether a Playwright config records traces for the tests that fail.
  *

package/dist/trace-artifacts.d.ts.map

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

package/dist/trace-artifacts.js

@@ -243,12 +243,34 @@ for (const one of found.slice(0, MAX_TRACES)) {
     const response = snapshot.response || {}
     const type = String(snapshot._resourceType || '')
     if (!origin) origin = type === 'document' ? originOf(String(request.url)) : ''
+    // What the request carried for CREDENTIALS — never the secret itself. A 401 on the app's own
+    // API cannot be read without this: m148's favorite POST answered 401 with no Authorization
+    // header at all, so the client never attached the token, and the note sent the run to the
+    // API handler instead (xr-molecule-flash-m148 +29:18). Presence is recorded as a boolean and
+    // only the scheme WORD (\`Bearer\`, \`Token\`) is kept; the value is a live credential and never
+    // leaves the trace. A first word that does not parse as a scheme (\`Authorization: <raw jwt>\`)
+    // is recorded as presence only, so a pasted token can never ride along as a "scheme".
+    const headerList = Array.isArray(request.headers) ? request.headers : []
+    const authHeader = headerList.find(function (h) {
+      return h && typeof h.name === 'string' && /^authorization$/i.test(h.name)
+    })
+    const authValue =
+      authHeader && typeof authHeader.value === 'string' ? String(authHeader.value).trim() : ''
+    const authSpace = authValue.search(/\\s/)
+    const authWord = authSpace > 0 ? authValue.slice(0, authSpace) : ''
+    const authScheme = /^[A-Za-z][A-Za-z0-9._~+/-]{0,23}$/.test(authWord) ? authWord : undefined
+    const sentCookie = headerList.some(function (h) {
+      return h && typeof h.name === 'string' && /^cookie$/i.test(h.name)
+    })
     requests.push({
       method: String(request.method).toUpperCase(),
       path: String(request.url).slice(0, MAX_URL),
       status: Number(response.status) || 0,
       failure: typeof response._failureText === 'string' ? response._failureText : undefined,
       type: type,
+      sentAuthorization: authHeader !== undefined,
+      authorization: authScheme,
+      sentCookie: sentCookie,
       // The HAR entry carries the monotonic clock the trace's action entries use, so a request
       // can be attributed to the action that caused it (see \`lastAction\` below).
       startedAt: typeof snapshot._monotonicTime === 'number' ? snapshot._monotonicTime : undefined,
@@ -430,6 +452,12 @@ for (const one of found.slice(0, MAX_TRACES)) {
       ...(r.sent ? { sent: r.sent } : {}),
       ...(r.got ? { got: r.got } : {}),
       type: r.type || undefined,
+      // The trace's own clock, so the note can tell a request the navigation was waiting on from
+      // one that was already pending before it started (m135/m153).
+      ...(typeof r.startedAt === 'number' ? { startedAt: r.startedAt } : {}),
+      ...(r.sentAuthorization ? { sentAuthorization: true } : {}),
+      ...(r.authorization ? { authorization: r.authorization } : {}),
+      ...(r.sentCookie ? { sentCookie: true } : {}),
     }
   }
   // The main frame's URL, timed: what the page showed when the action ran, and where it ended up.
@@ -590,6 +618,12 @@ function parseTraceRequest(value) {
         ...(typeof r.got === 'string' && r.got ? { got: r.got } : {}),
         ...(typeof r.type === 'string' && r.type ? { type: r.type } : {}),
         ...(Number.isFinite(Number(r.startedAt)) ? { startedAt: Number(r.startedAt) } : {}),
+        // The scheme word only: a raw header value is a live credential and is never parsed in.
+        ...(r.sentAuthorization === true ? { sentAuthorization: true } : {}),
+        ...(typeof r.authorization === 'string' && r.authorization
+            ? { authorization: r.authorization }
+            : {}),
+        ...(r.sentCookie === true ? { sentCookie: true } : {}),
     };
 }
 /**
@@ -934,6 +968,97 @@ function repeatsEarlierFailure(item, earlier) {
     }
     return false;
 }
+/** The Playwright navigation calls whose wait a pending document subresource can explain. */
+const NAVIGATION_OPERATIONS = new Set(['goto', 'waitForURL', 'waitForLoadState', 'reload']);
+/**
+ * The method a runner-reported operation names (`page.waitForSelector` → `waitForSelector`), or
+ * null when it is not one of the navigation calls a stalled asset can explain.
+ *
+ * @param operation - The call the runner's error text names, or null.
+ * @returns The navigation method, or null.
+ */
+function navigationMethod(operation) {
+    if (operation === null)
+        return null;
+    const method = operation.slice(operation.lastIndexOf('.') + 1);
+    return NAVIGATION_OPERATIONS.has(method) ? method : null;
+}
+/**
+ * The runner's report for the test THIS trace belongs to, or undefined when it belongs to none.
+ *
+ * The trace names the line of its LAST recorded step; the runner's summary names the test's
+ * DECLARATION line, and the step sits inside the body just after it ({@link
+ * RECURRENCE_LINE_WINDOW}). A line BEFORE the declaration is a hook — m153's teardown trace sits
+ * at `url-navigation.spec.ts:107`, the Pagination suite's `afterEach`, while the failing test is
+ * declared at `:206` — and a hook is not the failing test's operation.
+ *
+ * @param item - One traced failure.
+ * @param failures - The runner's report, one entry per failing test.
+ * @returns The matching failure, or undefined.
+ */
+function runFailureOf(item, failures) {
+    if (item.spec === null)
+        return undefined;
+    for (const failure of failures) {
+        if (!sameLocationFile(item.spec, failure.spec))
+            continue;
+        if (item.line < failure.line)
+            continue;
+        if (item.line - failure.line <= RECURRENCE_LINE_WINDOW)
+            return failure;
+    }
+    return undefined;
+}
+/**
+ * Whether a pending request's interval covers a navigation's wait: it started while the
+ * navigation was loading (at or after the wait began) and it has no recorded response, so it was
+ * still pending when the wait ran out. A request that started before the wait belongs to the page
+ * already on screen, not to the navigation that never finished.
+ *
+ * @param request - One request the trace recorded.
+ * @param wait - The navigation action the runner reported.
+ * @returns True when the request's pending interval covers the wait.
+ */
+function requestCoversWait(request, wait) {
+    if (typeof request.startedAt !== 'number')
+        return false;
+    return request.startedAt >= wait.start - 1;
+}
+/**
+ * The stalled-navigation reading for one trace — or null.
+ *
+ * All three facts must hold together: the runner says THIS test's failing operation is a
+ * navigation ({@link NAVIGATION_OPERATIONS}); the trace's record of that call never finished; and
+ * a document subresource still pending at the end started inside that wait
+ * ({@link requestCoversWait}). An asset merely unfinished when the test was cancelled, or one a
+ * teardown/`afterEach` trace holds, meets none of these and is not a cause (m153).
+ *
+ * @param item - One traced failure.
+ * @param report - The runner's report and the run's next step.
+ * @returns The wait and the assets it was waiting on, or null.
+ */
+function stalledNavigation(item, report) {
+    const failure = runFailureOf(item, report.failures ?? []);
+    if (failure === undefined)
+        return null;
+    const method = navigationMethod(failure.operation);
+    if (method === null)
+        return null;
+    let wait = null;
+    for (const action of item.actions) {
+        if (!action.api.endsWith(`.${method}`))
+            continue;
+        if (wait === null || action.start > wait.start)
+            wait = action;
+    }
+    // The navigation is the failure only while it is still running at the end of the test.
+    if (wait === null || wait.end !== null)
+        return null;
+    const assets = item.requests.filter((request) => stalledDocumentSubresource(request) && requestCoversWait(request, wait));
+    if (assets.length === 0)
+        return null;
+    return { reported: failure.operation ?? wait.api, wait, assets, budgetMs: failure.budgetMs };
+}
 /**
  * Whether a trace holds evidence the note can explain: a request that got a RECORDED response, a
  * real failure (4xx/5xx or a network error), or a console line. A request with no response is
@@ -943,31 +1068,38 @@ function repeatsEarlierFailure(item, earlier) {
  *
  * A request the page shell made (m125 +29:33: `/sw.js`, a font) is not evidence about the step
  * 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}).
+ * navigation the RUNNER reports failing was still open: that navigation waits on it, so it is the
+ * reason the `page.goto` timed out ({@link stalledNavigation}).
  *
  * @param item - One traced failure.
+ * @param report - The runner's report and the run's next step.
  * @returns True when the trace holds a request or console line worth a row.
  */
-function traceRowEvidence(item) {
+function traceRowEvidence(item, report) {
     return (item.console.length > 0 ||
         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 one shape in which a subresource with no response IS the cause: the navigation the
+        // runner reported was still running at the end (see {@link stalledNavigation}).
+        stalledNavigation(item, report) !== null);
 }
 /**
  * The note's row order: a row with a REAL failure first, then a row whose failure an earlier walk
  * also had, then the rest. A recurrence is the only evidence a row carries when its requests were
  * all answered (m112's favorite cause: the click's own request answered, the button never
  * changed).
+ *
+ * @param item - One traced failure.
+ * @param earlier - The failing `file:line`s earlier walks of this suite left.
+ * @param report - The runner's report and the run's next step.
+ * @returns The row's tier: 0 first, 2 last.
  */
-function traceRowTier(item, earlier) {
+function traceRowTier(item, earlier, report) {
     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))
+    // A navigation the runner reported, still waiting on a subresource that 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 (stalledNavigation(item, report) !== null)
         return 0;
     if (repeatsEarlierFailure(item, earlier))
         return 1;
@@ -1031,6 +1163,94 @@ function sameOriginPath(request) {
         return null;
     return raw.replace(/\/+$/, '');
 }
+/**
+ * The sentence a 401/403 on the app's own API gets: which half of the wire refused the request.
+ *
+ * A fixed "read the handler this route reaches" line is the wrong half for a credential refusal.
+ * The request's own `Authorization` header — recorded by the trace reader as its scheme WORD, never
+ * its value — decides: absent means the CLIENT never attached the token (a session store that the
+ * HTTP client does not read, a bare `fetch`, an auth bond the app replaced), while present means
+ * the SERVER refused a token it was sent (scheme or issuer). A 403 is a permission answer, not a
+ * credential one, and says so.
+ *
+ * xr-molecule-flash-m148 (+29:18): `POST /api/articles/…/favorite → 401 {"errors":{"token":["is
+ * missing"]}}` was answered with the handler sentence for six local walks, while the trace proved
+ * the request carried no `Authorization` header at all and the app's hand-rolled session store
+ * never handed its token to the shared client.
+ *
+ * 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.
+ *
+ * @param request - The refused request, a 401 or 403 on the app's own origin.
+ * @returns The sentence the note appends.
+ */
+function authRefusalSentence(request) {
+    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';
+    if (request.status === 403) {
+        return request.sentAuthorization === true
+            ? `The browser sent \`${label}\` ${carried} and the API answered 403 — the token was ` +
+                'accepted but this user may not do it: read the route’s role/permission check in your ' +
+                'own source, and the account the session belongs to.'
+            : `The browser sent \`${label}\` and the API answered 403 — the request carried no ` +
+                '`Authorization` header, so either the client did not attach the token (check that the ' +
+                'request goes through the app’s HTTP client that the auth bond configures, and that the ' +
+                'token is stored where the client reads it) or the route refuses this user: read the ' +
+                'route’s role/permission check in your own source.';
+    }
+    if (request.sentAuthorization === true) {
+        return (`The browser sent \`${label}\` ${carried} and the API refused it: the token was sent and ` +
+            'rejected — the scheme (the client’s `authScheme`, e.g. `Token` vs `Bearer`) or the ' +
+            'token’s issuer differs from what the server verifies; read the verify middleware this ' +
+            'route reaches.');
+    }
+    return (`The browser sent \`${label}\` with NO \`Authorization\` header — the client did not attach ` +
+        'the token: check that the request goes through the app’s HTTP client that the auth bond ' +
+        'configures (not a bare `fetch`), and that the token is stored where the client reads it. ' +
+        'The shared client carries it through `setAuthToken` — the auth bond ' +
+        '(`createDefaultAuthClientWithHttpSync` in `@molecule/app-bonds-default-react`) mirrors the ' +
+        'auth client’s token there, and a session store of your own has to call it too. ' +
+        (request.sentCookie
+            ? '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.');
+}
+/**
+ * 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.
+ *
+ * @param items - The traces the note is about.
+ * @returns The sentences to append (each led by a space), or '' when no same-origin 401/403 was
+ *   traced.
+ */
+function authRefusalAdvice(items) {
+    const sentences = [];
+    const seen = new Set();
+    for (const item of items) {
+        for (const request of item.requests) {
+            if (request.status !== 401 && request.status !== 403)
+                continue;
+            if (sameOriginPath(request) === null)
+                continue;
+            const key = `${request.status} ${request.sentAuthorization ? (request.authorization ?? 'header') : 'none'} ${request.sentCookie ? 'cookie' : ''}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            sentences.push(authRefusalSentence(request));
+            if (sentences.length === 2)
+                return ` ${sentences.join(' ')}`;
+        }
+    }
+    return sentences.length === 0 ? '' : ` ${sentences.join(' ')}`;
+}
 /**
  * The API path prefixes the traced requests themselves show.
  *
@@ -1148,12 +1368,16 @@ function missingApiPrefixSentence(request) {
  * 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.
+ * When a navigation the runner reports as the failure never finished and one of the document's
+ * own subresources (a stylesheet, a script, an asset under `/assets/`) never got a response either
+ * — having started inside that wait — the 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. An asset merely unfinished when a selector wait
+ * ran out the test budget, or one a teardown/`afterEach` trace holds, is not a cause: the note
+ * says it "had no recorded response when the test ended; that alone does not establish the cause"
+ * (xr-molecule-flash-m153 +13:43).
  *
  * 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`,
@@ -1162,6 +1386,15 @@ function missingApiPrefixSentence(request) {
  * 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`.
  *
+ * A 401/403 on the app's own origin is answered from the request's own credential record instead
+ * ({@link authRefusalSentence}): no `Authorization` header means the CLIENT never attached the
+ * token (the shared HTTP client's `setAuthToken` is what the auth bond mirrors it into), while a
+ * header the API then refused moves the answer to the server. The handler sentence is kept for
+ * the rest — 404/422/500 — and dropped when every failure was a credential refusal, because a
+ * trace that proves the header was never sent cannot be explained by the handler.
+ * xr-molecule-flash-m148 (+29:18) hit this exactly: six local walks read
+ * `POST …/favorite → 401 {"errors":{"token":["is missing"]}}` as a handler bug.
+ *
  * @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
@@ -1169,17 +1402,22 @@ function missingApiPrefixSentence(request) {
  * @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.
+ * @param report - The runner's own report for this run ({@link TraceRunReport}): each failing
+ *   test's declared location, the operation its failure names and the deadline it names, plus
+ *   whether the same result's `testRunNote` already points at a production build. A pending asset
+ *   is called the cause only when the runner says the failing operation for THAT test is the
+ *   navigation it was loading; without the report nothing is called a navigation stall.
  * @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 = [], apiPrefixes = []) {
-    const candidates = items.filter(traceRowEvidence);
+export function failureTraceNote(items, target, earlierFailures = [], apiPrefixes = [], report = {}) {
+    const candidates = items.filter((item) => traceRowEvidence(item, report));
     if (candidates.length === 0)
         return null;
     // Ranked, then deduplicated BY LOCATION — in that order, so the row kept for a location is the
     // one carrying the strongest evidence (m112's duplicate `afterEach` rows).
     const ranked = candidates
-        .map((item, index) => ({ item, index, tier: traceRowTier(item, earlierFailures) }))
+        .map((item, index) => ({ item, index, tier: traceRowTier(item, earlierFailures, report) }))
         .sort((left, right) => left.tier - right.tier || left.index - right.index);
     const traced = [];
     const seen = new Set();
@@ -1212,14 +1450,25 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
     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)),
+    // A credential refusal (401/403 on the app's own API) is not the handler's answer: the trace's
+    // own `Authorization` record says whether the CLIENT attached the token at all (m148 +29:18).
+    const authRefusals = failedRequests.filter((request) => sameOriginPath(request) !== null && (request.status === 401 || request.status === 403));
+    const everyFailureAuth = failedRequests.length > 0 && authRefusals.length === failedRequests.length;
+    const authAdvice = authRefusalAdvice(traced);
+    // 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}).
+    const stalls = traced.map((item) => stalledNavigation(item, report));
+    // "Every failure this run traced…" is only honest when every traced test meets that bar — one
+    // stalled trace beside a selector-wait failure is not the cause of the run (m153).
+    const everyTracedStalls = stalls.every((stall) => stall !== null);
+    const stalledAssets = everyTracedStalls
+        ? [...new Set(stalls.flatMap((stall) => stall?.assets.map(requestLabel) ?? []))]
+        : [];
+    const stalledWaits = [
+        ...new Set(stalls.flatMap((stall) => (stall === null ? [] : [stall.reported]))),
     ];
+    const anyStalled = stalls.some((stall) => stall !== null);
     const rows = [];
     for (const [index, item] of traced.entries()) {
         // The test's LAST action before the failing assertion leads the row (m148): the requests it
@@ -1227,10 +1476,24 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
         // page's own last call (a redirect target's `GET /api/tags`) and the shell's files do not.
         const lead = item.lead;
         const step = item.lastAction;
-        // A navigation that never finished has one explanation — the stalled asset it was waiting on
-        // (m135) — and that leads the row instead of the action's own document request.
-        const stalledNav = navigationNeverFinished(item) && item.requests.some(stalledDocumentSubresource);
-        const stepRequests = step !== undefined && !stalledNav ? step.requests : [];
+        // A navigation the runner reported, still waiting on a stalled asset (m135), leads the row
+        // instead of the action's own document request.
+        const stall = stalls[index] ?? null;
+        const stalledNav = stall !== null;
+        // The document subresources that never finished inside the navigation the runner reported:
+        // the page was waiting on them when the test's budget ran out (m135).
+        const stalled = stall?.assets ?? [];
+        // The same kind of pending asset on a trace the runner does NOT report as a navigation
+        // failure (a selector wait that ran out the test budget, an `afterEach`/teardown trace): it is
+        // not a cause, and it is still worth naming so the executor does not have to guess (m153).
+        const stalledKeys = new Set(stalled.map(requestKey));
+        const pendingAssets = item.requests.filter((request) => stalledDocumentSubresource(request) && !stalledKeys.has(requestKey(request)));
+        const pendingKeys = new Set(pendingAssets.map(requestKey));
+        // A pending asset says nothing about what the action got back, so it never rides the action
+        // lead — the honest bucket below names it (m153).
+        const stepRequests = step !== undefined && !stalledNav
+            ? step.requests.filter((request) => !pendingKeys.has(requestKey(request)))
+            : [];
         const stepKeys = new Set(stepRequests.map(requestKey));
         const isLead = (request) => lead !== undefined && requestKey(request) === requestKey(lead);
         // The page shell's own requests take no row, in any bucket: an aborted `/sw.js` would
@@ -1239,20 +1502,16 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
         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)
-            : [];
+        const budget = stall?.budgetMs ?? null;
         let room = MAX_TRACE_NOTE_REQUESTS;
         const parts = [];
         if (step !== undefined && !stalledNav) {
             const head = `the test's last action was ${step.api} at ${actionClock(item, step.start)}`;
-            if (step.requests.length === 0) {
+            if (stepRequests.length === 0) {
                 parts.push(`${head}, and it sent no request`);
             }
             else {
-                const shown = step.requests.slice(0, room);
+                const shown = stepRequests.slice(0, room);
                 room -= shown.length;
                 // The response body is the point (m148: the register `POST /api/users` answered 201 and
                 // the page rendered signed-out anyway) — printed whatever the status.
@@ -1279,18 +1538,25 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
             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');
+                `response, still in flight when the ${stall?.reported ?? 'navigation'} wait ran out` +
+                (budget === null ? '' : ` of the suite's ${Math.round(budget / 1000)} s per-test budget`));
+        }
+        if (pendingAssets.length > 0 && room > 0) {
+            const shown = pendingAssets.slice(0, room);
+            room -= shown.length;
+            parts.push(`had no recorded response when the test ended; that alone does not establish the cause: ` +
+                shown.map(requestLabel).join('; '));
         }
         if (unanswered.length > 0 && room > 0) {
             const shown = unanswered.slice(0, room);
             room -= shown.length;
-            parts.push(`no response recorded — still in flight when the test ended, so not a server failure: ` +
-                shown.map(requestLabel).join('; '));
+            parts.push(`no response recorded — still in flight when the test ended, so not a server failure; ` +
+                `that alone does not establish the cause: ${shown.map(requestLabel).join('; ')}`);
         }
         if (answered.length > 0 && room > 0) {
             // An action that sent nothing leaves the page's own load as the only requests there are:
             // name them for what they are, not as the action's answer.
-            const label = step !== undefined && !stalledNav && step.requests.length === 0
+            const label = step !== undefined && !stalledNav && stepRequests.length === 0
                 ? 'also answered (started before the action)'
                 : 'answered';
             parts.push(`${label}: ${answered.slice(0, room).map(requestLine).join('; ')}`);
@@ -1326,22 +1592,30 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
                     '`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
+    // A navigation the RUNNER reported failing, 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").
+    // the page"). Every traced test must meet the bar; one stalled trace beside a selector-wait
+    // failure is not the run's cause (m153).
     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(', ')} ` +
+        : `Every failure this run traced is a navigation the runner reported failing ` +
+            `(${stalledWaits.join(', ')}), 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`;
+            `app's state or a selector: ` +
+            (report.productionBuildAdvised
+                ? `the run's own test note already names the next measurement — the same suite against ` +
+                    `a production build, because the dev server's page load is not the built app's — take ` +
+                    `that one step first, and come back to the app only if the same navigation times out ` +
+                    `there too with a stalled asset in the trace.\n\n`
+                : `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} ` +
@@ -1352,14 +1626,26 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
         (anyFailed
             ? 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.'
+                : everyFailureAuth
+                    ? // Every failure was a credential refusal: the handler is not the problem, and the
+                        // auth advice already names what is (m148 was sent to the handler six walks running).
+                        authAdvice
+                    : '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.' +
+                        authAdvice
+            : anyStalled
+                ? report.productionBuildAdvised
+                    ? 'No listed request failed — none got a 4xx/5xx or a network error — but a navigation ' +
+                        'the runner reported failing was still waiting on a document subresource that never ' +
+                        'answered. Do not read this as a page-state bug, and do not re-run the same tests ' +
+                        'unchanged: the run’s own test note names the production build as the next ' +
+                        'measurement — take that one step first, and change the app only if the same ' +
+                        'navigation times out there with no stalled asset in the trace.'
+                    : '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 what the test's last action sent (the first line of each " +
                     'row) and what the page did next: a request that answered (2xx included) while the page ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.9.11",
+  "version": "1.9.13",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",