@molecule/api-ai-tools 1.9.2 → 1.9.3

package/dist/tools.js

@@ -359,6 +359,7 @@ async function backgroundTaskState(backend, command, seconds, ceilingMs) {
         slice,
     };
 }
+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, } from './utilities.js';
 /**
@@ -578,6 +579,35 @@ function batchFailureError(path, total, failures) {
             ? `\n\n(${omitted} more replacement${omitted === 1 ? '' : 's'} also failed and are not shown.)`
             : ''));
 }
+/**
+ * Delays between retries of the symlink guard while a sandbox's command channel is
+ * still attaching: four attempts over roughly 2.6 s (plus the commands' own time),
+ * which covers the span a freshly claimed E2B sandbox answers `SandboxNotFoundError`
+ * before its exec channel is usable (xr-molecule-flash-m120 +00:29). A plain slow
+ * answer keeps the single 300 ms retry instead — a sandbox that is gone does not
+ * come back inside five seconds.
+ */
+const SANDBOX_STARTING_BACKOFF_MS = [300, 800, 1_500];
+/**
+ * Whether an error from the sandbox's command channel says the sandbox is still
+ * STARTING rather than gone for good.
+ *
+ * A sandbox created seconds earlier answers `SandboxNotFoundError` ("Sandbox is
+ * probably not running anymore") until its channel attaches, and that message names
+ * the worse of the two causes — so a file tool refused it as if the sandbox were
+ * dead. These shapes are retried; anything else keeps the one quick retry.
+ *
+ * @param error - The error thrown by `backend.run`.
+ * @returns True when the sandbox looks like it is still coming up.
+ */
+function sandboxStillStarting(error) {
+    const err = error;
+    const name = typeof err?.name === 'string' ? err.name : '';
+    const message = typeof err?.message === 'string' ? err.message : '';
+    if (/^SandboxNotFound(?:Error)?$/i.test(name))
+        return true;
+    return /not (?:found|running)|notfound|not attached|still starting/i.test(`${name} ${message}`);
+}
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *
@@ -711,10 +741,18 @@ export function buildTools(backend, config) {
     async function checkSymlink(path) {
         if (!symlinkGuards)
             return null;
-        // One retry: the first commands on a just-attached sandbox can fail at once (X1
-        // flash-m44: three paths refused in 332 ms, the same check passing a beat later).
+        // The retry budget is failure-aware. A plain slow answer gets ONE quick retry
+        // (X1 flash-m44: three paths refused in 332 ms, the same check passing a beat
+        // later). A channel that is still ATTACHING gets longer: a sandbox created
+        // seconds earlier answers `SandboxNotFoundError` for well over 600 ms, so the
+        // fixed 2 × 300 ms budget ran out and the run's FIRST file tool was refused with
+        // "probably not running anymore" 300 ms before the same tool answered
+        // (xr-molecule-flash-m120 +00:29). Those errors are about a sandbox that is
+        // still starting, not one that is gone, so they are retried up to ~5 s.
         let lastError;
-        for (let attempt = 0; attempt < 2; attempt++) {
+        let attempts = 0;
+        for (;;) {
+            attempts++;
             const started = Date.now();
             try {
                 const result = await backend.run(`readlink -f ${shellQuote(path)} 2>/dev/null || echo ${shellQuote(path)}`, { timeout: 5000 });
@@ -728,20 +766,29 @@ export function buildTools(backend, config) {
                 lastError = Object.assign(error instanceof Error ? error : new Error(String(error)), {
                     elapsedMs: Date.now() - started,
                 });
-                if (attempt === 0)
-                    await new Promise((resolve) => setTimeout(resolve, 300));
+                const backoff = sandboxStillStarting(lastError) ? SANDBOX_STARTING_BACKOFF_MS : [];
+                const wait = backoff[attempts - 1] ?? (attempts === 1 ? 300 : undefined);
+                if (wait === undefined)
+                    break;
+                await new Promise((resolve) => setTimeout(resolve, wait));
             }
         }
         // Deny conservatively, and say what failed: "access denied" read as a forbidden path,
         // and a fixed "did not answer within 5 s" hid an error that took 332 ms.
         const err = lastError;
         const timedOut = err?.name === 'TimeoutError' || (err?.elapsedMs ?? 0) >= 4900;
-        return timedOut
-            ? 'Unable to verify path safety: the sandbox did not answer the check within 5 s (it may be ' +
+        if (timedOut) {
+            return ('Unable to verify path safety: the sandbox did not answer the check within 5 s (it may be ' +
                 'restarting or out of memory), so the path was refused to stay safe. Retry in a moment; if ' +
-                'every file tool fails this way, the sandbox needs a restart.'
-            : `Unable to verify path safety: the sandbox's command channel failed (${err?.name ?? 'Error'}: ${String(err?.message ?? err).slice(0, 160)}), ` +
-                'so the path was refused to stay safe. Retry the call; if every file tool fails this way, the sandbox needs a restart.';
+                'every file tool fails this way, the sandbox needs a restart.');
+        }
+        if (sandboxStillStarting(err)) {
+            return ('Unable to verify path safety: the sandbox is still starting (its command channel is not ' +
+                'attached yet), so the path was refused to stay safe. Retry in a few seconds — a freshly ' +
+                'created sandbox can take a moment to attach.');
+        }
+        return (`Unable to verify path safety: the sandbox's command channel failed (${err?.name ?? 'Error'}: ${String(err?.message ?? err).slice(0, 160)}), ` +
+            'so the path was refused to stay safe. Retry the call; if every file tool fails this way, the sandbox needs a restart.');
     }
     /**
      * Strip control characters and optionally redact secrets from tool output.
@@ -2506,6 +2553,13 @@ export function buildTools(backend, config) {
             // note it printed called "a lead, not a cause" — and read the early return as "stop waiting,
             // edit now", voiding a run that was still walking both times (the second wait, 224 s of a
             // 280 s budget, ended with nothing at all).
+            // How this run was started, so the note can hand over the re-run to send once it ends
+            // instead of one for now — the platform refuses a second run against the same app and
+            // database while this one walks (xr-molecule-flash-m89: the +19:59 note named a re-run
+            // and its overlap hold refused that exact run 23 s later) — and so a run narrowed to a
+            // file or two is judged against what it selected (xr-molecule-flash-m119 +42:08). Read
+            // BEFORE the loop: the running answers below are built after it closes and still need it.
+            const started = runByTask.get(taskId);
             let midRunNote = null;
             let lastCauseLookAt = startedAt - repeatingCauseLookMs();
             let exitCode = await readExit();
@@ -2537,12 +2591,7 @@ export function buildTools(backend, config) {
                     continue;
                 // The ONE predicate behind this decision and `repeatingFailureNote`'s wording, so the two
                 // cannot come to different verdicts.
-                const stopCause = earlyReturnCause(found, universalCause(causeLog, found));
-                // How this run was started, so the note can hand over the re-run to send once it ends
-                // instead of one for now — the platform refuses a second run against the same app and
-                // database while this one walks (xr-molecule-flash-m89: the +19:59 note named a re-run
-                // and its overlap hold refused that exact run 23 s later).
-                const started = runByTask.get(taskId);
+                const stopCause = earlyReturnCause(found, universalCause(causeLog, found, started?.command));
                 if (stopCause) {
                     // …and only now is the pid walk paid for.
                     repeatingCauseNoted.add(taskId);
@@ -2567,12 +2616,18 @@ export function buildTools(backend, config) {
                 // duration into a proven whole-run cause, and that one is worth returning early for.
                 if (!midRunLeadNoted.has(taskId)) {
                     midRunLeadNoted.add(taskId);
+                    // A run against the sandbox's own app is changed by an edit while it walks — the two
+                    // instructions the note and the wait's own sentence give must agree (xr-molecule-flash-
+                    // m122 +19:00: one result said editing app/src "changes the code the run is testing" and
+                    // "Start fixing it now"). The target is read off the command the task was started with.
+                    const editsInvalidateRun = started === undefined || suiteCommandTarget(started.command) === 'local';
                     midRunNote = repeatingFailureNote(found, {
                         taskId,
                         log,
                         stop: '',
                         universal: null,
                         ...(started ? { run: started } : {}),
+                        ...(editsInvalidateRun ? { editsInvalidateRun: true } : {}),
                     });
                 }
             }
@@ -2663,7 +2718,16 @@ export function buildTools(backend, config) {
                                 `each failure's own report into the log as that test fails, right under its ✘ line, ` +
                                 `not only in the summary at the end. `
                             : `Nothing has been printed yet — \`grep -n '✘' ${log} | head -40\` lists failures as they appear. `) +
-                        `Meanwhile do work that leaves the code under test alone (read the failures so far, plan the fixes): editing app/src or api/src now changes the code the run is testing, and its result no longer counts.${midRun}`,
+                        // What an edit does to this run depends on what the run MEASURES: the sandbox's own
+                        // app is re-served from app/src as it is edited, so the run's result stops counting; a
+                        // run against the deployed build is untouched by a local edit, and the executor can
+                        // spend the rest of the run fixing (xr-molecule-flash-m122 +19:00: a deployed run was
+                        // told editing changes what it tests, then handed "Start fixing it now" in the same
+                        // result — it waited out 1 min 11 s of free fixing time).
+                        (started !== undefined && suiteCommandTarget(started.command) !== 'local'
+                            ? `Meanwhile fix what it has already named: this run tests the deployed build, so editing app/src or api/src now does not change what it tests — fix the causes it has already named while it walks, run nothing against the app until it ends, then deploy once.`
+                            : `Meanwhile do work that leaves the code under test alone (read the failures so far, plan the fixes): editing app/src or api/src now changes the code the run is testing, and its result no longer counts.`) +
+                        `${midRun}`,
                 };
             }
             let output;

package/dist/trace-artifacts.d.ts

@@ -54,6 +54,12 @@ export interface TraceRequest {
     sent?: string;
     /** What came back for that 4xx, bounded the same way — the API's own error body. */
     got?: string;
+    /**
+     * The browser's own resource type (`document`, `fetch`, `xhr`, `font`, `image`, `stylesheet`,
+     * `script`, …). `document` when the request was the page load itself; when it ended in a
+     * `net::ERR_*`, nothing rendered and no selector or app request was measured.
+     */
+    type?: string;
 }
 /** One action the traced page performed, with the trace's own timing for it. */
 export interface TraceAction {
@@ -137,6 +143,36 @@ export declare const traceArtifactsScript: () => string;
  * @returns One entry per trace it printed.
  */
 export declare function parseTraceArtifacts(stdout: string): TraceArtifact[];
+/**
+ * Whether a request is one of the page shell's, not the test's (`STATIC_ASSET_PATH`).
+ *
+ * The document itself is never incidental — a page that never loaded IS the failure — and a
+ * request whose type is the app's own API (`fetch`/`xhr`) is judged by its path alone.
+ *
+ * @param request - One request a trace recorded.
+ * @returns True when the request is incidental to the step under test.
+ */
+export declare function isStaticAssetRequest(request: TraceRequest): boolean;
+/**
+ * Whether a trace recorded a request the server actually failed: a 4xx/5xx, or a network error.
+ *
+ * A 404 on a static asset is excepted: `/sw.js` and `/fonts/*` 404 on an app that never shipped
+ * them, and naming one as a failure sent m125 into writing the caching worker it had asked about.
+ * A 5xx on an asset, or a network error, still counts — the server did fail.
+ *
+ * @param request - One request a trace recorded.
+ * @returns True when the request failed in a way the note should name.
+ */
+export declare function failedRequest(request: TraceRequest): boolean;
+/**
+ * Whether a trace recorded NO response and no reason for it — a request that was aborted or still
+ * in flight when the test ended. It is not evidence that the server failed (m112 +30:45), and one
+ * the page shell made is not evidence about the step at all (m125 +29:33).
+ *
+ * @param request - One request a trace recorded.
+ * @returns True when the request is still in flight and worth naming.
+ */
+export declare function unansweredRequest(request: TraceRequest): boolean;
 /**
  * The note a failed suite run's result carries: what each failing test's page actually sent, and
  * what came back.
@@ -164,6 +200,10 @@ export declare function parseTraceArtifacts(stdout: string): TraceArtifact[];
  * traces of one `afterEach` line whose every request was `-1`, and left the favorite cause — the
  * one failure that repeated in every walk — in its "… and N more".
  *
+ * A run whose every traced page never finished its navigation leads with the browser's own
+ * 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).
+ *
  * @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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAA;IACX,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAA;IACb,kEAAkE;IAClE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CACnB;AAED,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,0FAA0F;IAC1F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAA;IACZ,6FAA6F;IAC7F,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB;;;;OAIG;IACH,OAAO,EAAE,WAAW,EAAE,CAAA;CACvB;AAED,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,sFAAsF;AACtF,eAAO,MAAM,kBAAkB,KAAK,CAAA;AAEpC,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC,iDAAiD;AACjD,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,gEAAgE;AAChE,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,MAAM,CAAA;AAKvC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,oBAAoB,QAAO,MAiQvC,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAqCnE;AAwJD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,MAAM,EAAE,MAAM,EACd,eAAe,GAAE,SAAS,MAAM,EAAO,GACtC,MAAM,GAAG,IAAI,CAmFf;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,8BAA8B,CAAA;AA2G/D,oGAAoG;AACpG,MAAM,WAAW,qBAAqB;IACpC,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5C,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAyBjC"}
+{"version":3,"file":"trace-artifacts.d.ts","sourceRoot":"","sources":["../src/trace-artifacts.ts"],"names":[],"mappings":"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"}

package/dist/trace-artifacts.js

@@ -244,9 +244,24 @@ for (const one of found.slice(0, MAX_TRACES)) {
     if (sent) r.sent = sent
     if (got) r.got = got
   }
+  // The page shell's own requests (a service worker probe, a manifest, a font) are not the
+  // failing step's dependencies: a 404 on one, or no response at all, is not a cause and takes
+  // no row (xr-molecule-flash-m125 +29:33 — "GET /sw.js; GET /fonts/ionicons.woff" sent the
+  // model to write a caching service worker into the app).
+  const SHELL_TYPE = { font: 1, image: 1, stylesheet: 1, script: 1, manifest: 1 }
+  function shellPath(path) {
+    return /^\\/(?:sw|service-worker)\\.js(?:[?#]|$)|\\/manifest\\.webmanifest(?:[?#]|$)|\\/favicon[^/]*(?:[?#]|$)|\\/fonts?\\//.test(path) ||
+      /^\\/(?:assets|@vite|__mol)\\//.test(path)
+  }
+  function shellRequest(r) {
+    if (r.type === 'document') return false
+    return SHELL_TYPE[r.type] === 1 || shellPath(r.path)
+  }
   // A failed request: a 4xx/5xx, or no response at all WITH Playwright's error text (a refused
-  // connection). No response and no text is an aborted/pending request, not a failure.
+  // connection). No response and no text is an aborted/pending request, not a failure. A 404 on
+  // the page shell is excepted, for the reason above.
   function failedRequest(r) {
+    if (shellRequest(r) && r.status === 404) return false
     return r.status >= 400 || (r.status <= 0 && typeof r.failure === 'string')
   }
   const failing = []
@@ -254,6 +269,8 @@ for (const one of found.slice(0, MAX_TRACES)) {
   const rest = []
   for (let i = 0; i < requests.length; i++) {
     const r = requests[i]
+    // An answered/aborted shell request is no evidence at all — do not spend a kept row on it.
+    if (shellRequest(r) && !failedRequest(r)) continue
     if (failedRequest(r)) failing.push(i)
     else if (r.type === 'fetch' || r.type === 'xhr' || r.type === 'document') api.push(i)
     else rest.push(i)
@@ -277,6 +294,7 @@ for (const one of found.slice(0, MAX_TRACES)) {
       failure: r.failure,
       sent: r.sent,
       got: r.got,
+      type: r.type || undefined,
     })
   }
   // The page's own actions, timed. before/after pair on the call id, and only the LIBRARY
@@ -365,6 +383,7 @@ export function parseTraceArtifacts(stdout) {
                     ...(typeof r.failure === 'string' && r.failure ? { failure: r.failure } : {}),
                     ...(typeof r.sent === 'string' && r.sent ? { sent: r.sent } : {}),
                     ...(typeof r.got === 'string' && r.got ? { got: r.got } : {}),
+                    ...(typeof r.type === 'string' && r.type ? { type: r.type } : {}),
                 })),
                 console: consoleMessages.map(String),
                 actions: actions
@@ -442,15 +461,77 @@ function wrappedInData(text) {
         return /^\{\s*"data"\s*:/.test(text.trim());
     }
 }
-/** Whether a trace recorded a request the server actually failed: a 4xx/5xx, or a network error. */
-function failedRequest(request) {
+/**
+ * A request the page made for its own shell rather than for the step under test: the PWA's
+ * service worker (`/sw.js` — the scaffold registers one there and a project without one answers
+ * 404), the manifest, a favicon, the fonts a stylesheet pulls, and Vite's/dev's own asset paths.
+ *
+ * These are not the failing step's dependencies, so neither a missing response nor a 404 on one is
+ * a cause. xr-molecule-flash-m125 (+29:33) was handed "no response recorded — still in flight when
+ * the test ended … GET /sw.js; GET /fonts/ionicons.woff" and answered it by writing a CACHING
+ * service worker into the app — in front of `/assets/*`, exactly what makes a redeployed fix
+ * 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 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. */
+const STATIC_ASSET_TYPES = new Set(['font', 'image', 'stylesheet', 'script', 'manifest']);
+/** The path part of a request, for the static-asset test. */
+function requestPath(request) {
+    const url = String(request.path ?? '');
+    try {
+        const parsed = new URL(url, 'http://trace.local');
+        return parsed.pathname;
+    }
+    catch (_error) {
+        // Not a URL this can parse: judge the text itself, up to any query or fragment.
+        return url.split(/[?#]/)[0] ?? url;
+    }
+}
+/**
+ * Whether a request is one of the page shell's, not the test's (`STATIC_ASSET_PATH`).
+ *
+ * The document itself is never incidental — a page that never loaded IS the failure — and a
+ * request whose type is the app's own API (`fetch`/`xhr`) is judged by its path alone.
+ *
+ * @param request - One request a trace recorded.
+ * @returns True when the request is incidental to the step under test.
+ */
+export function isStaticAssetRequest(request) {
+    if (request.type === 'document')
+        return false;
+    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);
+}
+/**
+ * Whether a trace recorded a request the server actually failed: a 4xx/5xx, or a network error.
+ *
+ * A 404 on a static asset is excepted: `/sw.js` and `/fonts/*` 404 on an app that never shipped
+ * them, and naming one as a failure sent m125 into writing the caching worker it had asked about.
+ * A 5xx on an asset, or a network error, still counts — the server did fail.
+ *
+ * @param request - One request a trace recorded.
+ * @returns True when the request failed in a way the note should name.
+ */
+export function failedRequest(request) {
+    if (isStaticAssetRequest(request) && request.status === 404)
+        return false;
     return request.status >= 400 || (request.status <= 0 && request.failure !== undefined);
 }
 /**
  * Whether a trace recorded NO response and no reason for it — a request that was aborted or still
- * in flight when the test ended. It is not evidence that the server failed (m112 +30:45).
+ * in flight when the test ended. It is not evidence that the server failed (m112 +30:45), and one
+ * the page shell made is not evidence about the step at all (m125 +29:33).
+ *
+ * @param request - One request a trace recorded.
+ * @returns True when the request is still in flight and worth naming.
  */
-function unansweredRequest(request) {
+export function unansweredRequest(request) {
+    if (isStaticAssetRequest(request))
+        return false;
     return request.status <= 0 && request.failure === undefined;
 }
 /**
@@ -508,9 +589,16 @@ function repeatsEarlierFailure(item, earlier) {
  * 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".
+ *
+ * A request the page shell made (m125 +29:33: `/sw.js`, a font) is not evidence about the step
+ * either, answered or not.
+ *
+ * @param item - One traced failure.
+ * @returns True when the trace holds a request or console error worth a row.
  */
 function traceRowEvidence(item) {
-    return item.console.length > 0 || item.requests.some((request) => !unansweredRequest(request));
+    return (item.console.length > 0 ||
+        item.requests.some((request) => !isStaticAssetRequest(request) && !unansweredRequest(request)));
 }
 /**
  * The note's row order: a row with a REAL failure first, then a row whose failure an earlier walk
@@ -525,6 +613,51 @@ function traceRowTier(item, earlier) {
         return 1;
     return 2;
 }
+/** A browser-level transport failure Chromium and Firefox both record (`net::ERR_*`). */
+const NETWORK_ERROR = /\bnet::ERR_[A-Z0-9_]+\b/;
+/**
+ * Whether the trace's page never finished a navigation: its own `Frame.goto` has no end time.
+ *
+ * A page that never loaded is not a set of app failures: a `page.goto` timeout on a document that
+ * ended in a `net::ERR_*` is the one line that explains every test that timed out on it, and it is
+ * what m118's preview walk never saw (`net::ERR_CONTENT_DECODING_FAILED` on a gzipped HTML body).
+ *
+ * @param item - One traced failure.
+ * @returns True when the page's navigation started and never ended.
+ */
+function navigationNeverFinished(item) {
+    return item.actions?.some((action) => /\.goto$/.test(action.api) && action.end === null) ?? false;
+}
+/**
+ * The `net::ERR_*` the traced pages recorded, with the request it hit — or null.
+ *
+ * The request's own `_failureText` is preferred (Playwright records the browser's error there);
+ * a console error is the fallback, because the browser logs the same failure as
+ * `Failed to load resource: net::ERR_…` and a page that timed out on its document has no request
+ * failure text at all.
+ *
+ * @param items - The traces the note is about.
+ * @returns The first transport failure, or null when the browser reported none.
+ */
+function transportFailure(items) {
+    for (const item of items) {
+        const document = item.requests.find((request) => request.type === 'document');
+        const failed = item.requests.find((request) => request.failure !== undefined && NETWORK_ERROR.test(request.failure));
+        if (failed !== undefined) {
+            const error = NETWORK_ERROR.exec(failed.failure ?? '')?.[0] ?? failed.failure ?? '';
+            return { error, where: failed.path };
+        }
+        for (const line of item.console) {
+            const error = NETWORK_ERROR.exec(line)?.[0];
+            if (error !== undefined)
+                return {
+                    error,
+                    where: document?.path ?? item.requests[0]?.path ?? 'the page',
+                };
+        }
+    }
+    return null;
+}
 /**
  * The note a failed suite run's result carries: what each failing test's page actually sent, and
  * what came back.
@@ -552,6 +685,10 @@ function traceRowTier(item, earlier) {
  * traces of one `afterEach` line whose every request was `-1`, and left the favorite cause — the
  * one failure that repeated in every walk — in its "… and N more".
  *
+ * A run whose every traced page never finished its navigation leads with the browser's own
+ * 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).
+ *
  * @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
@@ -585,9 +722,12 @@ export function failureTraceNote(items, target, earlierFailures = []) {
     const anyFailed = traced.some((item) => item.requests.some(failedRequest));
     const rows = [];
     for (const [index, item] of traced.entries()) {
-        const failed = item.requests.filter(failedRequest);
-        const unanswered = item.requests.filter(unansweredRequest);
-        const answered = item.requests.filter((request) => !failedRequest(request) && !unansweredRequest(request));
+        // The page shell's own requests take no row, in any bucket: an aborted `/sw.js` would
+        // otherwise be printed as an "answered" request with no response (m125 +29:33).
+        const requests = item.requests.filter((request) => !isStaticAssetRequest(request));
+        const failed = requests.filter(failedRequest);
+        const unanswered = requests.filter(unansweredRequest);
+        const answered = requests.filter((request) => !failedRequest(request) && !unansweredRequest(request));
         let room = MAX_TRACE_NOTE_REQUESTS;
         const parts = [];
         if (failed.length > 0) {
@@ -617,7 +757,26 @@ export function failureTraceNote(items, target, earlierFailures = []) {
     const more = distinct.size > traced.length
         ? `\n  … and ${distinct.size - traced.length} more traced failures`
         : '';
-    return (`The platform read the failing tests' own Playwright traces from the run against ${target} ` +
+    // A run whose pages never loaded has one cause, and it is not in the app: every traced failure is
+    // a `page.goto` that timed out on a document the browser could not load. The transport error is
+    // the first line the executor needs — m118 (+37:09) read 14 goto timeouts as app failures while
+    // the trace held `net::ERR_CONTENT_DECODING_FAILED` on every one.
+    const transport = candidates.length > 0 && candidates.every(navigationNeverFinished)
+        ? transportFailure(candidates)
+        : null;
+    const transportLead = transport === null
+        ? ''
+        : `Every failure this run traced is the same browser TRANSPORT failure: \`page.goto\` timed out ` +
+            `because the document at ${transport.where} ended \`${transport.error}\` — the page never ` +
+            `loaded, so none of these failures is the app's code or a selector. ` +
+            (transport.error === 'net::ERR_CONTENT_DECODING_FAILED'
+                ? 'A body whose gzip `content-encoding` no longer matches its bytes does this; a ' +
+                    '`vite preview` over a build must be started with ' +
+                    '`MOL_E2E_PREVIEW_PLUGIN=0 npx vite preview --port 4173 --strictPort`. '
+                : '') +
+            'Fix the server before the app.\n\n';
+    return (transportLead +
+        `The platform read the failing tests' own Playwright traces from the run against ${target} ` +
         `(what each page sent and got: the requests that failed, the ones that got no response, and ` +
         `its last answered ones):\n` +
         `${rows.join('\n')}${more}\n` +