@molecule/api-ai-tools 1.9.9 → 1.9.10

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-18T04:56:57.682Z
+Generated: 2026-10-18T06:52:09.924Z
 -->
 
 # @molecule/api-ai-tools
@@ -397,6 +397,44 @@ interface TraceRequest {
    * `net::ERR_*`, nothing rendered and no selector or app request was measured.
    */
   type?: string
+  /**
+   * When the request started, on the trace's own monotonic clock (ms) — the same clock the
+   * {@link TraceAction}s carry, so a request can be attributed to the action that caused it.
+   * Absent on traces whose network entries recorded no clock (an older Playwright, a synthetic
+   * fixture), in which case only recording order is available.
+   */
+  startedAt?: number
+}
+```
+
+#### `TraceLastAction`
+
+The test's LAST user action before the failing assertion, and the requests it caused.
+
+An assertion after a navigation is not explained by the page's last call (`GET /api/tags` on
+whatever page the app redirected to); it is explained by what the action the test took sent and
+what came back (xr-molecule-flash-m148: 13 then 12 failing tests, every trace row leading with
+`GET /api/tags → 200`, while the register `POST /api/users` and its answer — the fact that
+explains the signed-out page — was never shown).
+
+```typescript
+interface TraceLastAction {
+  /** The Playwright API the trace names: `Locator.click`, `Locator.fill`, `Frame.goto`. */
+  api: string
+  /** When the action started, on the trace's monotonic clock (ms). */
+  start: number
+  /** When it finished, or null when the run ended before it did. */
+  end: number | null
+  /**
+   * The requests the action caused — started after it and before the failing assertion, the app's
+   * own API calls first, static assets and the page shell's own files left out. Empty when the
+   * action sent none.
+   */
+  requests: TraceRequest[]
+  /** The main frame's URL when the action ran, when the trace recorded frame snapshots. */
+  pageBefore?: string
+  /** The last main-frame URL the trace recorded — where the page ended up. */
+  pageAfter?: string
 }
 ```
 
@@ -428,17 +466,27 @@ interface TraceArtifact {
   /** The requests the page made, the interesting ones first ({@link traceArtifactsScript}). */
   requests: TraceRequest[]
   /**
-   * The request the failing step itself sent: the trace's LAST `fetch`/`xhr` in recording order
-   * (a click's own call), else its document request. It leads the note's row, because a click that
-   * changed nothing is explained by the request the click sent and what came back — xr-molecule-
-   * flash-m135's Follow click sent `DELETE /api/profiles/x/follow → 200` (its `following` state was
-   * stale) and the note listed only the test's earlier, answered requests.
+   * The request the failing step itself sent: the first answered request the test's last user
+   * action caused ({@link TraceArtifact.lastAction}), else — on a trace with no action clock — the
+   * trace's LAST `fetch`/`xhr` in recording order, else its document. It leads the note's row when
+   * {@link lastAction} is absent, because a click that changed nothing is explained by the request
+   * the click sent and what came back — xr-molecule-flash-m135's Follow click sent
+   * `DELETE /api/profiles/x/follow → 200` (its `following` state was stale) and the note listed only
+   * the test's earlier, answered requests.
    *
    * 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. */
   console: string[]
+  /**
+   * The test's LAST user action before the failing assertion and the requests it caused — what the
+   * row leads with, when the trace carries the action times ({@link TraceLastAction}).
+   *
+   * Absent on traces read before this field existed, and on traces whose network entries recorded
+   * no clock; the row then falls back to {@link lead}.
+   */
+  lastAction?: TraceLastAction
   /**
    * The page's own actions in the order the trace recorded them, bounded — what a test that ran
    * out of a per-test budget spends its time on. A test that repeats one action prints it once per
@@ -1900,8 +1948,8 @@ A 4xx request carries what the page SENT beside its status, so a wrapped body is
 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
+Every row opens with the test's LAST user action before the failing assertion and the requests
+that action caused ({@link TraceArtifact.lastAction}) — started after it, before the assertion,
 
 _(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/trace-artifacts.d.ts`.)_
 

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;AAqEnE;;;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;AA8ED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAk9ExF"}
+{"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"}

package/dist/tools.js

@@ -363,7 +363,7 @@ async function backgroundTaskState(backend, command, seconds, ceilingMs) {
 }
 import { suiteCommandTarget } from './suite-overlap.js';
 import { diagnosisTraceCommand } from './trace-artifacts.js';
