@diegosouzacdv/jev-browser-mcp 0.7.0 → 0.7.1

package/mcp_servers/jev-browser-npm/src/flow.mjs

@@ -64,7 +64,7 @@ const FLOW_OPTION_KEYS = new Set([
   "color_scheme", "geolocation", "screenshot_on_success", "record_video", "trace_on_success",
   "continue_from_current_page", "reuse_page", "reuse_page_match", "return_snapshot", "screenshot_on_failure", "snapshot_include_hidden", "include_unnamed_controls", "snapshot_scope", "step_timeout_seconds", "stop_on_expected",
   "trace_on_failure", "console_levels", "fresh_context", "clear_storage", "wait_for_http", "storage_state",
-  "ready",
+  "ready", "capture_network", "capture_network_url_contains",
 ]);
 const MUTATING_LABEL = /\b(?:save|submit|issue|emit|cancel|delete|remove|void|confirm|approve|pay|send|generate|create|update|finalize|yes|okay|salvar|gravar|emitir|cancelar|excluir|apagar|remover|estornar|confirmar|aprovar|pagar|enviar|gerar|criar|atualizar|finalizar|sim)\b/i;
 
@@ -226,10 +226,13 @@ function actionSchemas(semanticTarget) {
         confirm_modal: { required: ["expected_text", "button"], optional: [...semanticTarget, "trigger", "confirm", "timeout_seconds"] },
         check: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
         uncheck: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
-        navigate_menu: { required: ["path"], optional: ["toggle_selector", "timeout_seconds"] },
-        assert_network: { required: ["url_contains", "method", "status"], optional: ["message_contains", "timeout_seconds", "timeout_ms"] },
-        assert_ws: { required: ["url_contains"], optional: ["message_contains", "json", "close_code", "timeout_seconds", "timeout_ms"] },
-        wait_for_request: { required: ["url"], optional: ["method", "status", "timeout_seconds", "timeout_ms"] },
+        navigate_menu: { required: [], optional: ["path", "screen", "toggle_selector", "timeout_seconds"] },
+        assert_network: { required: ["url_contains", "method", "status"], optional: ["message_contains", "timeout_seconds", "timeout_ms"] },
+        assert_ws: { required: ["url_contains"], optional: ["message_contains", "json", "close_code", "timeout_seconds", "timeout_ms"] },
+        wait_for_request: { required: ["url"], optional: ["method", "status", "timeout_seconds", "timeout_ms"] },
+        http_request: { required: ["url"], optional: ["method", "include_body", "timeout_seconds", "timeout_ms"] },
+        inspect_cookies: { required: [], optional: ["timeout_seconds", "timeout_ms"] },
+        read_angular_state: { required: [], optional: ["timeout_seconds", "timeout_ms"] },
         extract: { required: ["as"], optional: [...semanticTarget, "source", "attribute", "sensitive", "timeout_seconds", "timeout_ms"] },
         evaluate: { required: ["expression"], optional: ["as", "timeout_seconds", "timeout_ms"] },
         screenshot: { required: [], optional: ["full_page", "timeout_seconds", "timeout_ms"] },
@@ -257,21 +260,37 @@ function actionSchemas(semanticTarget) {
         };
 }
 
