@molecule/api-ai-tools 1.9.10 → 1.9.12

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-18T06:52:09.924Z
+Generated: 2026-10-18T07:36:48.788Z
 -->
 
 # @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
 }
 ```
 
@@ -455,7 +477,7 @@ interface TraceAction {
 
 #### `TraceArtifact`
 
-What one trace says: the test it belongs to, the requests it made, and its console errors.
+What one trace says: the test it belongs to, the requests it made, and its console lines.
 
 ```typescript
 interface TraceArtifact {
@@ -477,7 +499,11 @@ interface TraceArtifact {
    * Absent when the trace recorded neither, and on traces read before this field existed.
    */
   lead?: TraceRequest
-  /** The console errors and page errors the page raised. */
+  /**
+   * The console lines and page errors the page raised: its errors first, then a line that names a
+   * session decision or comes from a molecule package, then any other warning, then the browser's
+   * own resource error ({@link traceArtifactsScript}).
+   */
   console: string[]
   /**
    * The test's LAST user action before the failing assertion and the requests it caused — what the
@@ -1819,7 +1845,7 @@ function buildTools(backend: ExecutionBackend, config?: ToolBuildConfig): AITool
 
 The Node program the sandbox runs to read a failed run's traces: `node <script> <dir>` prints one
 `TRACE <json>` line per `trace.zip` under `<dir>` (newest first, {@link MAX_TRACE_ARTIFACTS} of
-them), each with the test it belongs to, the requests its page made and its console errors.
+them), each with the test it belongs to, the requests its page made and its console lines.
 
 It is a standalone program, not an import, for the reason `@molecule/api-code-sandbox` runs it:
 Playwright's own zip reader is not reachable from a project's `node_modules`, and a dependency
@@ -3221,7 +3247,8 @@ const MAX_TRACED_REQUESTS: 6
 
 #### `MAX_TRACED_CONSOLE`
 
-How many console errors one test's trace contributes.
+How many console lines one test's trace contributes: errors ahead of a session or molecule-package
+line, both ahead of a plain warning and of the browser's own resource error.
 
 ```typescript
 const MAX_TRACED_CONSOLE: 4

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.
@@ -104,7 +126,7 @@ export interface TraceAction {
     /** When it finished, or null when the run ended before it did. */
     end: number | null;
 }
-/** What one trace says: the test it belongs to, the requests it made, and its console errors. */
+/** What one trace says: the test it belongs to, the requests it made, and its console lines. */
 export interface TraceArtifact {
     /** The failure's spec file, relative to the run's directory, when the trace names one. */
     spec: string | null;
@@ -124,7 +146,11 @@ export interface TraceArtifact {
      * Absent when the trace recorded neither, and on traces read before this field existed.
      */
     lead?: TraceRequest;
-    /** The console errors and page errors the page raised. */
+    /**
+     * The console lines and page errors the page raised: its errors first, then a line that names a
+     * session decision or comes from a molecule package, then any other warning, then the browser's
+     * own resource error ({@link traceArtifactsScript}).
+     */
     console: string[];
     /**
      * The test's LAST user action before the failing assertion and the requests it caused — what the
@@ -145,7 +171,10 @@ export interface TraceArtifact {
 export declare const MAX_TRACE_ARTIFACTS = 12;
 /** How many requests one test's trace contributes. */
 export declare const MAX_TRACED_REQUESTS = 6;
-/** How many console errors one test's trace contributes. */
+/**
+ * How many console lines one test's trace contributes: errors ahead of a session or molecule-package
+ * line, both ahead of a plain warning and of the browser's own resource error.
+ */
 export declare const MAX_TRACED_CONSOLE = 4;
 /** How many of the page's own actions one test's trace contributes, the LAST ones. */
 export declare const MAX_TRACED_ACTIONS = 40;
@@ -170,7 +199,7 @@ export declare const TRACE_NOTE_LEAD_GOT_CHARS = 200;
 /**
  * The Node program the sandbox runs to read a failed run's traces: `node <script> <dir>` prints one
  * `TRACE <json>` line per `trace.zip` under `<dir>` (newest first, {@link MAX_TRACE_ARTIFACTS} of
- * them), each with the test it belongs to, the requests its page made and its console errors.
+ * them), each with the test it belongs to, the requests its page made and its console lines.
  *
  * It is a standalone program, not an import, for the reason `@molecule/api-code-sandbox` runs it:
  * Playwright's own zip reader is not reachable from a project's `node_modules`, and a dependency
@@ -282,7 +311,7 @@ export declare function stalledDocumentSubresource(request: TraceRequest): boole
  * row falls back to {@link TraceArtifact.lead}: the page's last answered fetch/xhr.
  *
  * 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
+ * needs a recorded response, a real failure or a console line ({@link traceRowEvidence}), rows are
  * deduplicated by the test's location, and they are ordered real failure → repeated from an
  * earlier walk → the rest ({@link traceRowTier}). Without that the note spent all five rows on four
  * traces of one `afterEach` line whose every request was `-1`, and left the favorite cause — the
@@ -306,6 +335,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

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

@@ -33,7 +33,10 @@ import { isPlaywrightRunCommand, redactSecrets } from './utilities.js';
 export const MAX_TRACE_ARTIFACTS = 12;
 /** How many requests one test's trace contributes. */
 export const MAX_TRACED_REQUESTS = 6;
-/** How many console errors one test's trace contributes. */
+/**
+ * How many console lines one test's trace contributes: errors ahead of a session or molecule-package
+ * line, both ahead of a plain warning and of the browser's own resource error.
+ */
 export const MAX_TRACED_CONSOLE = 4;
 /** How many of the page's own actions one test's trace contributes, the LAST ones. */
 export const MAX_TRACED_ACTIONS = 40;
@@ -60,7 +63,7 @@ const TRACE_NOTE_FAILURE_CHARS = 120;
 /**
  * The Node program the sandbox runs to read a failed run's traces: `node <script> <dir>` prints one
  * `TRACE <json>` line per `trace.zip` under `<dir>` (newest first, {@link MAX_TRACE_ARTIFACTS} of
- * them), each with the test it belongs to, the requests its page made and its console errors.
+ * them), each with the test it belongs to, the requests its page made and its console lines.
  *
  * It is a standalone program, not an import, for the reason `@molecule/api-code-sandbox` runs it:
  * Playwright's own zip reader is not reachable from a project's `node_modules`, and a dependency
@@ -95,6 +98,20 @@ const MAX_CONSOLE = ${MAX_TRACED_CONSOLE}
 const MAX_ACTIONS = ${MAX_TRACED_ACTIONS}
 const MAX_BODY = ${MAX_TRACED_BODY_CHARS}
 const MAX_URL = 200
+// A console line that is not an error but still has to reach the note (m148): one a molecule
+// package wrote — it names the package, the \`[molecule/…]\` prefix, or the \`[scope]\` prefix
+// molecule's own logger writes for a named module ([auth], [http], [i18n]) — or one that names a
+// session decision in the page's own words. \`@molecule/app-auth\` logged "Token refresh failed,
+// logging out" at WARNING level, and this reader kept error entries only, so every trace note
+// carried the browser's generic "Failed to load resource: 401" while the platform's own package was
+// saying, in words, that it had signed the user out.
+const MOLECULE_CONSOLE = /@molecule\\/|\\[molecule[:\\/][^\\]]*\\]|^\\s*\\[[a-z][a-z0-9-]*\\]/
+const SESSION_CONSOLE = /\\b(?:auth(?:entication|enticated|orization|orized)?|session|token|sign(?:ed|ing)?[\\s-]?out|log(?:ged|ging)?[\\s-]?out|refresh(?:ed|ing)?\\s+failed|no\\s+provider)\\b/i
+
+// Whether a console line belongs in the note even though it is not at error level.
+function consoleSignal(text) {
+  return MOLECULE_CONSOLE.test(text) || SESSION_CONSOLE.test(text)
+}
 
 function walk(dir, depth, out) {
   if (depth < 0) return
@@ -226,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,
@@ -413,6 +452,9 @@ for (const one of found.slice(0, MAX_TRACES)) {
       ...(r.sent ? { sent: r.sent } : {}),
       ...(r.got ? { got: r.got } : {}),
       type: r.type || undefined,
+      ...(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.
@@ -508,13 +550,18 @@ for (const one of found.slice(0, MAX_TRACES)) {
     chosen.push(wire(r))
   }
   const consoleErrors = []
+  const consoleSignals = []
+  const consoleWarnings = []
   let spec = null
   let line = 0
   for (const entry of trace) {
     if (!entry) continue
-    if (entry.type === 'console' && entry.messageType === 'error' && typeof entry.text === 'string')
-      consoleErrors.push(entry.text)
-    else if (entry.type === 'event' && entry.method === 'pageError') {
+    if (entry.type === 'console' && typeof entry.text === 'string') {
+      if (entry.messageType === 'error') consoleErrors.push(entry.text)
+      else if (consoleSignal(entry.text)) consoleSignals.push(entry.text)
+      else if (entry.messageType === 'warning' || entry.messageType === 'warn')
+        consoleWarnings.push(entry.text)
+    } else if (entry.type === 'event' && entry.method === 'pageError') {
       const message = messageOf(entry.params)
       if (message) consoleErrors.push(message)
     } else if (entry.type === 'before' && Array.isArray(entry.stack) && entry.stack.length) {
@@ -526,9 +573,13 @@ for (const one of found.slice(0, MAX_TRACES)) {
     }
   }
   // Chromium reports every failed request as a console error too; where the page logged something
-  // of its own about it, that is the line worth reading.
+  // of its own about it, that is the line worth reading. Errors lead, then the lines that name a
+  // session decision or come from a molecule package (m148), then any other warning — the browser's
+  // resource error is last, because it is evidence of a failed request, not of a cause, and the
+  // platform's own package saying "logging out" must not be ranked below it.
   const specific = consoleErrors.filter(function (text) { return !/^Failed to load resource/.test(text) })
-  const keptConsole = specific.length > 0 ? specific : consoleErrors
+  const keptConsole = specific.concat(consoleSignals, consoleWarnings)
+  if (specific.length === 0) keptConsole.push.apply(keptConsole, consoleErrors)
   if (chosen.length === 0 && keptConsole.length === 0 && actions.length === 0) continue
   process.stdout.write('TRACE ' + JSON.stringify({
     dir: path.relative(ROOT, path.dirname(one.file)),
@@ -564,6 +615,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 } : {}),
     };
 }
 /**
@@ -910,7 +967,7 @@ function repeatsEarlierFailure(item, earlier) {
 }
 /**
  * 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 error. A request with no response is
+ * real failure (4xx/5xx or a network error), or a console line. A request with no response is
  * not evidence (m112 +53:46): four of the note's five rows were traces of one `afterEach` line
  * whose every request was `-1`, so the favorite cause — repeated in all three walks — stayed
  * hidden in "… and 7 more traced failures".
@@ -921,7 +978,7 @@ function repeatsEarlierFailure(item, earlier) {
  * `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.
+ * @returns True when the trace holds a request or console line worth a row.
  */
 function traceRowEvidence(item) {
     return (item.console.length > 0 ||
@@ -1005,6 +1062,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.
  *
@@ -1112,7 +1257,7 @@ function missingApiPrefixSentence(request) {
  * row falls back to {@link TraceArtifact.lead}: the page's last answered fetch/xhr.
  *
  * 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
+ * needs a recorded response, a real failure or a console line ({@link traceRowEvidence}), rows are
  * deduplicated by the test's location, and they are ordered real failure → repeated from an
  * earlier walk → the rest ({@link traceRowTier}). Without that the note spent all five rows on four
  * traces of one `afterEach` line whose every request was `-1`, and left the favorite cause — the
@@ -1136,6 +1281,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
@@ -1186,6 +1340,11 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
     const prefixAdvice = missingPrefix.length > 0
         ? ` ${missingPrefix.slice(0, 2).map(missingApiPrefixSentence).join(' ')}`
         : '';
+    // 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 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 = [
@@ -1326,9 +1485,14 @@ 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.'
+                : 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
             : 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 ' +

package/package.json

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