-import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, earlyReturnCause, emptyCallError, failureCausesNote, findPathArgs, findPatternArgs, fusedLine, htmlOutline, isCommandTimeout, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isSuiteRunCommand, isValidGlob, linesWithinSerialized, literalDirPrefix, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_HTML_INLINE_CHARS, MAX_OUTPUT_SIZE, MAX_READ_CALL_CHARS, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, printsOnlySource, READ_RESULT_ENVELOPE_CHARS, redactSecrets, redactSecretsInCode, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningOutputSliceCommand, searchTimeoutError, serializedChars, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunPipelinePlacement, suiteRunPriorityLaunch, truncateMiddle, universalCause, whitespaceTolerantReplace, withoutSuiteTimeout, } from './utilities.js';
+import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, earlyReturnCause, emptyCallError, failureCausesNote, findPathArgs, findPatternArgs, fusedLine, htmlOutline, isCommandTimeout, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isSuiteRunCommand, isValidGlob, linesWithinSerialized, literalDirPrefix, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_HTML_INLINE_CHARS, MAX_OUTPUT_SIZE, MAX_READ_CALL_CHARS, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, printsOnlySource, READ_RESULT_ENVELOPE_CHARS, redactSecrets, redactSecretsInCode, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningOutputSliceCommand, searchTimeoutError, serializedChars, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunPipelinePlacement, suiteRunPriorityLaunch, TOOL_RESULT_CHARS, truncateMiddle, universalCause, whitespaceTolerantReplace, withoutSuiteTimeout, } from './utilities.js';
 /**
  * How long exec_command waits for a command it backgrounded only because the
  * command asked for more than the tool's ceiling, before handing back a task id.
@@ -610,6 +610,33 @@ function sandboxStillStarting(error) {
         return true;
     return /not (?:found|running)|notfound|not attached|still starting/i.test(`${name} ${message}`);
 }
+/**
+ * The most entries a bounded `list_files` result lists. A package catalog is not read entry by
+ * entry — the executor wants one package it can name — so the summary keeps enough names to show
+ * the naming pattern and no more.
+ */
+const LIST_FILES_HEAD_ENTRIES = 20;
+/**
+ * The line a package-catalog listing carries instead of a catalog's worth of names: a directory
+ * of 1,032 names answers no question, while `find_package` answers the one that was asked.
+ */
+const MOLECULE_CATALOG_POINTER = 'use find_package(query) to search the @molecule catalog by what you need, and ' +
+    'read_molecule_doc(name) for one package';
+/**
+ * Which package catalog a `list_files` path is, when it is one: the `@molecule` scope (1,032
+ * package directories, ~53 KB of names in one plan-phase call — X0 xr-molecule-flash-m151 at
+ * +01:54) or the `node_modules` root above it.
+ *
+ * @param path - A resolved (absolute, normalized) directory path.
+ * @returns `'molecule'` for the `@molecule` scope, `'packages'` for a `node_modules` root, or null.
+ */
+function packageCatalog(path) {
+    if (/(^|\/)node_modules\/@molecule$/.test(path))
+        return 'molecule';
+    if (/(^|\/)node_modules$/.test(path))
+        return 'packages';
+    return null;
+}
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *
@@ -1161,6 +1188,39 @@ export function buildTools(backend, config) {
             return { error: directoryReadHint(message, path) ?? `Failed to read ${path}: ${message}` };
         }
     }