-export function describeBrowserActions() {
+export function describeBrowserActions() {
   const semanticTarget = ["frame", "comment", "within", "index", "near", "label", "placeholder", "title", "text", "test_id", "selector", "target_text", "role", "name", "name_match", "target_page"];
   const schemas = actionSchemas(semanticTarget);
-  return {
-    actions: Object.fromEntries(Object.entries(schemas).map(([action, schema]) => [action, {
-      required: [...schema.required],
-      optional: [...new Set([...schema.optional, "timeout_ms", "mutating", "screenshot"])],
-    }])),
+  return {
+    required_flow_fields: ["flow", "candidate_plans"],
+    candidate_plan: { required: ["description", "steps"], optional: ["comment", "when"] },
+    actions: Object.fromEntries(Object.entries(schemas).map(([action, schema]) => {
+      const contract = {
+        required: [...schema.required],
+        optional: [...new Set([...schema.optional, "timeout_ms", "mutating", "screenshot"])],
+      };
+      if (action === "extract") contract.conditional_required = { attribute: "required when source is attribute" };
+      if (action === "type") contract.conditional_required = { text: "exactly one of text or text_env is required" };
+      if (action === "navigate_menu") contract.conditional_required = { path: "exactly one of path or screen is required" };
+      if (action === "select_option") contract.conditional_required = { option: "exactly one of option, value or label_contains is required" };
+      return [action, contract];
+    })),
     options: [...FLOW_OPTION_KEYS],
     option_shapes: {
+      capture_network: ["errors", "all", "none"],
+      capture_network_url_contains: "optional URL substring filter for capture_network=all",
+      local_only: "required for http_request, read_angular_state and inspect_cookies; only localhost loopback is allowed",
       ready: ["network_idle", { hidden_text: "text that must disappear" }, { selector: "CSS selector", has_value: true }],
       return_snapshot: ["diff", "full", "none"],
       include_unnamed_controls: "boolean; false by default",
       reuse_page_match: ["url", "path"],
     },
+    step_shapes: {
+      frame: ["first", { url_contains: "iframe URL substring" }, "exact iframe name or title"],
+      navigate_menu: ["path: menu label array", "screen: SAFI Acesso Rápido name or screen code"],
+    },
     expected_outcome: {
       text: "string description or {text: string} assertion",
       request: "{request: 'PUT */path', status: 200, message_contains?: string}; request may include a method prefix",
@@ -285,10 +304,71 @@ export function describeBrowserActions() {
       confirm_modal: { trigger: "button accessible name", confirm: "button", expected_text: "required exact safety phrase" },
     },
     placeholders: "Use {name}; declare params.name or extract it before use. Unknown and {{double-brace}} placeholders are rejected.",
-  };
-}
-
-export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps = settings.browser.maxFlowSteps) {
+  };
+}
+
+export function collectFlowContractIssues({ flow, candidatePlans }) {
+  const issues = [];
+  if (typeof flow !== "string" || !flow.trim()) issues.push("flow: required non-empty string");
+  if (!isRecord(candidatePlans) || !Object.keys(candidatePlans).length) {
+    issues.push("candidate_plans: required non-empty object");
+    return issues;
+  }
+  const schemas = actionSchemas(["frame", "comment", "within", "index", "near", ...LOCATOR_FIELDS, "target_text", "role", "name", "name_match", "target_page"]);
+  for (const [planId, plan] of Object.entries(candidatePlans)) {
+    if (!isRecord(plan)) {
+      issues.push(`candidate_plans.${planId}: must be an object`);
+      continue;
+    }
+    if (typeof plan.description !== "string" || !plan.description.trim()) issues.push(`candidate_plans.${planId}.description: required non-empty string`);
+    if (plan.when !== undefined && (!isRecord(plan.when) || typeof plan.when.visible !== "string" || !plan.when.visible.trim())) {
+      issues.push(`candidate_plans.${planId}.when.visible: required non-empty string when is provided`);
+    }
+    if (!Array.isArray(plan.steps) || !plan.steps.length) {
+      issues.push(`candidate_plans.${planId}.steps: required non-empty array`);
+      continue;
+    }
+    for (const [index, step] of plan.steps.entries()) {
+      const prefix = `candidate_plans.${planId}.steps[${index}]`;
+      if (!isRecord(step) || typeof step.action !== "string") {
+        issues.push(`${prefix}.action: required supported action`);
+        continue;
+      }
+      let normalizedStep;
+      try { normalizedStep = normalizeStepAliases(step); }
+      catch (error) {
+        issues.push(`${prefix}: ${error instanceof Error ? error.message : "invalid aliases"}`);
+        normalizedStep = step;
+      }
+      const schema = schemas[normalizedStep.action];
+      if (!schema) {
+        issues.push(`${prefix}.action: unsupported action ${JSON.stringify(normalizedStep.action)}`);
+        continue;
+      }
+      for (const field of schema.required) {
+        if (!Object.hasOwn(normalizedStep, field)) issues.push(`${prefix}.${field}: required for ${normalizedStep.action}`);
+      }
+      if (normalizedStep.action === "extract" && normalizedStep.source === "attribute" && !Object.hasOwn(normalizedStep, "attribute")) {
+        issues.push(`${prefix}.attribute: required when extract.source is attribute`);
+      }
+      if (normalizedStep.action === "type"
+        && (Object.hasOwn(normalizedStep, "text") === Object.hasOwn(normalizedStep, "text_env"))) {
+        issues.push(`${prefix}: exactly one of text or text_env is required for type`);
+      }
+      if (normalizedStep.action === "navigate_menu"
+        && (Object.hasOwn(normalizedStep, "path") === Object.hasOwn(normalizedStep, "screen"))) {
+        issues.push(`${prefix}: exactly one of path or screen is required for navigate_menu`);
+      }
+      if (normalizedStep.action === "select_option"
+        && ["option", "value", "label_contains"].filter((field) => Object.hasOwn(normalizedStep, field)).length !== 1) {
+        issues.push(`${prefix}: exactly one of option, value or label_contains is required for select_option`);
+      }
+    }
+  }
+  return issues;
+}
+
+export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps = settings.browser.maxFlowSteps) {
   if (!isRecord(candidatePlans)) throw new JevBrowserError("candidate_plans must be an object");
   if (Object.keys(candidatePlans).length > settings.jev.maxActionCount) {
     throw new JevBrowserError("candidate_plans exceeds the configured candidate limit");
@@ -482,12 +562,18 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         if (!step.role) step.role = "checkbox";
         if (action === "uncheck" && step.role === "radio") throw new JevBrowserError("uncheck does not support radio controls");
       }
-      if (action === "navigate_menu") {
-        if (!Array.isArray(rawStep.path) || rawStep.path.length === 0 || rawStep.path.length > 8) {
-          throw new JevBrowserError("navigate_menu path must contain between 1 and 8 menu labels");
-        }
-        step.path = rawStep.path.map((label) => requiredText(label, "menu path label", settings.jev.maxActionDescriptionChars));
-        step.toggleSelector = rawStep.toggle_selector === undefined
+      if (action === "navigate_menu") {
+        if ((rawStep.path === undefined) === (rawStep.screen === undefined)) {
+          throw new JevBrowserError("navigate_menu needs exactly one of path or screen");
+        }
+        if (rawStep.path !== undefined) {
+          if (!Array.isArray(rawStep.path) || rawStep.path.length === 0 || rawStep.path.length > 8) {
+            throw new JevBrowserError("navigate_menu path must contain between 1 and 8 menu labels");
+          }
+          step.path = rawStep.path.map((label) => requiredText(label, "menu path label", settings.jev.maxActionDescriptionChars));
+        }
+        if (rawStep.screen !== undefined) step.screen = requiredText(rawStep.screen, "quick access screen name or code", settings.jev.maxActionDescriptionChars);
+        step.toggleSelector = rawStep.toggle_selector === undefined
           ? "#open_btn"
           : requiredText(rawStep.toggle_selector, "toggle_selector", settings.jev.maxActionDescriptionChars);
       }
@@ -577,15 +663,24 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         if (!step.messageContains && !step.json && rawStep.close_code === undefined) throw new JevBrowserError("assert_ws needs message_contains, json, or close_code");
         step.closeCode = rawStep.close_code;
       }
-      if (action === "wait_for_request") {
-        step.urlPattern = requiredText(rawStep.url, "wait_for_request url", settings.jev.maxActionDescriptionChars);
+      if (action === "wait_for_request") {
+        step.urlPattern = requiredText(rawStep.url, "wait_for_request url", settings.jev.maxActionDescriptionChars);
         step.method = rawStep.method === undefined ? undefined : requiredText(rawStep.method, "request method", 16).toUpperCase();
         if (step.method && !/^[A-Z]+$/.test(step.method)) throw new JevBrowserError("wait_for_request method must contain letters only");
         if (rawStep.status !== undefined && (!Number.isSafeInteger(rawStep.status) || rawStep.status < 100 || rawStep.status > 599)) {
           throw new JevBrowserError("wait_for_request status must be an HTTP status from 100 to 599");
-        }
-        step.status = rawStep.status;
-      }
+        }
+        step.status = rawStep.status;
+      }
+      if (action === "http_request") {
+        step.url = requiredText(rawStep.url, "http_request URL", settings.jev.maxActionDescriptionChars);
+        step.method = rawStep.method === undefined ? "GET" : requiredText(rawStep.method, "http_request method", 16).toUpperCase();
+        if (step.method !== "GET") throw new JevBrowserError("http_request supports GET only");
+        if (rawStep.include_body !== undefined && typeof rawStep.include_body !== "boolean") {
+          throw new JevBrowserError("http_request include_body must be a boolean");
+        }
+        step.includeBody = rawStep.include_body ?? false;
+      }
       if (action === "evaluate") {
         step.expression = requiredText(rawStep.expression, "read-only expression", 256);
         if (!/^(?:window|document|navigator|location)(?:\.[A-Za-z_$][A-Za-z0-9_$]*){1,8}$/.test(step.expression)) {
@@ -744,7 +839,13 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
           throw new JevBrowserError(`${action} labels must distinguish liked and unliked state`);
         }
       }
-      if (rawStep.frame !== undefined) step.frame = requiredText(rawStep.frame, "frame name", settings.jev.maxActionDescriptionChars);
+      if (rawStep.frame !== undefined) {
+        if (rawStep.frame === "first") step.frame = "first";
+        else if (isRecord(rawStep.frame)) {
+          exactKeys(rawStep.frame, ["url_contains"], [], "frame");
+          step.frame = { urlContains: requiredText(rawStep.frame.url_contains, "frame URL substring", settings.jev.maxActionDescriptionChars) };
+        } else step.frame = requiredText(rawStep.frame, "frame name", settings.jev.maxActionDescriptionChars);
+      }
       return step;
     });
     plans[id] = { description, steps, ...(rawPlan.when ? { when: { visible: rawPlan.when.visible } } : {}) };
@@ -958,10 +1059,18 @@ function resolveFlowOptions(rawOptions, settings) {
   if (storageState !== undefined && !/^[A-Za-z0-9_-]+$/.test(storageState)) {
     throw new JevBrowserError("options.storage_state must be a simple account name using letters, numbers, _ or -");
   }
-  if (storageState && (rawOptions.fresh_context || rawOptions.clear_storage)) {
-    throw new JevBrowserError("options.storage_state cannot be combined with fresh_context or clear_storage");
-  }
-  let reportPath;
+  if (storageState && (rawOptions.fresh_context || rawOptions.clear_storage)) {
+    throw new JevBrowserError("options.storage_state cannot be combined with fresh_context or clear_storage");
+  }
+  const configuredNetworkErrors = rawOptions.capture_network_errors ?? defaults.captureNetworkErrors;
+  const configuredNetworkErrorBodies = rawOptions.capture_network_error_bodies ?? defaults.captureNetworkErrorBodies;
+  const captureNetwork = rawOptions.capture_network ?? (configuredNetworkErrors || configuredNetworkErrorBodies ? "errors" : "none");
+  if (!new Set(["none", "errors", "all"]).has(captureNetwork)) {
+    throw new JevBrowserError("options.capture_network must be none, errors, or all");
+  }
+  const captureNetworkUrlContains = rawOptions.capture_network_url_contains === undefined
+    ? undefined : requiredText(rawOptions.capture_network_url_contains, "capture_network_url_contains", settings.jev.maxActionDescriptionChars);
+  let reportPath;
   if (rawOptions.report_path !== undefined) {
     if (typeof rawOptions.report_path !== "string" || !path.isAbsolute(rawOptions.report_path)) {
       throw new JevBrowserError("options.report_path must be an absolute path inside the configured artifact directory");
@@ -977,8 +1086,10 @@ function resolveFlowOptions(rawOptions, settings) {
     blockFonts: rawOptions.block_fonts ?? defaults.blockFonts,
     busySelectors: Object.freeze(busySelectors),
     captureConsoleErrors: rawOptions.capture_console_errors ?? defaults.captureConsoleErrors,
-    captureNetworkErrorBodies: rawOptions.capture_network_error_bodies ?? defaults.captureNetworkErrorBodies,
-    captureNetworkErrors: rawOptions.capture_network_errors ?? defaults.captureNetworkErrors,
+    captureNetworkErrorBodies: captureNetwork !== "none" && configuredNetworkErrorBodies,
+    captureNetworkErrors: captureNetwork === "errors" || captureNetwork === "all",
+    captureNetwork,
+    captureNetworkUrlContains,
     dryRun: rawOptions.dry_run ?? false,
     fastPath: rawOptions.fast_path ?? defaults.fastPath,
     localOnly: rawOptions.local_only ?? defaults.localOnly,
@@ -1145,9 +1256,36 @@ function providerSafeSnapshot(snapshot, secrets) {
     });
 }
 
-function localHostOnly(url) {
-  return new Set(["localhost", "127.0.0.1", "::1", "[::1]"]).has(new URL(url).hostname.toLowerCase());
-}
+function localHostOnly(url) {
+  return new Set(["localhost", "127.0.0.1", "::1", "[::1]"]).has(new URL(url).hostname.toLowerCase());
+}
+
+const SAFE_RESPONSE_HEADER_NAMES = new Set([
+  "cache-control", "content-length", "content-type", "date", "etag", "last-modified", "retry-after", "vary",
+]);
+
+function safeResponseHeaders(headers) {
+  return Object.fromEntries(Object.entries(headers || {})
+    .filter(([name, value]) => SAFE_RESPONSE_HEADER_NAMES.has(name.toLowerCase()) && typeof value === "string")
+    .map(([name, value]) => [name.toLowerCase(), value.slice(0, 256)]));
+}
+
+function assertLocalDebugPage(page, localOnly, action) {
+  const currentUrl = page.url();
+  if (!localOnly || !currentUrl || currentUrl === "about:blank" || !localHostOnly(currentUrl)) {
+    throw new JevBrowserError(`${action} requires options.local_only: true and a localhost page`);
+  }
+}
+
+function redactLocalPayload(value) {
+  if (Array.isArray(value)) return value.map(redactLocalPayload);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    /(?:auth|cookie|credential|secret|password|token|session|user|usuario|nome|email|cpf|cnpj|matricula|identity)/i.test(key)
+      ? "[redacted]" : redactLocalPayload(item),
+  ]));
+}
 
 async function resolveFakeMediaPath(fakeMedia, settings) {
   if (!fakeMedia) return undefined;
@@ -1665,12 +1803,17 @@ async function evaluateExpectedOutcome(expected, snapshot, networkTracker, marke
   return checks;
 }
 
-function createNetworkTracker(page, settings, loginUrlContains = []) {
-  const active = new Map();
-  const history = [];
+function createNetworkTracker(page, settings, loginUrlContains = [], watchPatterns = []) {
+  const active = new Map();
+  const history = [];
+  const watchedHistory = [];
   const websocketHistory = [];
   const websocketUrls = new Map();
   const websocketObserverPromises = new Set();
+  const blockedCookieEvents = [];
+  const cdpRequestUrls = new Map();
+  const cdpSessions = new Set();
+  const pendingHeaderReads = new Set();
   const ignored = new Set();
   let sequence = 0;
   const shouldIgnore = (request) => {
@@ -1684,21 +1827,41 @@ function createNetworkTracker(page, settings, loginUrlContains = []) {
       return undefined;
     }
     if (ignored.has(request)) return undefined;
-    const entry = { sequence: ++sequence, type, url: request.url(), method: request.method(), at: performance.now(), request };
-    if (type === "request") active.set(request, entry);
-    else if (type === "finished" || type === "failed") active.delete(request);
-    history.push(entry);
-    const historyLimit = settings.browser.maxNetworkHistoryEvents;
-    if (history.length > historyLimit) history.splice(0, history.length - historyLimit);
+    const startedAt = active.get(request)?.at;
+    const entry = {
+      sequence: ++sequence, type, url: request.url(), method: request.method(),
+      resourceType: request.resourceType(), at: performance.now(), request,
+    };
+    if (startedAt !== undefined && type !== "request") entry.durationMs = Math.max(0, entry.at - startedAt);
+    if (type === "request") active.set(request, entry);
+    else if (type === "finished" || type === "failed") {
+      const original = active.get(request);
+      if (original && entry.durationMs !== undefined) original.durationMs = entry.durationMs;
+      active.delete(request);
+    }
+    history.push(entry);
+    const historyLimit = settings.browser.maxNetworkHistoryEvents;
+    if (history.length > historyLimit) history.splice(0, history.length - historyLimit);
+    if (watchPatterns.some((pattern) => pattern.includes("*")
+      ? urlPatternMatcher(pattern).test(entry.url) : entry.url.includes(pattern))) {
+      watchedHistory.push(entry);
+      if (watchedHistory.length > historyLimit) watchedHistory.splice(0, watchedHistory.length - historyLimit);
+    }
     return entry;
   };
   const onRequest = (request) => record("request", request);
-  const onResponse = (response) => {
-    const entry = record("response", response.request());
-    if (!entry) return;
-    entry.response = response;
-    entry.status = response.status();
-  };
+  const onResponse = (response) => {
+    const entry = record("response", response.request());
+    if (!entry) return;
+    entry.response = response;
+    entry.status = response.status();
+    const requestEntry = active.get(response.request());
+    if (requestEntry && entry.durationMs !== undefined) requestEntry.durationMs = entry.durationMs;
+    const headerRead = Promise.resolve().then(() => response.allHeaders())
+      .then((headers) => { entry.responseHeaders = safeResponseHeaders(headers); }).catch(() => {});
+    pendingHeaderReads.add(headerRead);
+    void headerRead.finally(() => pendingHeaderReads.delete(headerRead));
+  };
   const onFinished = (request) => record("finished", request);
   const onFailed = (request) => record("failed", request);
   const trackedPages = new Set();
@@ -1717,9 +1880,41 @@ function createNetworkTracker(page, settings, loginUrlContains = []) {
   };
   const attachCdpWebSocketObserver = async (trackedPage) => {
     try {
-      const session = await trackedPage.context().newCDPSession(trackedPage);
-      await session.send("Network.enable");
-      session.on("Network.webSocketCreated", ({ requestId, url }) => websocketUrls.set(requestId, url));
+      const session = await trackedPage.context().newCDPSession(trackedPage);
+      cdpSessions.add(session);
+      await session.send("Network.enable");
+      session.on("Network.requestWillBeSent", ({ requestId, request }) => {
+        if (request?.url) {
+          cdpRequestUrls.set(requestId, request.url);
+          while (cdpRequestUrls.size > settings.browser.maxNetworkHistoryEvents) {
+            cdpRequestUrls.delete(cdpRequestUrls.keys().next().value);
+          }
+        }
+      });
+      session.on("Network.responseReceivedExtraInfo", ({ requestId, statusCode, headers, blockedCookies }) => {
+        const url = cdpRequestUrls.get(requestId);
+        if (!url) return;
+        const blocked = Array.isArray(blockedCookies) ? blockedCookies.map(({ cookie, blockedReasons }) => ({
+          name: String(cookie?.name || "").slice(0, 128),
+          domain: String(cookie?.domain || "").slice(0, 255),
+          path: String(cookie?.path || "").slice(0, 256),
+          secure: Boolean(cookie?.secure),
+          http_only: Boolean(cookie?.httpOnly),
+          same_site: cookie?.sameSite,
+          blocked_reasons: Array.isArray(blockedReasons) ? blockedReasons.map((reason) => String(reason).slice(0, 128)) : [],
+        })) : [];
+        if (blocked.length) {
+          blockedCookieEvents.push({ sequence: ++sequence, url, status: statusCode, cookies: blocked });
+          if (blockedCookieEvents.length > settings.browser.maxNetworkHistoryEvents) {
+            blockedCookieEvents.splice(0, blockedCookieEvents.length - settings.browser.maxNetworkHistoryEvents);
+          }
+        }
+        const safeHeaders = safeResponseHeaders(headers);
+        const matching = [...history, ...watchedHistory].reverse().find((event) => event.type === "response" && event.url === url);
+        if (matching && Object.keys(safeHeaders).length) matching.responseHeaders = safeHeaders;
+        cdpRequestUrls.delete(requestId);
+      });
+      session.on("Network.webSocketCreated", ({ requestId, url }) => websocketUrls.set(requestId, url));
       session.on("Network.webSocketFrameReceived", ({ requestId, response }) => {
         if (response?.opcode !== 8 || typeof response.payloadData !== "string") return;
         try {
@@ -1732,7 +1927,10 @@ function createNetworkTracker(page, settings, loginUrlContains = []) {
         } catch { /* A non-binary close payload has no status code. */ }
       });
       session.on("Network.webSocketClosed", ({ requestId }) => websocketUrls.delete(requestId));
-      trackedPage.once("close", () => { void session.detach().catch(() => {}); });
+      trackedPage.once("close", () => {
+        cdpSessions.delete(session);
+        void session.detach().catch(() => {});
+      });
     } catch {
       // WebSocket close-code assertions are available only on Chromium CDP sessions.
     }
@@ -1760,15 +1958,18 @@ function createNetworkTracker(page, settings, loginUrlContains = []) {
     websocketObserverPromises.add(ready);
     return ready;
   };
-  attachPage(page);
+  const historySince = (marker) => [...new Map([...history, ...watchedHistory]
+    .filter((entry) => entry.sequence > marker)
+    .map((entry) => [entry.sequence, entry])).values()].sort((left, right) => left.sequence - right.sequence);
+  attachPage(page);
   return {
     mark: () => sequence,
     attachPage,
     waitForWebSocketObservers: async () => Promise.allSettled([...websocketObserverPromises]),
     since: (marker, urlContains) => history.filter((entry) => entry.sequence > marker
       && (urlContains === undefined || entry.url.includes(urlContains))),
-    responsesSince: (marker, urlContains, method) => history.filter((entry) => entry.sequence > marker
-      && entry.type === "response" && entry.url.includes(urlContains) && entry.method === method),
+    responsesSince: (marker, urlContains, method) => historySince(marker).filter((entry) =>
+      entry.type === "response" && entry.url.includes(urlContains) && entry.method === method),
     websocketSince: (marker, urlContains) => websocketHistory.filter((entry) => entry.sequence > marker && entry.url.includes(urlContains)),
     collectWebSocketCloseCodes: async () => {
       for (const trackedPage of trackedPages) {
@@ -1791,13 +1992,35 @@ function createNetworkTracker(page, settings, loginUrlContains = []) {
         }
       }
     },
-    historySince: (marker) => history.filter((entry) => entry.sequence > marker),
+    historySince,
+    networkEventsSince: (marker, urlContains, limit = settings.jev.maxDiagnosticItems) => {
+      const events = historySince(marker);
+      const entries = events.filter((entry) => entry.type === "request"
+        && (urlContains === undefined || entry.url.includes(urlContains)));
+      return entries.slice(-limit).map((requestEntry) => {
+        const response = events.find((event) => event.type === "response" && event.request === requestEntry.request);
+        const terminal = events.find((event) => (event.type === "finished" || event.type === "failed")
+          && event.request === requestEntry.request);
+        return {
+          url: requestEntry.url,
+          method: requestEntry.method,
+          resource_type: requestEntry.resourceType,
+          ...(response ? { status: response.status } : {}),
+          ...(requestEntry.durationMs !== undefined ? { duration_ms: Math.round(requestEntry.durationMs * 10) / 10 }
+            : terminal?.durationMs !== undefined ? { duration_ms: Math.round(terminal.durationMs * 10) / 10 } : {}),
+          ...(response?.responseHeaders ? { response_headers: response.responseHeaders } : {}),
+        };
+      });
+    },
+    blockedCookiesSince: (marker, urlContains, limit = settings.jev.maxDiagnosticItems) => blockedCookieEvents
+      .filter((event) => event.sequence > marker && (urlContains === undefined || event.url.includes(urlContains)))
+      .slice(-limit),
     authenticationFailureSince: (marker) => history.find((entry) => {
       if (entry.sequence <= marker || entry.type !== "response" || ![401, 403].includes(entry.status)) return false;
       return loginUrlContains.some((needle) => entry.url.toLocaleLowerCase().includes(needle.toLocaleLowerCase()));
     }),
     activeFor: (urlContains) => [...active.values()].filter((entry) => entry.url.includes(urlContains)),
-    dispose: () => {
+    dispose: async () => {
       for (const trackedPage of trackedPages) {
         trackedPage.off("request", onRequest);
         trackedPage.off("response", onResponse);
@@ -1805,11 +2028,14 @@ function createNetworkTracker(page, settings, loginUrlContains = []) {
         trackedPage.off("requestfailed", onFailed);
         trackedPage.off("websocket", onWebSocket);
       }
-      trackedPages.clear();
-      active.clear();
-      ignored.clear();
-      history.length = 0;
-      websocketHistory.length = 0;
+      trackedPages.clear();
+      active.clear();
+      ignored.clear();
+      await Promise.allSettled([...pendingHeaderReads]);
+      pendingHeaderReads.clear();
+      cdpRequestUrls.clear();
+      await Promise.allSettled([...cdpSessions].map((session) => session.detach()));
+      cdpSessions.clear();
     },
   };
 }
@@ -1922,10 +2148,13 @@ async function networkResponseMessage(response, page, settings, secrets) {
   }
 }
 
-async function waitForNetworkAssertion(tracker, step, marker, timeout, page, settings, secrets) {
-  const started = performance.now();
-  while (performance.now() - started < timeout) {
-    const [entry] = tracker.responsesSince(marker, step.urlContains, step.method);
+async function waitForNetworkAssertion(tracker, step, marker, initialNavigationMarker, timeout, page, settings, secrets) {
+  const started = performance.now();
+  while (performance.now() - started < timeout) {
+    const [stepResponse] = tracker.responsesSince(marker, step.urlContains, step.method);
+    const entry = stepResponse || (initialNavigationMarker === undefined
+      ? undefined
+      : tracker.responsesSince(initialNavigationMarker, step.urlContains, step.method).at(-1));
     if (entry) {
       if (entry.status !== step.status) {
         throw new JevBrowserError(`assert_network expected ${step.method} ${JSON.stringify(redact(step.urlContains, secrets))} status ${step.status}, received ${entry.status}`);
@@ -2651,19 +2880,29 @@ async function namedTarget(root, step, snapshot, secrets, timeout, settings) {
   return locatorAt(locator, match.visible[0]);
 }
 
-async function stepRoot(page, frameName) {
-  if (!frameName) return page;
-  const frames = [];
-  for (const frame of page.frames().filter((candidate) => candidate !== page.mainFrame())) {
-    const name = await frameDisplayName(frame);
-    if (name) frames.push({ frame, name });
-  }
-  const matches = frames.filter(({ name }) => name === frameName);
-  if (matches.length !== 1) {
-    const available = frames.map(({ name }) => name).slice(0, 5);
-    const suffix = available.length ? `; available frames: ${available.map((name) => JSON.stringify(name)).join(", ")}` : "";
-    throw new JevBrowserError(`frame ${JSON.stringify(frameName)} must match exactly one named iframe; found ${matches.length}${suffix}`);
-  }
+async function stepRoot(page, frameName) {
+  if (!frameName) return page;
+  const frames = page.frames().filter((candidate) => candidate !== page.mainFrame());
+  if (frameName === "first") {
+    if (frames.length) return frames[0];
+    throw new JevBrowserError("frame first found no iframe on the page");
+  }
+  if (isRecord(frameName) && frameName.urlContains) {
+    const matches = frames.filter((frame) => frame.url().includes(frameName.urlContains));
+    if (matches.length === 1) return matches[0];
+    throw new JevBrowserError(`frame URL substring ${JSON.stringify(frameName.urlContains)} must match exactly one iframe; found ${matches.length}`);
+  }
+  const namedFrames = [];
+  for (const frame of frames) {
+    const name = await frameDisplayName(frame);
+    if (name) namedFrames.push({ frame, name });
+  }
+  const matches = namedFrames.filter(({ name }) => name === frameName);
+  if (matches.length !== 1) {
+    const available = namedFrames.map(({ name }) => name).slice(0, 5);
+    const suffix = available.length ? `; available frames: ${available.map((name) => JSON.stringify(name)).join(", ")}` : "";
+    throw new JevBrowserError(`frame ${JSON.stringify(frameName)} must match exactly one named iframe; found ${matches.length}${suffix}; use "first" or {url_contains: "..."} for unnamed frames`);
+  }
   return matches[0].frame;
 }
 
@@ -2859,8 +3098,26 @@ async function visibleMenuItem(root, label, timeout, settings) {
   return locatorAt(textLocator, visible.at(-1));
 }
 
-async function navigateMenu(page, root, step, settings, execution) {
-  let item;
+async function navigateMenu(page, root, step, settings, execution) {
+  if (step.screen) {
+    const search = page.locator("#pesquisa");
+    const { visible } = await visibleIndexes(search, step.timeoutMs ?? settings.browser.actionTimeoutMs, "SAFI Acesso Rápido search", settings);
+    if (visible.length !== 1) throw new JevBrowserError(`SAFI Acesso Rápido search must match exactly one visible input; found ${visible.length}`);
+    await locatorAt(search, visible[0]).fill(step.screen, { timeout: step.timeoutMs ?? settings.browser.actionTimeoutMs });
+    const timeout = step.timeoutMs ?? settings.browser.actionTimeoutMs;
+    const allRows = page.locator("#ConsultaTelas tbody tr");
+    const exactRows = allRows.filter({ has: page.getByText(step.screen, { exact: true }) });
+    const exactMatches = await visibleIndexes(exactRows, timeout, "exact SAFI Acesso Rápido result", settings, { allowNone: true });
+    const rows = exactMatches.visible.length
+      ? exactRows
+      : allRows.filter({ has: page.getByText(step.screen, { exact: false }) });
+    const row = await exactlyOne(rows, `SAFI Acesso Rápido result ${JSON.stringify(step.screen)}`, timeout, settings);
+    const link = await exactlyOne(row.getByRole("link", { name: new RegExp("Acessar", "i") }), "SAFI Acesso Rápido result link", step.timeoutMs ?? settings.browser.actionTimeoutMs, settings);
+    await link.click({ timeout: step.timeoutMs ?? settings.browser.actionTimeoutMs });
+    await page.locator("#pesquisa").waitFor({ state: "hidden", timeout: step.timeoutMs ?? settings.browser.actionTimeoutMs });
+    return { action: step.action, navigated_screen: step.screen, navigation_source: "safi_quick_access" };
+  }
+  let item;
   try {
     item = await visibleMenuItem(root, step.path[0], 250, settings);
   } catch {
@@ -2879,13 +3136,13 @@ async function navigateMenu(page, root, step, settings, execution) {
   return { action: step.action, navigated_menu: step.path };
 }
 
-async function executeStep(page, step, settings, snapshot, secrets, downloadLedger, execution = {}) {
-  const root = await stepRoot(page, step.frame);
-  const timeout = step.timeoutMs ?? settings.browser.actionTimeoutMs;
+async function executeStep(page, step, settings, snapshot, secrets, downloadLedger, execution = {}) {
+  const root = await stepRoot(page, step.frame);
+  const timeout = step.timeoutMs ?? settings.browser.actionTimeoutMs;
   if (step.action === "click" && step.ifVisible && !await conditionIsVisible(root, step.ifVisible)) {
     return { action: step.action, skipped: true, skip_reason: "if_visible condition was not visible" };
   }
-  if (step.action === "navigate") {
+  if (step.action === "navigate") {
     let destination;
     try { destination = new URL(step.url, page.url()).toString(); } catch {
       throw new JevBrowserError("navigate URL must be absolute or relative to the current page");
@@ -2896,9 +3153,106 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     }
     await page.goto(destination, { waitUntil: "domcontentloaded", timeout });
     execution.browserPool?.setNavigationError?.(null);
-    return { action: step.action, url: evidenceUrl(destination, secrets, settings.jev.maxDiagnosticChars) };
-  }
-  if (step.action === "evaluate") {
+    return { action: step.action, url: evidenceUrl(destination, secrets, settings.jev.maxDiagnosticChars) };
+  }
+  if (step.action === "http_request") {
+    assertLocalDebugPage(page, execution.localOnly, "http_request");
+    const pageUrl = new URL(page.url());
+    const requestUrl = new URL(step.url, pageUrl);
+    if (requestUrl.origin !== pageUrl.origin || !localHostOnly(requestUrl.toString())) {
+      throw new JevBrowserError("http_request must target the current localhost origin");
+    }
+    const reply = await page.evaluate(async ({ url, includeBody, maxBytes }) => {
+      const response = await fetch(url, {
+        method: "GET", credentials: "same-origin", redirect: "error", cache: "no-store",
+      });
+      const headers = {};
+      for (const name of ["cache-control", "content-length", "content-type", "date", "etag", "last-modified", "retry-after", "vary"]) {
+        const value = response.headers.get(name);
+        if (value !== null) headers[name] = value.slice(0, 256);
+      }
+      let body = "";
+      let truncated = false;
+      if (includeBody && response.body) {
+        const reader = response.body.getReader();
+        const chunks = [];
+        let size = 0;
+        while (size <= maxBytes) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          const chunk = value.slice(0, Math.max(0, maxBytes + 1 - size));
+          chunks.push(chunk);
+          size += chunk.length;
+          if (size > maxBytes || chunk.length < value.length) {
+            truncated = true;
+            await reader.cancel();
+            break;
+          }
+        }
+        const bytes = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
+        body = new TextDecoder().decode(bytes.slice(0, maxBytes));
+      }
+      return { status: response.status, ok: response.ok, headers, body, body_truncated: truncated };
+    }, { url: requestUrl.toString(), includeBody: step.includeBody, maxBytes: settings.browser.maxNetworkErrorBodyBytes });
+    let responseBody;
+    if (step.includeBody && reply.body) {
+      try { responseBody = redactLocalPayload(JSON.parse(reply.body)); }
+      catch { responseBody = sanitizeDiagnosticText(reply.body, secrets, settings.browser.maxNetworkErrorMessageChars); }
+    }
+    return {
+      action: step.action,
+      method: "GET",
+      url: evidenceUrl(requestUrl.toString(), secrets, settings.jev.maxDiagnosticChars),
+      status: reply.status,
+      ok: reply.ok,
+      response_headers: reply.headers,
+      ...(step.includeBody ? { response_body: responseBody ?? "", body_truncated: reply.body_truncated } : {}),
+    };
+  }
+  if (step.action === "inspect_cookies") {
+    assertLocalDebugPage(page, execution.localOnly, "inspect_cookies");
+    const cookies = await execution.context.cookies([page.url()]);
+    return {
+      action: step.action,
+      cookies: cookies.map(({ name, domain, path: cookiePath, expires, httpOnly, secure, sameSite }) => ({
+        name: String(name).slice(0, 128), domain: String(domain).slice(0, 255), path: String(cookiePath).slice(0, 256),
+        expires, http_only: Boolean(httpOnly), secure: Boolean(secure), same_site: sameSite,
+        value: "[redacted]",
+      })),
+    };
+  }
+  if (step.action === "read_angular_state") {
+    assertLocalDebugPage(page, execution.localOnly, "read_angular_state");
+    const state = await page.evaluate(() => {
+      const angular = window.angular;
+      if (!angular) return { angular_present: false };
+      const root = document.querySelector("[ng-app], [data-ng-app]") || document.body;
+      let injector;
+      try { injector = angular.element(root).injector(); } catch { injector = undefined; }
+      if (!injector) return { angular_present: true, angular_version: angular.version?.full || null, injector_ready: false };
+      let currentState = null;
+      let parameterNames = [];
+      try {
+        const router = injector.get("$state");
+        currentState = router.current?.name || null;
+        parameterNames = Object.keys(router.params || {}).slice(0, 32);
+      } catch { /* ui-router may not be registered on this page. */ }
+      let authenticated = null;
+      try { authenticated = Boolean(injector.get("$rootScope").usuario); } catch { /* no app-specific auth scope */ }
+      return {
+        angular_present: true,
+        angular_version: angular.version?.full || null,
+        injector_ready: true,
+        state: currentState,
+        parameter_names: parameterNames,
+        authenticated,
+      };
+    });
+    return { action: step.action, ...state };
+  }
+  if (step.action === "evaluate") {
     const value = await page.evaluate((expression) => {
       const parts = expression.split(".");
       let current = globalThis;
@@ -2956,9 +3310,14 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     if (!tabs[step.index]) throw new JevBrowserError(`switch_tab index ${step.index} does not exist; open tabs: ${tabs.length}`);
     return { action: step.action, tab_index: step.index, activePage: tabs[step.index], activeContext: selectedContext };
   }
-  if (step.action === "wait_for_request") {
-    const request = await waitForRequestAssertion(execution.networkTracker, step, execution.networkMarker, timeout, settings);
-    return { action: step.action, asserted: true, method: request.method, status: request.status, url: evidenceUrl(request.url, secrets, settings.jev.maxDiagnosticChars) };
+  if (step.action === "wait_for_request") {
+    const request = await waitForRequestAssertion(execution.networkTracker, step, execution.flowNetworkMarker ?? execution.networkMarker, timeout, settings);
+    return {
+      action: step.action, asserted: true, method: request.method, status: request.status,
+      ...(request.durationMs === undefined ? {} : { duration_ms: Math.round(request.durationMs * 10) / 10 }),
+      ...(request.responseHeaders ? { response_headers: request.responseHeaders } : {}),
+      url: evidenceUrl(request.url, secrets, settings.jev.maxDiagnosticChars),
+    };
   }
   if (step.action === "assert_ws") {
     const frame = await waitForWebSocketAssertion(execution.networkTracker, step, execution.networkMarker, timeout, settings);
@@ -2969,14 +3328,21 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
   if (step.action === "assert_network") {
     const response = await waitForNetworkAssertion(
       execution.networkTracker,
-      step,
-      execution.networkMarker,
-      timeout,
-      page,
+      step,
+      execution.networkMarker,
+      execution.initialNavigationMarker,
+      timeout,
+      page,
       settings,
       secrets,
     );
-    return { action: step.action, asserted: true, url: evidenceUrl(response.url, secrets, settings.jev.maxDiagnosticChars), method: response.method, response_status: response.status, ...(response.message ? { message: response.message } : {}) };
+    return {
+      action: step.action, asserted: true, url: evidenceUrl(response.url, secrets, settings.jev.maxDiagnosticChars),
+      method: response.method, response_status: response.status,
+      ...(response.durationMs === undefined ? {} : { duration_ms: Math.round(response.durationMs * 10) / 10 }),
+      ...(response.responseHeaders ? { response_headers: response.responseHeaders } : {}),
+      ...(response.message ? { message: response.message } : {}),
+    };
   }
   if (step.action === "confirm_modal") {
     const trigger = await namedTarget(root, step, snapshot, secrets, timeout, settings);
@@ -3725,9 +4091,12 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   if (!requestedFlow) throw new JevBrowserError("flow must not be empty");
   if (requestedFlow.length > settings.jev.maxFlowChars) throw new JevBrowserError("flow exceeds the configured character limit");
   if (outcome.length > settings.jev.maxActionDescriptionChars) throw new JevBrowserError("expected_outcome exceeds the configured character limit");
-  const url = initialUrl === undefined ? undefined : validateUrl(initialUrl);
+  const url = initialUrl === undefined ? undefined : validateUrl(initialUrl);
   const options = resolveFlowOptions(rawOptions, settings);
   const plans = validateCandidatePlans(replaceKnownParams(candidatePlans, variables, true), settings, options.maxFlowSteps);
+  const networkOnlyFastPath = options.fastPath && Object.keys(plans).length === 1
+    && !Object.values(plans)[0].when
+    && Object.values(plans)[0].steps.every(({ action }) => ["assert_network", "wait_for_request"].includes(action));
   assertPlanPlaceholders(plans, variables);
   if (!url && !options.reusePage) throw new JevBrowserError("initial_url is required when continue_from_current_page is false");
   if (options.waitForHttp && !localHostOnly(options.waitForHttp.url)
@@ -3778,10 +4147,17 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     browserSessionMs = browser.sessionMs;
     page = browser.page;
     context = browser.context;
+    if (browser.recovered && options.reusePage && !url) browserPool.setNavigationError?.("BROWSER_PAGE_NOT_RESTORED");
   }
   const initialPage = page;
   const initialContext = context;
-  const capture = createDiagnostics(page, options, settings, secrets);
+  const networkWatchPatterns = Object.values(plans).flatMap(({ steps }) => steps.flatMap((step) => {
+    if (step.action === "wait_for_request") return [step.urlPattern];
+    if (step.action === "assert_network") return [step.urlContains];
+    return [];
+  })).concat(expected.assertions.filter(({ kind }) => kind === "request").map(({ request }) => request));
+  const networkTracker = createNetworkTracker(page, settings, options.loginUrlContains, networkWatchPatterns);
+  const capture = createDiagnostics(page, options, settings, secrets);
   const result = {
     ...(serverVersion ? { server_version: serverVersion } : {}),
     status: "failed",
@@ -3798,9 +4174,9 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   result.snapshot_mode = options.returnSnapshot;
   if (options.allowMutations) result.mutation_authorization = "allowed_on_localhost";
   const downloadLedger = { count: 0, bytes: 0 };
-  const networkTracker = createNetworkTracker(page, settings, options.loginUrlContains);
   await networkTracker.waitForWebSocketObservers();
-  const initialNetworkMarker = networkTracker.mark();
+  const initialNetworkMarker = networkTracker.mark();
+  let initialNavigationMarker;
   const timings = { navigationMs: 0, initialSnapshotMs: 0, readyMs: 0, decisionMs: 0, browserPlanMs: 0 };
   const routeCleanups = [];
   const contextStack = [context];
@@ -3855,17 +4231,24 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
       addDiagnostic(result.warnings, "trace, video, and screenshots were suppressed because this flow contains sensitive text", settings.jev.maxDiagnosticItems);
     }
 
-    let reusedPage = false;
+    let reusedPage = false;
     result.navigation_strategy = options.freshContext ? "fresh_isolated_context" : "navigated_to_initial_url";
-    const plansBeginWithNavigation = Object.values(plans).every(({ steps }) => steps[0]?.action === "navigate");
+    const plansBeginWithNavigation = Object.values(plans).every(({ steps }) => steps[0]?.action === "navigate");
     if (options.reusePage && !options.freshContext) {
-      navigationError = browserPool.getNavigationError?.();
-      if (navigationError) {
-        result.navigation_error = navigationError;
-        throw new JevBrowserError(`reuse_page cannot continue because the previous navigation failed with ${navigationError}; run once with reuse_page: false to navigate again`);
-      }
-      const currentUrl = typeof page.url === "function" ? page.url() : "about:blank";
-      if (currentUrl && currentUrl !== "about:blank") {
+      navigationError = browserPool.getNavigationError?.();
+      if (navigationError) {
+        if (navigationError === "BROWSER_PAGE_NOT_RESTORED" && url) {
+          result.navigation_strategy = "recovered_with_initial_url";
+        } else {
+          result.navigation_error = navigationError;
+          const detail = navigationError === "BROWSER_PAGE_NOT_RESTORED"
+            ? "the previous page was not restored after reconnecting; provide initial_url to navigate again"
+            : `the previous navigation failed with ${navigationError}; run once with reuse_page: false to navigate again`;
+          throw new JevBrowserError(`reuse_page cannot continue because ${detail}`);
+        }
+      }
+      const currentUrl = typeof page.url === "function" ? page.url() : "about:blank";
+      if (!navigationError && currentUrl && currentUrl !== "about:blank") {
         let currentRoute;
         try {
           currentRoute = normalizedRouteUrl(currentUrl);
@@ -3888,18 +4271,30 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         }
       }
     }
-    if (!reusedPage) {
+    if (!reusedPage) {
       const destinationUrl = url;
       if (!destinationUrl) throw new JevBrowserError("initial_url is required because there is no open page to continue");
       const navigationStarted = performance.now();
+      initialNavigationMarker = networkTracker.mark();
       try {
-        await page.goto(destinationUrl, { waitUntil: "domcontentloaded", timeout: settings.browser.actionTimeoutMs * 4 });
+        const response = await page.goto(destinationUrl, { waitUntil: "domcontentloaded", timeout: settings.browser.actionTimeoutMs * 4 });
+        if (response?.status() >= 400) result.navigation_http_status = response.status();
         if (!options.freshContext) browserPool.setNavigationError?.(null);
       } catch (error) {
-        navigationError = String(error?.message || "").match(/\b(?:net::)?(ERR_[A-Z0-9_]+)\b/)?.[1] || "NAVIGATION_FAILED";
-        if (navigationError && !options.freshContext) browserPool.setNavigationError?.(navigationError);
-        throw error;
-      }
+        const failedDocument = networkOnlyFastPath
+          ? networkTracker.historySince(initialNavigationMarker)
+            .filter((entry) => entry.type === "response" && entry.resourceType === "document" && entry.status >= 400)
+            .at(-1)
+          : undefined;
+        if (failedDocument) {
+          result.navigation_http_status = failedDocument.status;
+          if (!options.freshContext) browserPool.setNavigationError?.(null);
+        } else {
+          navigationError = String(error?.message || "").match(/\b(?:net::)?(ERR_[A-Z0-9_]+)\b/)?.[1] || "NAVIGATION_FAILED";
+          if (navigationError && !options.freshContext) browserPool.setNavigationError?.(navigationError);
+          throw error;
+        }
+      }
       timings.navigationMs = performance.now() - navigationStarted;
     }
     if (options.clearStorage) {
@@ -3909,11 +4304,15 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
       }
       reusedPage = false;
       result.navigation_strategy = "storage_cleared_and_reloaded";
-    }
-    const snapshotStarted = performance.now();
-    try {
-      const readiness = await waitForPageReady(page, options, settings, secrets, reusedPage);
-      const enriched = await enrichSnapshot(page, readiness.snapshot, settings, secrets, options.snapshotScope, options.snapshotIncludeHidden);
+    }
+    const snapshotStarted = performance.now();
+    try {
+      const readiness = networkOnlyFastPath
+        ? { snapshot: "", readyMs: 0 }
+        : await waitForPageReady(page, options, settings, secrets, reusedPage);
+      const enriched = networkOnlyFastPath
+        ? { snapshot: "", unnamedControls: [] }
+        : await enrichSnapshot(page, readiness.snapshot, settings, secrets, options.snapshotScope, options.snapshotIncludeHidden);
       result.final_snapshot = enriched.snapshot;
       initialSnapshot = continuation?.initialSnapshot || enriched.snapshot;
       if (options.includeUnnamedControls) result.unnamed_controls_initial = enriched.unnamedControls;
@@ -3921,13 +4320,16 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         navigationError = "AUTHENTICATION_REQUIRED";
         throw new JevBrowserError("the configured login text is visible; sign in to the application, then run the flow again");
       }
-      for (const control of enriched.unnamedControls) {
-        addDiagnostic(
-          result.warnings,
-          `interactive ${control.role} has no accessible name; index ${control.index}; nearest label ${JSON.stringify(control.nearest_label)}; set include_unnamed_controls to return sanitized HTML evidence`,
-          settings.jev.maxDiagnosticItems,
-        );
-      }
+      if (enriched.unnamedControls.length) {
+        const examples = enriched.unnamedControls.slice(0, 3)
+          .map(({ role, nearest_label }) => `${role}${nearest_label ? ` near ${JSON.stringify(nearest_label)}` : ""}`)
+          .join("; ");
+        addDiagnostic(
+          result.warnings,
+          `${enriched.unnamedControls.length} interactive control(s) have no accessible name${examples ? `; examples: ${examples}` : ""}; set include_unnamed_controls to return sanitized HTML evidence`,
+          settings.jev.maxDiagnosticItems,
+        );
+      }
       timings.readyMs = readiness.readyMs;
       if (!options.freshContext) browserPool.setNavigationError?.(null);
       if (continuation) {
@@ -4068,11 +4470,14 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
               nativeDialog.result = undefined;
             }
             const actionMarker = networkTracker.mark();
-            const execution = {
-              networkTracker,
-              networkMarker,
-              autoAngularIdle: options.autoAngularIdle,
-              readyStableMs: options.readyStableMs,
+            const execution = {
+              networkTracker,
+              networkMarker,
+              initialNavigationMarker,
+              flowNetworkMarker: initialNetworkMarker,
+              autoAngularIdle: options.autoAngularIdle,
+              readyStableMs: options.readyStableMs,
+              localOnly: options.localOnly,
               allowMutations: options.allowMutations,
               browserPool,
               nativeDialog,
@@ -4130,16 +4535,18 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
                 failure = `accessibility audit reported ${traceStep.accessibility_audit.blocking_violations_count} violation(s) at or above ${traceStep.accessibility_audit.fail_on_impact} impact`;
               }
             }
-            snapshot = await snapshotAfterStep(
-              activePage,
-              settings,
-              secrets,
-              options.snapshotScope,
-              snapshot,
-              index + 1,
-              result.warnings,
-              options.snapshotIncludeHidden,
-            );
+            if (!networkOnlyFastPath) {
+              snapshot = await snapshotAfterStep(
+                activePage,
+                settings,
+                secrets,
+                options.snapshotScope,
+                snapshot,
+                index + 1,
+                result.warnings,
+                options.snapshotIncludeHidden,
+              );
+            }
             if (failure) break;
             if (options.stopOnExpected && outcome && !runAllSteps && containsExpectedOutcome(snapshot, outcome)) break;
           } catch (error) {
@@ -4160,7 +4567,7 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
             break;
           }
         }
-        if (failure || trace.length === 0) {
+        if ((failure || trace.length === 0) && !networkOnlyFastPath) {
           snapshot = await snapshotAfterStep(
             activePage,
             settings,
@@ -4172,14 +4579,16 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
             options.snapshotIncludeHidden,
           );
         }
-        const finalDetails = await enrichSnapshot(
-          activePage,
-          snapshot,
-          settings,
-          secrets,
-          options.snapshotScope,
-          options.snapshotIncludeHidden,
-        );
+        const finalDetails = networkOnlyFastPath
+          ? { snapshot, unnamedControls: [] }
+          : await enrichSnapshot(
+            activePage,
+            snapshot,
+            settings,
+            secrets,
+            options.snapshotScope,
+            options.snapshotIncludeHidden,
+          );
         snapshot = finalDetails.snapshot;
         if (options.includeUnnamedControls) result.unnamed_controls_final = finalDetails.unnamedControls;
         timings.browserPlanMs = performance.now() - planStarted;
@@ -4339,7 +4748,7 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     await Promise.all(createdContexts.map(async (createdContext) => {
       try { await browserPool.releaseContext?.(createdContext); } catch { artifactErrors.push("isolated browser context cleanup failed"); }
     }));
-    networkTracker.dispose();
+    await networkTracker.dispose();
     await capture.dispose();
     initialPage.off("dialog", onNativeDialog);
   }
@@ -4348,7 +4757,16 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   try { result.current_url = evidenceUrl(activePage.url(), secrets, settings.jev.maxDiagnosticChars); } catch { result.current_url = "unavailable"; }
   result.console_errors = groupConsoleErrors([...(continuation?.consoleErrors || []), ...capture.diagnostics.console_errors]);
   result.console_messages = groupConsoleMessages([...(continuation?.consoleMessages || []), ...capture.diagnostics.console_messages]);
-  result.network_failures = [...(continuation?.networkFailures || []), ...capture.diagnostics.network_failures];
+  result.network_failures = [...(continuation?.networkFailures || []), ...capture.diagnostics.network_failures];
+  const blockedCookies = networkTracker.blockedCookiesSince(initialNetworkMarker, options.captureNetworkUrlContains)
+    .map(({ url: requestUrl, ...event }) => ({ ...event, url: evidenceUrl(requestUrl, secrets, settings.jev.maxDiagnosticChars) }));
+  if (blockedCookies.length) result.blocked_cookies = blockedCookies;
+  if (options.captureNetwork === "all") {
+    result.network_events = networkTracker.networkEventsSince(
+      initialNetworkMarker,
+      options.captureNetworkUrlContains,
+    ).map(({ url: requestUrl, ...event }) => ({ ...event, url: evidenceUrl(requestUrl, secrets, settings.jev.maxDiagnosticChars) }));
+  }
   result.warnings.push(...capture.diagnostics.warnings);
   result.timings_ms = flowTimings(started, browserSessionMs, timings.navigationMs, timings.initialSnapshotMs, timings.readyMs, timings.decisionMs, timings.browserPlanMs);
   const safeResult = await redactObject(result, secrets);
@@ -4359,7 +4777,7 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     safeResult.final_snapshot = stripUnnamedControlsSection(safeResult.final_snapshot);
     initialSnapshot = stripUnnamedControlsSection(initialSnapshot);
   }
-  if (options.returnSnapshot === "diff" && typeof safeResult.final_snapshot === "string") {
+  if (!networkOnlyFastPath && options.returnSnapshot === "diff" && typeof safeResult.final_snapshot === "string") {
     safeResult.final_snapshot = snapshotDiff(initialSnapshot, safeResult.final_snapshot);
   } else if (options.returnSnapshot === "none") {
     delete safeResult.final_snapshot;