+    /**
+     * A `list_files` result, bounded when the directory is a package catalog or when the whole
+     * listing would not fit one tool result ({@link TOOL_RESULT_CHARS} — molecule-dev's cap on a
+     * tool result's text, which cuts a longer one through its MIDDLE). A normal app directory whose
+     * listing fits comes back exactly as it always has.
+     *
+     * @param path - The resolved directory path.
+     * @param entries - Everything the backend listed.
+     * @returns The listing, or its count plus the first {@link LIST_FILES_HEAD_ENTRIES} names and a note.
+     */
+    function listFilesResult(path, entries) {
+        const listing = {
+            path,
+            entries: entries.map((entry) => ({ name: entry.name, type: entry.type })),
+        };
+        const catalog = packageCatalog(path);
+        if (!catalog && JSON.stringify(listing).length <= TOOL_RESULT_CHARS)
+            return listing;
+        const head = listing.entries.slice(0, LIST_FILES_HEAD_ENTRIES);
+        const cut = head.length < entries.length;
+        const note = catalog === 'molecule'
+            ? `${entries.length} @molecule packages are installed here` +
+                (cut ? `; this listing is cut to ${head.length} names` : '') +
+                `. ${MOLECULE_CATALOG_POINTER}.`
+            : catalog === 'packages'
+                ? `This node_modules holds ${entries.length} entries` +
+                    (cut ? `; this listing is cut to ${head.length} names` : '') +
+                    `. ${MOLECULE_CATALOG_POINTER}.`
+                : `This directory holds ${entries.length} entries` +
+                    (cut ? `; this listing is cut to ${head.length}` : '') +
+                    '. Narrow it with find_files (by path pattern) or search_files (by content), or list a subdirectory.';
+        return { path, count: entries.length, entries: head, note };
+    }
     const toolImpls = {
         async list_files(input) {
             const path = resolve(input.path || '');
@@ -1169,7 +1229,7 @@ export function buildTools(backend, config) {
                 return { error: symlinkErr };
             try {
                 const entries = await backend.readDir(path);
-                return { path, entries: entries.map((e) => ({ name: e.name, type: e.type })) };
+                return listFilesResult(path, entries);
             }
             catch (e) {
                 const message = e.message;

package/dist/trace-artifacts.d.ts

@@ -60,6 +60,40 @@ export interface TraceRequest {
      * `net::ERR_*`, nothing rendered and no selector or app request was measured.
      */
     type?: string;
+    /**
+     * When the request started, on the trace's own monotonic clock (ms) — the same clock the
+     * {@link TraceAction}s carry, so a request can be attributed to the action that caused it.
+     * Absent on traces whose network entries recorded no clock (an older Playwright, a synthetic
+     * fixture), in which case only recording order is available.
+     */
+    startedAt?: number;
+}
+/**
+ * The test's LAST user action before the failing assertion, and the requests it caused.
+ *
+ * An assertion after a navigation is not explained by the page's last call (`GET /api/tags` on
+ * whatever page the app redirected to); it is explained by what the action the test took sent and
+ * what came back (xr-molecule-flash-m148: 13 then 12 failing tests, every trace row leading with
+ * `GET /api/tags → 200`, while the register `POST /api/users` and its answer — the fact that
+ * explains the signed-out page — was never shown).
+ */
+export interface TraceLastAction {
+    /** The Playwright API the trace names: `Locator.click`, `Locator.fill`, `Frame.goto`. */
+    api: string;
+    /** When the action started, on the trace's monotonic clock (ms). */
+    start: number;
+    /** When it finished, or null when the run ended before it did. */
+    end: number | null;
+    /**
+     * The requests the action caused — started after it and before the failing assertion, the app's
+     * own API calls first, static assets and the page shell's own files left out. Empty when the
+     * action sent none.
+     */
+    requests: TraceRequest[];
+    /** The main frame's URL when the action ran, when the trace recorded frame snapshots. */
+    pageBefore?: string;
+    /** The last main-frame URL the trace recorded — where the page ended up. */
+    pageAfter?: string;
 }
 /** One action the traced page performed, with the trace's own timing for it. */
 export interface TraceAction {
@@ -79,17 +113,27 @@ export interface TraceArtifact {
     /** The requests the page made, the interesting ones first ({@link traceArtifactsScript}). */
     requests: TraceRequest[];
     /**
-     * The request the failing step itself sent: the trace's LAST `fetch`/`xhr` in recording order
-     * (a click's own call), else its document request. It leads the note's row, because a click that
-     * changed nothing is explained by the request the click sent and what came back — xr-molecule-
-     * flash-m135's Follow click sent `DELETE /api/profiles/x/follow → 200` (its `following` state was
-     * stale) and the note listed only the test's earlier, answered requests.
+     * The request the failing step itself sent: the first answered request the test's last user
+     * action caused ({@link TraceArtifact.lastAction}), else — on a trace with no action clock — the
+     * trace's LAST `fetch`/`xhr` in recording order, else its document. It leads the note's row when
+     * {@link lastAction} is absent, because a click that changed nothing is explained by the request
+     * the click sent and what came back — xr-molecule-flash-m135's Follow click sent
+     * `DELETE /api/profiles/x/follow → 200` (its `following` state was stale) and the note listed only
+     * the test's earlier, answered requests.
      *
      * 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. */
     console: string[];
+    /**
+     * The test's LAST user action before the failing assertion and the requests it caused — what the
+     * row leads with, when the trace carries the action times ({@link TraceLastAction}).
+     *
+     * Absent on traces read before this field existed, and on traces whose network entries recorded
+     * no clock; the row then falls back to {@link lead}.
+     */
+    lastAction?: TraceLastAction;
     /**
      * The page's own actions in the order the trace recorded them, bounded — what a test that ran
      * out of a per-test budget spends its time on. A test that repeats one action prints it once per
@@ -226,11 +270,16 @@ export declare function stalledDocumentSubresource(request: TraceRequest): boole
  * 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.
+ * Every row opens with the test's LAST user action before the failing assertion and the requests
+ * that action caused ({@link TraceArtifact.lastAction}) — started after it, before the assertion,
+ * the app's own API calls first, each with its status and the first 200 characters of its response,
+ * then where the page went next. The trace's action clock and each request's `_monotonicTime` are
+ * the same clock, so "caused" is the trace's own fact rather than a guess from recording order.
+ * xr-molecule-flash-m148 failed 13 then 12 tests on one unnamed cause while every row led with
+ * `GET /api/tags → 200` — the Home page's own fetch after the redirect — and filled its answered
+ * slots with the PWA's `/workbox-*.js` and its `/icons/*.svg`; the register `POST /api/users`
+ * (answered 201, the page still rendering signed-out) never appeared. With no action clock, the
+ * 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

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

@@ -90,6 +90,7 @@ const zlib = require('node:zlib')
 const ROOT = process.argv[2] || '/workspace'
 const MAX_TRACES = ${MAX_TRACE_ARTIFACTS}
 const MAX_REQUESTS = ${MAX_TRACED_REQUESTS}
+const MAX_NOTE = ${MAX_TRACE_NOTE_REQUESTS}
 const MAX_CONSOLE = ${MAX_TRACED_CONSOLE}
 const MAX_ACTIONS = ${MAX_TRACED_ACTIONS}
 const MAX_BODY = ${MAX_TRACED_BODY_CHARS}
@@ -231,6 +232,9 @@ for (const one of found.slice(0, MAX_TRACES)) {
       status: Number(response.status) || 0,
       failure: typeof response._failureText === 'string' ? response._failureText : undefined,
       type: type,
+      // 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,
       postData: request.postData,
       content: response.content,
     })
@@ -240,16 +244,6 @@ for (const one of found.slice(0, MAX_TRACES)) {
     origin = first ? originOf(first.path) : ''
   }
   for (const r of requests) r.path = pathOf(r.path).slice(0, MAX_URL)
-  // A 4xx from the app's own API is where a body SHAPE is diagnosed: keep what the page sent and
-  // what came back (bounded). A relative path here means the same origin as the traced document.
-  for (const r of requests) {
-    if (r.status < 400 || r.status >= 500) continue
-    if (/^https?:/i.test(r.path)) continue
-    const sent = bodyText(buf, entries, r.postData, MAX_BODY)
-    const got = bodyText(buf, entries, r.content, MAX_BODY)
-    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
@@ -283,20 +277,36 @@ for (const one of found.slice(0, MAX_TRACES)) {
   // 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 }
+  // The PWA worker's own hashed script (\`/workbox-d8ed3718.js\`), the manifest's touch icons
+  // (\`/icons/splash-*.svg\`), the favicons and fonts: the shell's files. They are typed \`other\` or
+  // \`fetch\` by the worker and the shell rather than \`script\`/\`image\`, so the type alone never
+  // caught them — on xr-molecule-flash-m148 they took three of the note's four slots on every
+  // failing test and pushed the register \`POST /api/users\` out.
   function shellPath(path) {
-    return /^\\/(?:sw|service-worker)\\.js(?:[?#]|$)|\\/manifest\\.webmanifest(?:[?#]|$)|\\/favicon[^/]*(?:[?#]|$)|\\/fonts?\\//.test(path) ||
-      /^\\/(?:assets|@vite|__mol)\\//.test(path)
+    var p = path
+    try { p = new URL(path, 'http://trace.local').pathname } catch (e) { p = String(path).split(/[?#]/)[0] }
+    return /^\\/(?:sw|service-worker)\\.js(?:[?#]|$)|\\/manifest\\.webmanifest(?:[?#]|$)|\\/favicon[^/]*(?:[?#]|$)|\\/fonts?\\//.test(p) ||
+      /^\\/(?:assets|@vite|__mol)\\//.test(p) ||
+      /^\\/workbox-[^/]*\\.js(?:[?#]|$)/.test(p) ||
+      /^\\/icons\\//.test(p) ||
+      /^\\/(?:apple-touch-icon|og-image|splash)[^/]*(?:[?#]|$)/.test(p)
   }
   function shellRequest(r) {
     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.
+  // manifest, a favicon, a font, the worker's own script and the manifest's icons. A pending
+  // \`/assets/*.css\` is NOT one of these — the navigation blocks on it (m135).
   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)
+    if (r.type === 'font' || r.type === 'manifest') return true
+    var p = r.path
+    try { p = new URL(r.path, 'http://trace.local').pathname } catch (e) { p = String(r.path).split(/[?#]/)[0] }
+    return /^\\/(?:sw|service-worker)\\.js(?:[?#]|$)|\\/manifest\\.webmanifest(?:[?#]|$)|\\/favicon[^/]*(?:[?#]|$)|\\/fonts?\\//.test(p) ||
+      /^\\/workbox-[^/]*\\.js(?:[?#]|$)/.test(p) ||
+      /^\\/icons\\//.test(p) ||
+      /^\\/(?:apple-touch-icon|og-image|splash)[^/]*(?:[?#]|$)/.test(p)
   }
   // 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
@@ -309,15 +319,19 @@ for (const one of found.slice(0, MAX_TRACES)) {
   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.
+  // Whether a request can lead a row: it got an answer (or failed for its own recorded reason),
+  // and it is the app's own call — a fetch/xhr of the page, or its document — never the page
+  // shell's own probe (a refused \`/sw.js\` is not the step's request — m125 +29:33).
+  //
+  // It ranks the requests the test's last action caused (see \`lastAction\` below), and it is the
+  // whole rule on a trace with no action clock (the fallback lead: the page's LAST call to the
+  // app's own origin, else the document load). That fallback is right for a click that changed
+  // nothing — xr-molecule-flash-m135 clicked Follow and sent a DELETE (its \`following\` state was
+  // stale) — and wrong for an assertion after a navigation (m148), which is why the action's
+  // clock, when the trace has one, decides.
   //
   // 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).
+  // what came back, and the note has its own honest row for it (m112 +30:45).
   function leadCandidate(r) {
     if (r.status <= 0 && typeof r.failure !== 'string') return false
     if (r.type === 'document') return true
@@ -329,29 +343,131 @@ for (const one of found.slice(0, MAX_TRACES)) {
     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 }
+  // The test's LAST user action before the failing assertion, and the requests it caused.
+  //
+  // The old lead was "the page's LAST call to the app's own origin", which is right for a click
+  // that changed nothing (m135) and wrong for an assertion after a navigation: the last call
+  // belongs to the page the app landed on (xr-molecule-flash-m148's \`GET /api/tags\` on Home),
+  // not to the action the test took. The trace records both clocks — the action's \`startTime\`
+  // and each HAR entry's \`_monotonicTime\` — so the requests that started after the last action
+  // are exactly the ones it caused, and the register \`POST /api/users\` (answered 201, the page
+  // then rendering signed-out) leads instead of the Home page's own fetch.
+  const USER_ACTION = /\\.(?:click|dblclick|tap|fill|press|pressSequentially|selectOption|check|uncheck|setInputFiles|goto|type)$/
+  const userActions = actions.filter(function (a) { return USER_ACTION.test(a.api) })
+  const lastAction = userActions.length > 0 ? userActions[userActions.length - 1] : null
+  // A request the action caused started after it (a millisecond of clock slack) and before the
+  // assertion — which is everything later in the trace. A request that started before it is the
+  // page's own load, not the action's; the page shell's files are never the step's, except a
+  // document subresource the open navigation is waiting on (m135).
+  function causedIndexes(action) {
+    const out = []
+    for (let i = 0; i < requests.length; i++) {
+      const r = requests[i]
+      if (typeof r.startedAt !== 'number' || r.startedAt < action.start - 1) continue
+      if (shellRequest(r) && !(navigationOpen && neverFinished(r) && !incidentalShell(r))) continue
+      out.push(i)
+    }
+    return out
   }
-  if (leadIndex === -1) {
-    for (let i = requests.length - 1; i >= 0; i--) {
-      if (requests[i].type === 'document' && leadCandidate(requests[i])) { leadIndex = i; break }
+  // API requests first, then the navigation the page made; a stalled asset outranks both when the
+  // navigation it belongs to never finished (m135's goto timeout was waiting on the CSS).
+  function causedOrder(indexes) {
+    const stalled = []
+    const apiCalls = []
+    const documents = []
+    const other = []
+    for (const i of indexes) {
+      const r = requests[i]
+      if (r.type === 'document') documents.push(i)
+      else if (navigationOpen && neverFinished(r) && !incidentalShell(r)) stalled.push(i)
+      else if (r.type === 'fetch' || r.type === 'xhr') apiCalls.push(i)
+      else other.push(i)
     }
+    return stalled.concat(apiCalls, documents, other)
   }
-  let lead = null
-  if (leadIndex !== -1) {
-    const r = requests[leadIndex]
+  const actionIndexes = lastAction === null ? [] : causedOrder(causedIndexes(lastAction))
+  // Both the action's own requests and a 4xx from the app's own API keep what the page sent and
+  // what came back. The action's requests keep the RESPONSE whatever its status — an answered
+  // \`POST /api/users → 201\` and its body is the fact that explains a signed-out page.
+  for (const i of actionIndexes) {
+    const r = requests[i]
+    const sent = bodyText(buf, entries, r.postData, MAX_BODY)
+    const got = bodyText(buf, entries, r.content, MAX_BODY)
+    if (sent) r.sent = sent
+    if (got) r.got = got
+  }
+  for (const r of requests) {
+    if (r.status < 400 || r.status >= 500) continue
+    if (/^https?:/i.test(r.path)) continue
     const sent = bodyText(buf, entries, r.postData, MAX_BODY)
     const got = bodyText(buf, entries, r.content, MAX_BODY)
-    lead = {
+    if (sent) r.sent = sent
+    if (got) r.got = got
+  }
+  function wire(r) {
+    return {
       method: r.method,
       path: r.path,
       status: r.status,
       failure: r.failure,
+      ...(r.sent ? { sent: r.sent } : {}),
+      ...(r.got ? { got: r.got } : {}),
       type: r.type || undefined,
-      ...(sent ? { sent: sent } : {}),
-      ...(got ? { got: got } : {}),
+    }
+  }
+  // The main frame's URL, timed: what the page showed when the action ran, and where it ended up.
+  // The trace records these around every action, which is how the note can say what the page did
+  // after the request — a client-side redirect never appears in the network log as a document.
+  const frames = []
+  for (const entry of trace) {
+    if (!entry || entry.type !== 'frame-snapshot') continue
+    const snap = entry.snapshot || {}
+    if (snap.isMainFrame === false) continue
+    if (typeof snap.frameUrl !== 'string' || typeof snap.timestamp !== 'number') continue
+    frames.push({ url: pathOf(snap.frameUrl).slice(0, MAX_URL), at: snap.timestamp })
+  }
+  let last = null
+  if (lastAction !== null) {
+    let pageBefore
+    for (const frame of frames) { if (frame.at <= lastAction.start) pageBefore = frame.url }
+    if (pageBefore === undefined && frames.length > 0) pageBefore = frames[0].url
+    const pageAfter = frames.length > 0 ? frames[frames.length - 1].url : undefined
+    last = {
+      api: lastAction.api,
+      start: lastAction.start,
+      end: lastAction.end,
+      requests: actionIndexes.slice(0, MAX_NOTE).map(function (i) { return wire(requests[i]) }),
+      ...(pageBefore === undefined ? {} : { pageBefore: pageBefore }),
+      ...(pageAfter === undefined ? {} : { pageAfter: pageAfter }),
+    }
+  }
+  // The lead stays for traces that carry no action clock: the last answered fetch/xhr, else the
+  // document. With an action, its first answered request is the lead.
+  let lead = null
+  for (const i of actionIndexes) {
+    if (leadCandidate(requests[i])) { lead = wire(requests[i]); break }
+  }
+  // The fallback lead stays for traces with no action clock. With an action, only a request it
+  // caused is the lead; an action that sent none leaves the page's own load to the row's
+  // "also answered" bucket, not to a lead that would hide it.
+  if (lead === null && lastAction === null) {
+    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 }
+      }
+    }
+    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 = wire(r)
+      if (sent) lead.sent = sent
+      if (got) lead.got = got
     }
   }
   const failing = []
@@ -369,28 +485,27 @@ for (const one of found.slice(0, MAX_TRACES)) {
     else if (navigationOpen && neverFinished(r)) pending.push(i)
     else rest.push(i)
   }
-  const keep = failing.slice(-MAX_REQUESTS).concat(api.slice(-MAX_REQUESTS))
+  // The action's own requests are kept whatever the cap: they are the row's first line.
+  const actionSet = new Set(actionIndexes)
+  const keep = failing.slice(-MAX_REQUESTS).concat(actionIndexes.slice(0, MAX_NOTE))
+    .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) {
-    const wrong = failedRequest(requests[a]) ? 0 : 1
-    const other = failedRequest(requests[b]) ? 0 : 1
-    return wrong === other ? a - b : wrong - other
+    function rank(index) {
+      if (failedRequest(requests[index])) return 0
+      return actionSet.has(index) ? 1 : 2
+    }
+    const left = rank(a)
+    const right = rank(b)
+    return left === right ? a - b : left - right
   })) {
     const r = requests[i]
     const key = r.method + ' ' + r.path + ' ' + r.status
     if (seen.has(key)) continue
     seen.add(key)
-    chosen.push({
-      method: r.method,
-      path: r.path,
-      status: r.status,
-      failure: r.failure,
-      sent: r.sent,
-      got: r.got,
-      type: r.type || undefined,
-    })
+    chosen.push(wire(r))
   }
   const consoleErrors = []
   let spec = null
@@ -420,6 +535,7 @@ for (const one of found.slice(0, MAX_TRACES)) {
     spec: spec,
     line: line,
     lead: lead,
+    lastAction: last,
     // 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).
@@ -447,6 +563,31 @@ function parseTraceRequest(value) {
         ...(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 } : {}),
+        ...(Number.isFinite(Number(r.startedAt)) ? { startedAt: Number(r.startedAt) } : {}),
+    };
+}
+/**
+ * One `lastAction` out of a `TRACE` line's json, or null when the value is not one.
+ *
+ * @param value - The line's `lastAction`.
+ * @returns The action and its requests, or null.
+ */
+function parseLastAction(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value;
+    if (typeof raw.api !== 'string' || !Number.isFinite(Number(raw.start)))
+        return null;
+    const requests = Array.isArray(raw.requests) ? raw.requests : [];
+    return {
+        api: raw.api,
+        start: Number(raw.start),
+        end: raw.end === null || raw.end === undefined ? null : Number(raw.end),
+        requests: requests
+            .map(parseTraceRequest)
+            .filter((request) => request !== null),
+        ...(typeof raw.pageBefore === 'string' ? { pageBefore: raw.pageBefore } : {}),
+        ...(typeof raw.pageAfter === 'string' ? { pageAfter: raw.pageAfter } : {}),
     };
 }
 /**
@@ -469,6 +610,7 @@ export function parseTraceArtifacts(stdout) {
             const consoleMessages = Array.isArray(raw.console) ? raw.console : [];
             const actions = Array.isArray(raw.actions) ? raw.actions : [];
             const lead = parseTraceRequest(raw.lead);
+            const lastAction = parseLastAction(raw.lastAction);
             out.push({
                 spec: typeof raw.spec === 'string' ? raw.spec : null,
                 line: typeof raw.line === 'number' ? raw.line : 0,
@@ -476,6 +618,7 @@ export function parseTraceArtifacts(stdout) {
                     .map(parseTraceRequest)
                     .filter((request) => request !== null),
                 ...(lead === null ? {} : { lead }),
+                ...(lastAction === null ? {} : { lastAction }),
                 console: consoleMessages.map(String),
                 actions: actions
                     .filter((a) => typeof a === 'object' && a !== null)
@@ -536,6 +679,26 @@ function requestLine(request) {
         : '';
     return `${head}${sent}${got}`;
 }
+/**
+ * One request as the note writes it when the body matters as much as the status: the app's own
+ * answer, printed to `gotChars`.
+ *
+ * @param request - The request.
+ * @param gotChars - How much of the response body to print.
+ * @returns The request's clause.
+ */
+function requestWithBody(request, gotChars) {
+    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), gotChars)}` : '';
+    return `${requestLabel(request)} → ${status}${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":{…}}`.
@@ -548,18 +711,27 @@ function requestLine(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}`;
+    return `the failing step sent ${requestWithBody(request, TRACE_NOTE_LEAD_GOT_CHARS)}`;
+}
+/** A request's identity in a trace: method, path and status. */
+function requestKey(request) {
+    return `${request.method} ${request.path} ${request.status}`;
+}
+/**
+ * When an action ran, relative to the first action the trace recorded — `+2.9 s`.
+ *
+ * The trace's clock starts with the worker process, so the raw value is meaningless to a reader;
+ * a relative time keeps the trace's own ordering visible without inventing a wall-clock time.
+ *
+ * @param item - The trace.
+ * @param start - The action's start, on the trace's clock.
+ * @returns The time to print.
+ */
+function actionClock(item, start) {
+    const first = item.actions?.[0]?.start;
+    if (first === undefined || !Number.isFinite(first) || start < first)
+        return `${Math.round(start)} ms`;
+    return `+${((start - first) / 1000).toFixed(1)} s`;
 }
 /** Whether a sent body is an object whose only top-level key is `data` — the wrapped-body trap. */
 function wrappedInData(text) {
@@ -589,6 +761,16 @@ function wrappedInData(text) {
  * invisible to the next proof run. The note is about the test's own API calls.
  */
 const STATIC_ASSET_PATH = /^\/(?:sw|service-worker)\.js(?:[?#]|$)|\/manifest\.webmanifest(?:[?#]|$)|\/favicon[^/]*(?:[?#]|$)|\/fonts?\//i;
+/**
+ * The PWA worker's own hashed script, the manifest's touch icons and the splash images.
+ *
+ * The worker and the shell type these `other`/`fetch`, not `script`/`image`, so
+ * {@link STATIC_ASSET_TYPES} alone never caught them: on xr-molecule-flash-m148 every failing
+ * test's row filled three of its four request slots with `GET /workbox-d8ed3718.js → 200` and
+ * `GET /icons/splash-1125x2436.svg → 200`, and the register `POST /api/users` that explains the
+ * signed-out page never appeared.
+ */
+const SHELL_FILE_PATH = /^\/workbox-[^/]*\.js(?:[?#]|$)|^\/icons\/|^\/(?:apple-touch-icon|og-image|splash)[^/]*(?:[?#]|$)/i;
 /** The build/dev output paths the page shell loads (Vite's bundle, the platform's own files). */
 const STATIC_ASSET_DIR = /^\/(?:assets|@vite|__mol)\//i;
 /** The resource types a page loads for itself rather than for the step under test. */
@@ -620,7 +802,7 @@ export function isStaticAssetRequest(request) {
     if (request.type !== undefined && STATIC_ASSET_TYPES.has(request.type))
         return true;
     const path = requestPath(request);
-    return STATIC_ASSET_PATH.test(path) || STATIC_ASSET_DIR.test(path);
+    return STATIC_ASSET_PATH.test(path) || STATIC_ASSET_DIR.test(path) || SHELL_FILE_PATH.test(path);
 }
 /**
  * Whether a trace recorded a request the server actually failed: a 4xx/5xx, or a network error.
@@ -918,11 +1100,16 @@ function missingApiPrefixSentence(request) {
  * 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.
+ * Every row opens with the test's LAST user action before the failing assertion and the requests
+ * that action caused ({@link TraceArtifact.lastAction}) — started after it, before the assertion,
+ * the app's own API calls first, each with its status and the first 200 characters of its response,
+ * then where the page went next. The trace's action clock and each request's `_monotonicTime` are
+ * the same clock, so "caused" is the trace's own fact rather than a guess from recording order.
+ * xr-molecule-flash-m148 failed 13 then 12 tests on one unnamed cause while every row led with
+ * `GET /api/tags → 200` — the Home page's own fetch after the redirect — and filled its answered
+ * slots with the PWA's `/workbox-*.js` and its `/icons/*.svg`; the register `POST /api/users`
+ * (answered 201, the page still rendering signed-out) never appeared. With no action clock, the
+ * 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
@@ -1009,17 +1196,20 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
     ];
     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.
+        // The test's LAST action before the failing assertion leads the row (m148): the requests it
+        // caused and what came back explain a page that never showed the signed-in state, while the
+        // page's own last call (a redirect target's `GET /api/tags`) and the shell's files do not.
         const lead = item.lead;
-        const isLead = (request) => lead !== undefined &&
-            request.method === lead.method &&
-            request.path === lead.path &&
-            request.status === lead.status;
+        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 : [];
+        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
         // otherwise be printed as an "answered" request with no response (m125 +29:33).
-        const requests = item.requests.filter((request) => !isStaticAssetRequest(request) && !isLead(request));
+        const requests = item.requests.filter((request) => !isStaticAssetRequest(request) && !isLead(request) && !stepKeys.has(requestKey(request)));
         const failed = requests.filter(failedRequest);
         const unanswered = requests.filter(unansweredRequest);
         const answered = requests.filter((request) => !failedRequest(request) && !unansweredRequest(request));
@@ -1030,7 +1220,27 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
             : [];
         let room = MAX_TRACE_NOTE_REQUESTS;
         const parts = [];
-        if (lead !== undefined) {
+        if (step !== undefined && !stalledNav) {
+            const head = `the test's last action was ${step.api} at ${actionClock(item, step.start)}`;
+            if (step.requests.length === 0) {
+                parts.push(`${head}, and it sent no request`);
+            }
+            else {
+                const shown = step.requests.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.
+                parts.push(`${head}, and it sent ${shown.map((request) => requestWithBody(request, TRACE_NOTE_LEAD_GOT_CHARS)).join('; ')}`);
+            }
+            // What the page did next: a navigation shows in the main frame's URL even when the app moved
+            // client-side and the network log recorded no document request.
+            if (step.pageAfter !== undefined) {
+                parts.push(step.pageBefore !== undefined && step.pageBefore !== step.pageAfter
+                    ? `the page then navigated to ${step.pageAfter}`
+                    : `the page stayed at ${step.pageAfter}`);
+            }
+        }
+        else if (lead !== undefined) {
             parts.push(leadRequestLine(lead));
             room -= 1;
         }
@@ -1052,7 +1262,12 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
                 shown.map(requestLabel).join('; '));
         }
         if (answered.length > 0 && room > 0) {
-            parts.push(`answered: ${answered.slice(0, room).map(requestLine).join('; ')}`);
+            // 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
+                ? 'also answered (started before the action)'
+                : 'answered';
+            parts.push(`${label}: ${answered.slice(0, room).map(requestLine).join('; ')}`);
         }
         if (item.console.length > 0)
             parts.push(`console: ${item.console
@@ -1104,8 +1319,9 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
     return (transportLead +
         stalledLead +
         `The platform read the failing tests' own Playwright traces from the run against ${target} ` +
-        `(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` +
+        `(what each page sent and got — first what the test's last action sent and where the page went ` +
+        `next, then the requests that failed, the ones that got no response, and its last answered ` +
+        `ones):\n` +
         `${rows.join('\n')}${more}\n` +
         (anyFailed
             ? everyFailureLacksPrefix
@@ -1119,10 +1335,12 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
                     '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.') +
+                    "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 ' +
+                    'still did not show the state the assertion waited on is the fact to read — its status ' +
+                    'and response body, not the selector. If the request is not the one the test meant — an ' +
+                    'unfollow sent where the test clicked follow — the state the action read was stale ' +
+                    'before it.') +
         prefixAdvice +
         (wrapped
             ? ' The API received a body wrapped in `data`: app-http’s `post(url, data, config)` / ' +

package/package.json

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