@diegosouzacdv/jev-browser-mcp 0.7.0 → 0.7.2

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

@@ -1,9 +1,12 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { chmod, lstat, mkdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { ACCESSIBILITY_STANDARDS, runAccessibilityAudit } from "./accessibility.mjs";
-import { JevBrowserError } from "./config.mjs";
-import { buildChoicePayload, COMPLETE_ACTION_ID, parseDecision, requestJev } from "./jev-client.mjs";
+import { ACCESSIBILITY_STANDARDS, runAccessibilityAudit } from "./accessibility.mjs";
+import { JevBrowserError } from "./config.mjs";
+import { buildChoicePayload, COMPLETE_ACTION_ID, parseDecision, requestJev } from "./jev-client.mjs";
+import { assertReadOnlySql, createIntegrationSession, executeIntegrationStep } from "./test-integrations.mjs";
+import { isProfileOriginAllowed, requireEnvironmentProfile } from "./environment-profiles.mjs";
+import { cleanupUploadStagingDirectory, prepareUploadStagingDirectory, withUploadStagingLock } from "./upload-staging.mjs";
 
 const PLAN_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,79}$/;
 const CLICK_ROLES = new Set(["button", "link", "tab", "menuitem", "checkbox", "radio", "switch", "cell", "gridcell", "option"]);
@@ -18,7 +21,7 @@ const CONTAINER_ROLES = new Set([
 ]);
 const TARGET_SELECTION_ACTIONS = new Set([
   "click", "confirm_modal", "check", "uncheck", "type", "clear", "select_option", "hover", "press", "assert_text", "assert_value", "wait_for_value",
-  "wait_for_enabled", "assert_enabled", "assert_visible", "assert_hidden", "upload_file", "extract",
+  "wait_for_enabled", "assert_enabled", "assert_visible", "assert_hidden", "assert_attribute", "upload_file", "extract",
 ]);
 const LOCATOR_FIELDS = ["label", "placeholder", "title", "text", "test_id", "selector"];
 const TARGET_LOCATOR_FIELDS = [...LOCATOR_FIELDS, "target_text"];
@@ -38,6 +41,8 @@ const MIME_TYPES = new Map([
   [".jpg", "image/jpeg"], [".jpeg", "image/jpeg"], [".png", "image/png"],
   [".txt", "text/plain"], [".webp", "image/webp"],
 ]);
+// Jev's Decisions API currently caps a single upload payload at 47 MiB.
+const JEV_UPLOAD_LIMIT_BYTES = 47 * 1024 * 1024;
 const WEBSOCKET_CLOSE_PROBE = `(() => {
   const eventsKey = "__jevBrowserWebSocketCloseEvents";
   const installedKey = "__jevBrowserWebSocketCloseProbe";
@@ -59,12 +64,13 @@ const WEBSOCKET_CLOSE_PROBE = `(() => {
 const FLOW_OPTION_KEYS = new Set([
   "allow_mutations", "block_trackers", "capture_console_errors", "capture_network_error_bodies", "capture_network_errors",
   "auto_angular_idle", "block_fonts", "busy_selectors", "confirmation_token", "dry_run", "fast_path", "local_only",
+  "environment_profile",
   "login_text", "login_url_contains", "max_flow_steps", "ready_network_idle", "ready_stable_ms", "ready_text", "ready_timeout_seconds",
   "report_path", "permissions", "fake_media", "viewport", "mobile", "device_scale_factor", "locale", "timezone_id",
   "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;
 
@@ -114,8 +120,10 @@ function flowFingerprint({ flow, initialUrl, expectedOutcome, candidatePlans, pa
   }))).digest("hex");
 }
 
-function looksMutating(rawStep) {
-  if (["confirm_dialog", "confirm_modal", "like_comment", "unlike_comment", "upload_file"].includes(rawStep.action)) return true;
+function looksMutating(rawStep) {
+  if (["confirm_dialog", "confirm_modal", "like_comment", "unlike_comment", "upload_file"].includes(rawStep.action)) return true;
+  if (["delete_remote_file", "run_hook"].includes(rawStep.action)) return true;
+  if (rawStep.action === "http_request" && !["GET", "HEAD"].includes(String(rawStep.method || "GET").toUpperCase())) return true;
   if (rawStep.action !== "click") return false;
   return [rawStep.name, rawStep.title, rawStep.text, rawStep.target_text, rawStep.label]
     .some((value) => typeof value === "string" && MUTATING_LABEL.test(value));
@@ -177,7 +185,7 @@ function replaceKnownParams(value, params, allowUnknown = false) {
   return value;
 }
 
-function assertPlanPlaceholders(plans, initialVariables) {
+function assertPlanPlaceholders(plans, initialVariables) {
   for (const [planId, plan] of Object.entries(plans)) {
     const available = new Set(Object.keys(initialVariables));
     for (const field of [plan.description, plan.when?.visible]) {
@@ -186,7 +194,10 @@ function assertPlanPlaceholders(plans, initialVariables) {
     for (const [index, step] of plan.steps.entries()) {
       const fields = Object.entries(step).filter(([key]) => !["action", "as", "sensitive"].includes(key)).map(([, value]) => value);
       for (const field of fields) assertTemplateRefsDeep(field, available, `candidate plan ${planId} step ${index + 1}`);
-      if (step.action === "extract" || (step.action === "evaluate" && step.as)) available.add(step.as);
+      if (step.action === "extract" || step.action === "generate_fixture" || (step.action === "evaluate" && step.as)) available.add(step.as);
+      if (["http_request", "assert_db"].includes(step.action)) {
+        for (const name of Object.keys(step.extract || {})) available.add(name);
+      }
     }
   }
 }
@@ -223,13 +234,25 @@ function actionSchemas(semanticTarget) {
         clear: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
         navigate: { required: ["url"], optional: ["timeout_seconds", "timeout_ms", "target_page"] },
         confirm_dialog: { required: ["expected_text", "button"], optional: ["timeout_seconds"] },
-        confirm_modal: { required: ["expected_text", "button"], optional: [...semanticTarget, "trigger", "confirm", "timeout_seconds"] },
+        confirm_modal: { required: ["expected_text", "button"], optional: [...semanticTarget, "trigger", "trigger_match", "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", "json", "multipart", "include_body", "expected_status", "extract", "timeout_seconds", "timeout_ms"] },
+        generate_fixture: { required: ["kind", "as", "file_name"], optional: ["content", "size_bytes", "timeout_seconds", "timeout_ms"] },
+        assert_download: { required: ["file_path"], optional: ["mime_type", "timeout_seconds", "timeout_ms"] },
+        assert_db: { required: ["sql", "expected"], optional: ["binds", "extract", "timeout_seconds", "timeout_ms"] },
+        assert_log: { required: ["source", "contains"], optional: ["not_contains", "since", "timeout_seconds", "timeout_ms"] },
+        start_email_capture: { required: [], optional: ["timeout_seconds", "timeout_ms"] },
+        assert_email: { required: [], optional: ["to", "subject_contains", "body_contains", "timeout_ms", "timeout_seconds"] },
+        assert_remote_file: { required: ["server", "path"], optional: ["exists", "size_bytes", "sha256", "timeout_seconds", "timeout_ms"] },
+        delete_remote_file: { required: ["server", "path"], optional: ["timeout_seconds", "timeout_ms"] },
+        run_hook: { required: ["hook"], optional: ["args", "expected_exit_code", "timeout_ms", "timeout_seconds"] },
+        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"] },
@@ -245,8 +268,9 @@ function actionSchemas(semanticTarget) {
         press: { required: ["key"], optional: [...semanticTarget, "timeout_seconds"] },
         select_option: { required: [], optional: [...semanticTarget, "option", "value", "label_contains", "timeout_seconds"] },
         hover: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
-        assert_text: { required: ["expected"], optional: [...semanticTarget, "timeout_seconds"] },
-        assert_value: { required: ["expected"], optional: [...semanticTarget, "timeout_seconds"] },
+        assert_text: { required: ["expected"], optional: [...semanticTarget, "timeout_seconds"] },
+        assert_value: { required: ["expected"], optional: [...semanticTarget, "timeout_seconds"] },
+        assert_attribute: { required: ["attribute", "expected"], optional: [...semanticTarget, "match", "timeout_seconds"] },
         assert_enabled: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
         assert_visible: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
         assert_hidden: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
@@ -257,21 +281,92 @@ function actionSchemas(semanticTarget) {
         };
 }
 
-export function describeBrowserActions() {
+export function describeBrowserActions(settings) {
   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 === "assert_email") contract.conditional_required = { subject_contains: "at least one of to, subject_contains, or body_contains is required" };
+      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],
+    suite: {
+      file: ".jev-browser/suites/<name>.json",
+      file_fields: { required: ["version", "id", "criteria"], optional: ["description", "environment_profile", "params", "flows", "setup", "teardown"] },
+      flow_definition: { required: ["flow", "candidate_plans"], optional: ["initial_url", "expected_outcome", "params", "options"] },
+      criterion: { required: ["id", "description", "flow"], optional: ["initial_url", "expected_outcome", "params", "options"] },
+      run_test_suite_tool: { required: ["suite_name"], optional: ["params", "environment_profile", "report_path", "background"] },
+      execution: "sequential; all setup, criteria and teardown flows are preflighted before browser startup; teardown is always attempted; run_test_suite returns or polls a run_id when background=true",
+    },
+    profiles: {
+      file: ".jev-browser/profiles.json or absolute JEV_BROWSER_PROFILES_FILE inside the project",
+      supported: ["dev", "hml", "prd"],
+      profile_fields: { required: ["environment"], optional: ["application_origins", "database", "log_sources", "smtp_capture", "remotes", "hooks"] },
+      database: ["postgresql", "oracle"],
+      database_fields: {
+        postgresql: { required: ["engine", "connection_env", "timeout_ms", "max_rows"] },
+        oracle: { required: ["engine", "connect_env", "user_env", "password_env", "timeout_ms", "max_rows"] },
+      },
+      remote_protocols: ["ftp", "ftps", "sftp"],
+      remote_fields: { required: ["protocol", "host", "port", "username_env", "password_env", "root"], optional: ["host_fingerprint_env; required for SFTP"] },
+      smtp_capture_fields: { required: ["port", "bind_address", "max_messages"] },
+      hook_fields: { required: ["script", "arguments", "timeout_ms"], argument_fields: { required: ["type", "required", "max_length"], types: ["string", "integer", "boolean"] } },
+      environment_policy: { dev: "test writes allowed with explicit allow_mutations; remote deletion and hooks are DEV-only", hml: "application writes require explicit allow_mutations; database and logs are read-only", prd: "mutations, destructive remote actions and hooks are refused" },
+      credentials: "environment variable references only; raw credentials are rejected from reports",
+      ...(settings ? { configured: Object.keys(settings.browser.environmentProfiles.profiles) } : {}),
+    },
+    ...(settings ? { limits: {
+      max_flow_steps: settings.browser.maxFlowSteps,
+      max_flow_steps_env: settings.browser.maxFlowStepsEnv,
+      max_upload_files: settings.browser.maxUploadFiles,
+      max_upload_file_bytes: settings.browser.maxUploadFileBytes,
+      max_upload_file_bytes_env: settings.browser.maxUploadFileBytesEnv,
+      max_upload_total_bytes: settings.browser.maxUploadTotalBytes,
+      max_upload_total_bytes_env: settings.browser.maxUploadTotalBytesEnv,
+      max_background_flow_runs: settings.browser.maxBackgroundFlowRuns,
+      background_flow_result_ttl_ms: settings.browser.backgroundFlowResultTtlMs,
+      max_download_files: settings.browser.maxDownloadFiles,
+      max_download_file_bytes: settings.browser.maxDownloadFileBytes,
+      max_download_total_bytes: settings.browser.maxDownloadTotalBytes,
+      max_environment_profile_file_bytes: settings.browser.maxEnvironmentProfileFileBytes,
+      max_test_suite_file_bytes: settings.browser.maxTestSuiteFileBytes,
+      max_test_suite_criteria: settings.browser.maxTestSuiteCriteria,
+      max_test_suite_report_bytes: settings.browser.maxTestSuiteReportBytes,
+      max_database_query_chars: settings.browser.maxDatabaseQueryChars,
+      max_database_bind_values: settings.browser.maxDatabaseBindValues,
+      max_external_extract_variables: settings.browser.maxExternalExtractVariables,
+      max_hook_output_bytes: settings.browser.maxHookOutputBytes,
+      max_hook_timeout_ms: settings.browser.maxHookTimeoutMs,
+      max_hook_argument_chars: settings.browser.maxHookArgumentChars,
+      max_smtp_captured_messages: settings.browser.maxSmtpCapturedMessages,
+      max_database_timeout_ms: settings.browser.maxDatabaseTimeoutMs,
+      max_database_rows: settings.browser.maxDatabaseRows,
+      jev_max_upload_file_bytes: JEV_UPLOAD_LIMIT_BYTES,
+    } } : {}),
     option_shapes: {
+      capture_network: ["errors", "all", "none"],
+      capture_network_url_contains: "optional URL substring filter for capture_network=all",
+      environment_profile: "selects a configured DEV, HML, or PRD allowlist from .jev-browser/profiles.json; credentials are environment references only",
+      local_only: "required for page inspection and for HTTP requests without an environment profile; localhost loopback only",
       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",
@@ -282,13 +377,74 @@ export function describeBrowserActions() {
       duration_ms: "wait.ms",
       value: "type.text or wait_for_text.text",
       timeout_ms: "per-step timeout in milliseconds",
-      confirm_modal: { trigger: "button accessible name", confirm: "button", expected_text: "required exact safety phrase" },
+      confirm_modal: { trigger: "button accessible name (exact by default)", trigger_match: ["exact", "contains", "regex"], confirm: "button", expected_text: "required safety phrase; checked before the affirmative button is clicked" },
     },
     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 +638,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);
       }
@@ -515,7 +677,7 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         if (hasTextEnv) step.textEnv = rawStep.text_env;
         step.mode = rawStep.mode || "fill";
         step.blur = rawStep.blur ?? false;
-        step.sensitive = rawStep.sensitive ?? true;
+        step.sensitive = rawStep.sensitive ?? true;
         if (hasTextEnv && rawStep.sensitive === false) throw new JevBrowserError("type text_env is always sensitive");
       }
       if (action === "clear" && step.role && !TEXT_ROLES.has(step.role)) {
@@ -577,16 +739,140 @@ 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;
-      }
-      if (action === "evaluate") {
+        }
+        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 (!new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]).has(step.method)) {
+          throw new JevBrowserError("http_request method must be GET, HEAD, POST, PUT, PATCH, or DELETE");
+        }
+        if (rawStep.json !== undefined && !isRecord(rawStep.json)) throw new JevBrowserError("http_request json must be an object");
+        if (rawStep.multipart !== undefined && !Array.isArray(rawStep.multipart)) throw new JevBrowserError("http_request multipart must be an array of typed fields");
+        if (rawStep.json !== undefined && rawStep.multipart !== undefined) throw new JevBrowserError("http_request cannot contain both json and multipart");
+        step.json = rawStep.json;
+        step.multipart = (rawStep.multipart || []).map((field, index) => {
+          if (!isRecord(field)) throw new JevBrowserError(`http_request multipart[${index}] must be an object`);
+          exactKeys(field, ["name"], ["value", "file_path", "file_name"], `http_request multipart[${index}]`);
+          const hasValue = Object.hasOwn(field, "value");
+          const hasFile = Object.hasOwn(field, "file_path");
+          if (hasValue === hasFile) throw new JevBrowserError(`http_request multipart[${index}] needs exactly one of value or file_path`);
+          const item = { name: requiredText(field.name, "multipart field name", 128) };
+          if (hasValue) {
+            if (!["string", "number", "boolean"].includes(typeof field.value)) throw new JevBrowserError(`http_request multipart[${index}].value must be scalar`);
+            item.value = field.value;
+          } else {
+            item.filePath = requiredText(field.file_path, "multipart file path", settings.browser.maxUploadPathChars);
+            if (field.file_name !== undefined) item.fileName = safeDownloadName(requiredText(field.file_name, "multipart file name", 180));
+          }
+          return item;
+        });
+        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 (rawStep.expected_status !== undefined && (!Number.isSafeInteger(rawStep.expected_status) || rawStep.expected_status < 100 || rawStep.expected_status > 599)) {
+          throw new JevBrowserError("http_request expected_status must be an HTTP status from 100 to 599");
+        }
+        step.expectedStatus = rawStep.expected_status;
+        if (rawStep.extract !== undefined) {
+          if (!isRecord(rawStep.extract) || Object.keys(rawStep.extract).length > settings.browser.maxExternalExtractVariables) throw new JevBrowserError("http_request extract must be a bounded object of variable names to JSON paths");
+          step.extract = Object.fromEntries(Object.entries(rawStep.extract).map(([name, descriptor]) => {
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new JevBrowserError("http_request extract keys must be simple variable names");
+            exactKeys(descriptor, ["json_path"], [], `http_request extract.${name}`);
+            const jsonPath = requiredText(descriptor.json_path, `http_request extract.${name} JSON path`, 256);
+            if (!/^[A-Za-z0-9_$-]+(?:\.(?:[A-Za-z0-9_$-]+|\d+))*$/.test(jsonPath)) throw new JevBrowserError(`http_request extract.${name} JSON path is invalid`);
+            return [name, { jsonPath }];
+          }));
+        } else step.extract = {};
+      }
+      if (action === "generate_fixture") {
+        step.kind = rawStep.kind;
+        if (!new Set(["pdf", "text", "bytes"]).has(step.kind)) throw new JevBrowserError("generate_fixture kind must be pdf, text, or bytes");
+        step.as = requiredText(rawStep.as, "fixture variable name", 64);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(step.as)) throw new JevBrowserError("generate_fixture as must be a simple variable name");
+        step.fileName = requiredText(rawStep.file_name, "fixture file_name", settings.browser.maxUploadPathChars);
+        if (rawStep.content !== undefined) step.content = requiredText(rawStep.content, "fixture content", settings.browser.maxTextEntryChars);
+        if (step.kind === "bytes") {
+          if (!Number.isSafeInteger(rawStep.size_bytes) || rawStep.size_bytes <= 0 || rawStep.size_bytes > Math.min(settings.browser.maxUploadFileBytes, JEV_UPLOAD_LIMIT_BYTES)) {
+            throw new JevBrowserError("generate_fixture size_bytes must fit the configured upload limit and Jev's 47 MiB provider limit");
+          }
+          step.sizeBytes = rawStep.size_bytes;
+        } else if (rawStep.size_bytes !== undefined) throw new JevBrowserError("generate_fixture size_bytes is only valid for kind bytes");
+      }
+      if (action === "assert_download") {
+        step.filePath = requiredText(rawStep.file_path, "assert_download file_path", settings.browser.maxUploadPathChars);
+        if (rawStep.mime_type !== undefined) step.mimeType = requiredText(rawStep.mime_type, "assert_download mime_type", 128).toLowerCase();
+      }
+      if (action === "assert_db") {
+        step.sql = requiredText(rawStep.sql, "assert_db sql", settings.browser.maxDatabaseQueryChars);
+        if (!isRecord(rawStep.expected)) throw new JevBrowserError("assert_db expected must contain row_count, first_row, or rows");
+        exactKeys(rawStep.expected, [], ["row_count", "first_row", "rows"], "assert_db expected");
+        if (!Object.keys(rawStep.expected).length) throw new JevBrowserError("assert_db expected must contain at least one assertion");
+        if (rawStep.expected.row_count !== undefined && (!Number.isSafeInteger(rawStep.expected.row_count) || rawStep.expected.row_count < 0)) {
+          throw new JevBrowserError("assert_db expected.row_count must be a non-negative integer");
+        }
+        if (rawStep.expected.first_row !== undefined && !isRecord(rawStep.expected.first_row)) throw new JevBrowserError("assert_db expected.first_row must be an object");
+        if (rawStep.expected.rows !== undefined && !Array.isArray(rawStep.expected.rows)) throw new JevBrowserError("assert_db expected.rows must be an array");
+        step.expected = rawStep.expected;
+        step.binds = rawStep.binds ?? {};
+        if (!isRecord(step.binds) || Object.keys(step.binds).length > settings.browser.maxDatabaseBindValues
+          || Object.values(step.binds).some((value) => !["string", "number", "boolean"].includes(typeof value) && value !== null)) {
+          throw new JevBrowserError("assert_db binds must be a bounded object of scalar values");
+        }
+        if (rawStep.extract !== undefined) {
+          if (!isRecord(rawStep.extract) || Object.keys(rawStep.extract).length > settings.browser.maxExternalExtractVariables) throw new JevBrowserError("assert_db extract must be a bounded object");
+          step.extract = Object.fromEntries(Object.entries(rawStep.extract).map(([name, descriptor]) => {
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new JevBrowserError("assert_db extract keys must be simple variable names");
+            exactKeys(descriptor, ["column"], ["row"], `assert_db extract.${name}`);
+            const row = descriptor.row ?? 0;
+            if (!Number.isSafeInteger(row) || row < 0) throw new JevBrowserError(`assert_db extract.${name}.row must be a non-negative integer`);
+            return [name, { column: requiredText(descriptor.column, `assert_db extract.${name}.column`, 128), row }];
+          }));
+        } else step.extract = {};
+      }
+      if (action === "assert_log") {
+        step.source = requiredText(rawStep.source, "assert_log source", 48);
+        step.contains = requiredText(rawStep.contains, "assert_log contains", settings.browser.maxTextEntryChars);
+        if (rawStep.not_contains !== undefined) step.notContains = requiredText(rawStep.not_contains, "assert_log not_contains", settings.browser.maxTextEntryChars);
+        step.since = rawStep.since ?? "flow";
+        if (step.since !== "flow" && !/^step:\d+$/.test(step.since)) throw new JevBrowserError("assert_log since must be flow or step:N");
+      }
+      if (action === "assert_email") {
+        for (const field of ["to", "subject_contains", "body_contains"]) {
+          if (rawStep[field] !== undefined) step[field === "subject_contains" ? "subjectContains" : field === "body_contains" ? "bodyContains" : field]
+            = requiredText(rawStep[field], `assert_email ${field}`, settings.browser.maxTextEntryChars);
+        }
+        if (!step.to && !step.subjectContains && !step.bodyContains) throw new JevBrowserError("assert_email needs at least one of to, subject_contains, or body_contains");
+        if (step.to && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(step.to)) throw new JevBrowserError("assert_email to must be a valid email address");
+      }
+      if (action === "assert_remote_file" || action === "delete_remote_file") {
+        step.server = requiredText(rawStep.server, `${action} server`, 48);
+        step.path = requiredText(rawStep.path, `${action} path`, 1024);
+        if (action === "assert_remote_file") {
+          step.exists = rawStep.exists ?? true;
+          if (typeof step.exists !== "boolean") throw new JevBrowserError("assert_remote_file exists must be a boolean");
+          if (rawStep.size_bytes !== undefined && (!Number.isSafeInteger(rawStep.size_bytes) || rawStep.size_bytes < 0)) throw new JevBrowserError("assert_remote_file size_bytes must be a non-negative integer");
+          step.sizeBytes = rawStep.size_bytes;
+          if (rawStep.sha256 !== undefined && !/^[a-f0-9]{64}$/i.test(rawStep.sha256)) throw new JevBrowserError("assert_remote_file sha256 must be a 64-character SHA-256 hex string");
+          step.sha256 = rawStep.sha256?.toLowerCase();
+        }
+      }
+      if (action === "run_hook") {
+        step.hook = requiredText(rawStep.hook, "run_hook hook", 48);
+        step.args = rawStep.args ?? {};
+        if (!isRecord(step.args)) throw new JevBrowserError("run_hook args must be an object");
+        step.expectedExitCode = rawStep.expected_exit_code ?? 0;
+        if (!Number.isSafeInteger(step.expectedExitCode) || step.expectedExitCode < 0 || step.expectedExitCode > 255) throw new JevBrowserError("run_hook expected_exit_code must be 0-255");
+      }
+      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)) {
           throw new JevBrowserError("evaluate accepts read-only property paths such as navigator.mediaDevices or document.readyState; calls and assignments are not supported");
@@ -632,10 +918,12 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         if (["url", "title"].includes(step.source) && hasLocatorField(rawStep)) {
           throw new JevBrowserError(`extract source ${step.source} does not use a locator`);
         }
-        if (rawStep.sensitive !== undefined && typeof rawStep.sensitive !== "boolean") {
-          throw new JevBrowserError("extract sensitive must be a boolean");
-        }
-        step.sensitive = rawStep.sensitive ?? true;
+        if (rawStep.sensitive !== undefined && typeof rawStep.sensitive !== "boolean") {
+          throw new JevBrowserError("extract sensitive must be a boolean");
+        }
+        const sensitiveAttribute = step.source === "attribute"
+          && /(?:pass(?:word)?|token|secret|authorization|cookie|credential|api[_-]?key|private[_-]?key)/i.test(step.attribute);
+        step.sensitive = rawStep.sensitive ?? (step.source !== "attribute" || sensitiveAttribute);
       }
       if (action === "wait_for_condition") {
         if (!new Set(["network_idle", "url", "hidden", "text_hidden", "angular_idle"]).has(rawStep.condition)) {
@@ -699,9 +987,20 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         }
         step.key = rawStep.key;
       }
-      if (action === "assert_text" || action === "assert_value") {
-        step.expected = requiredText(rawStep.expected, "expected value", settings.browser.maxTextEntryChars);
-      }
+      if (action === "assert_text" || action === "assert_value") {
+        step.expected = requiredText(rawStep.expected, "expected value", settings.browser.maxTextEntryChars);
+      }
+      if (action === "assert_attribute") {
+        step.attribute = requiredText(rawStep.attribute, "attribute", 128);
+        if (!/^[A-Za-z_:][A-Za-z0-9:._-]*$/.test(step.attribute)) {
+          throw new JevBrowserError("assert_attribute attribute must be a valid HTML attribute name");
+        }
+        step.expected = requiredText(rawStep.expected, "expected value", settings.browser.maxTextEntryChars);
+        step.match = rawStep.match ?? "exact";
+        if (!new Set(["exact", "contains"]).has(step.match)) {
+          throw new JevBrowserError("assert_attribute match must be exact or contains");
+        }
+      }
       if (action === "upload_file") {
         const target = rawStep.target || (hasLocatorField(step) ? "input"
           : step.role && DROPZONE_ROLES.has(step.role) && step.role !== "button" ? "dropzone"
@@ -744,7 +1043,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 } } : {}) };
@@ -779,6 +1084,11 @@ export function normalizeStepAliases(rawStep) {
       step[canonical] = step[alias];
       delete step[alias];
     }
+    if (Object.hasOwn(step, "trigger_match")) {
+      if (Object.hasOwn(step, "name_match")) throw new JevBrowserError("confirm_modal cannot contain both trigger_match and name_match");
+      step.name_match = step.trigger_match;
+      delete step.trigger_match;
+    }
     if (step.name !== undefined && step.role === undefined) step.role = "button";
   }
   return step;
@@ -832,7 +1142,16 @@ function resolveFlowOptions(rawOptions, settings) {
   }
   const scope = rawOptions.snapshot_scope ?? settings.browser.defaults.snapshotScope;
   if (!new Set(["body", "main", "dialog"]).has(scope)) throw new JevBrowserError("options.snapshot_scope must be body, main, or dialog");
-  const defaults = settings.browser.defaults;
+  const defaults = settings.browser.defaults;
+  const environmentProfile = rawOptions.environment_profile === undefined
+    ? undefined
+    : requiredText(rawOptions.environment_profile, "environment_profile", 48);
+  const selectedProfile = environmentProfile
+    ? requireEnvironmentProfile(settings, environmentProfile, "options.environment_profile")
+    : undefined;
+  if ((rawOptions.allow_mutations ?? false) && selectedProfile?.environment === "prd") {
+    throw new JevBrowserError("allow_mutations is forbidden for PRD profiles");
+  }
   const stepTimeoutSeconds = rawOptions.step_timeout_seconds ?? settings.browser.actionTimeoutMs / 1000;
   if (typeof stepTimeoutSeconds !== "number" || !Number.isFinite(stepTimeoutSeconds) || stepTimeoutSeconds <= 0
     || stepTimeoutSeconds > settings.browser.maxStepTimeoutSeconds) {
@@ -958,10 +1277,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,11 +1304,14 @@ 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,
+    localOnly: rawOptions.local_only ?? defaults.localOnly,
+    environmentProfile,
     loginText: Object.freeze(loginText),
     loginUrlContains: Object.freeze(loginUrlContains),
     permissions: Object.freeze([...permissions]),
@@ -1026,11 +1356,29 @@ function escapeRegex(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-function planSecrets(plans) {
-  const secrets = new Set();
-  for (const plan of Object.values(plans)) {
-    for (const step of plan.steps) {
-      if (step.action === "type" && step.sensitive) secrets.add(step.text);
+function planSecrets(plans) {
+  const secrets = new Set();
+  const collectSensitiveValues = (value, sensitiveParent = false) => {
+    if (typeof value === "string") {
+      if (sensitiveParent && value.length >= 4) secrets.add(value);
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) collectSensitiveValues(item, sensitiveParent);
+      return;
+    }
+    if (isRecord(value)) {
+      for (const [key, item] of Object.entries(value)) collectSensitiveValues(item, sensitiveParent || /pass(?:word)?|secret|token|authorization|cookie|credential|api[_-]?key|private[_-]?key/i.test(key));
+    }
+  };
+  for (const plan of Object.values(plans)) {
+    for (const step of plan.steps) {
+      if (step.action === "type" && step.sensitive) secrets.add(step.text);
+      if (step.action === "http_request") {
+        collectSensitiveValues(step.json);
+        collectSensitiveValues(step.multipart);
+      }
+      if (step.action === "assert_db") collectSensitiveValues(step.binds);
       if (step.action === "upload_file") {
         for (const filePath of step.filePaths) {
           secrets.add(filePath);
@@ -1145,28 +1493,55 @@ 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;
-  if (!settings.browser.uploadRoot) {
-    throw new JevBrowserError("fake_media is disabled; configure JEV_BROWSER_UPLOAD_ROOT and keep the WAV file inside it");
-  }
-  let root;
-  let audio;
-  try {
-    root = await realpath(settings.browser.uploadRoot);
-    const requested = path.isAbsolute(fakeMedia) ? fakeMedia : path.resolve(root, fakeMedia);
-    audio = await realpath(requested);
-  } catch {
-    throw new JevBrowserError("fake_media could not read the configured WAV file");
-  }
-  const relative = path.relative(root, audio);
-  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-    throw new JevBrowserError("fake_media path must stay inside JEV_BROWSER_UPLOAD_ROOT");
-  }
+async function resolveFakeMediaPath(fakeMedia, settings) {
+  if (!fakeMedia) return undefined;
+  const staging = await prepareUploadStagingDirectory(settings);
+  const roots = [settings.browser.uploadRoot, staging].filter(Boolean);
+  let audio;
+  for (const rootPath of roots) {
+    const candidate = path.isAbsolute(fakeMedia) ? fakeMedia : path.resolve(rootPath, fakeMedia);
+    const resolved = await realpath(candidate).catch(() => undefined);
+    if (!resolved) continue;
+    const root = await realpath(rootPath).catch(() => undefined);
+    if (!root) continue;
+    const relative = path.relative(root, resolved);
+    if (relative && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) {
+      audio = resolved;
+      break;
+    }
+  }
+  if (!audio) throw new JevBrowserError("fake_media must resolve inside managed project staging or JEV_BROWSER_UPLOAD_ROOT");
   if (path.extname(audio).toLowerCase() !== ".wav") throw new JevBrowserError("fake_media accepts WAV files only");
   const file = await stat(audio);
   if (!file.isFile() || file.size > settings.browser.maxUploadFileBytes) {
@@ -1665,12 +2040,20 @@ 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 watchedResponses = new Map();
+  const responseWaiters = new Set();
+  const responseObservers = new Set();
   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 +2067,58 @@ 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();
+    if (watchPatterns.some((pattern) => pattern.includes("*")
+      ? urlPatternMatcher(pattern).test(entry.url) : entry.url.includes(pattern))) {
+      const watchKey = `${entry.url}\n${entry.method}\n${entry.status}`;
+      watchedResponses.delete(watchKey);
+      watchedResponses.set(watchKey, entry);
+      while (watchedResponses.size > settings.browser.maxNetworkHistoryEvents) {
+        watchedResponses.delete(watchedResponses.keys().next().value);
+      }
+    }
+    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));
+    for (const waiter of [...responseWaiters]) {
+      if (entry.sequence > waiter.marker && waiter.predicate(entry)) {
+        responseWaiters.delete(waiter);
+        clearTimeout(waiter.timer);
+        waiter.resolve(entry);
+      }
+    }
+    for (const observer of [...responseObservers]) observer.capture(entry);
+  };
   const onFinished = (request) => record("finished", request);
   const onFailed = (request) => record("failed", request);
   const trackedPages = new Set();
@@ -1717,9 +2137,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 +2184,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 +2215,73 @@ function createNetworkTracker(page, settings, loginUrlContains = []) {
     websocketObserverPromises.add(ready);
     return ready;
   };
-  attachPage(page);
+  const historySince = (marker) => [...new Map([...history, ...watchedHistory, ...watchedResponses.values()]
+    .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]),
+    observeResponseSince: (marker, predicate) => {
+      const observer = {
+        entry: historySince(marker).find((candidate) => candidate.type === "response" && predicate(candidate)),
+        resolve: undefined,
+        timer: undefined,
+        capture(candidate) {
+          if (this.entry || candidate.sequence <= marker || !predicate(candidate)) return;
+          this.entry = candidate;
+          responseObservers.delete(this);
+          clearTimeout(this.timer);
+          this.timer = undefined;
+          const resolve = this.resolve;
+          this.resolve = undefined;
+          resolve?.(candidate);
+        },
+        wait(timeout) {
+          if (this.entry) return Promise.resolve(this.entry);
+          return new Promise((resolve) => {
+            this.resolve = resolve;
+            this.timer = setTimeout(() => {
+              responseObservers.delete(this);
+              this.timer = undefined;
+              this.resolve = undefined;
+              resolve(undefined);
+            }, timeout);
+          });
+        },
+        dispose() {
+          responseObservers.delete(this);
+          clearTimeout(this.timer);
+          this.timer = undefined;
+          const resolve = this.resolve;
+          this.resolve = undefined;
+          resolve?.(this.entry);
+        },
+      };
+      if (!observer.entry) responseObservers.add(observer);
+      return observer;
+    },
+    waitForResponseSince: (marker, predicate, timeout) => {
+      const existing = historySince(marker).find((entry) => entry.type === "response" && predicate(entry));
+      if (existing) return Promise.resolve(existing);
+      return new Promise((resolve) => {
+        const waiter = {
+          marker,
+          predicate,
+          timer: setTimeout(() => {
+            responseWaiters.delete(waiter);
+            resolve(undefined);
+          }, timeout),
+          resolve,
+        };
+        responseWaiters.add(waiter);
+      });
+    },
     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 +2304,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 +2340,16 @@ 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();
+      for (const observer of [...responseObservers]) observer.dispose();
+      responseObservers.clear();
+      await Promise.allSettled([...pendingHeaderReads]);
+      pendingHeaderReads.clear();
+      cdpRequestUrls.clear();
+      await Promise.allSettled([...cdpSessions].map((session) => session.detach()));
+      cdpSessions.clear();
     },
   };
 }
@@ -1922,10 +2462,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}`);
@@ -1949,17 +2492,15 @@ function urlPatternMatcher(pattern) {
   return new RegExp(`^${pattern.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`, "i");
 }
 
-async function waitForRequestAssertion(tracker, step, marker, timeout, settings) {
-  const matcher = urlPatternMatcher(step.urlPattern);
-  const started = performance.now();
-  while (performance.now() - started < timeout) {
-    const entry = tracker.historySince(marker).find((event) => event.type === "response"
-      && matcher.test(event.url)
-      && (!step.method || event.method === step.method)
-      && (step.status === undefined || event.status === step.status));
-    if (entry) return entry;
-    await new Promise((resolve) => setTimeout(resolve, Math.min(settings.browser.visibilityPollMs, remainingMs(started + timeout))));
-  }
+async function waitForRequestAssertion(tracker, step, marker, timeout, observer) {
+  const matcher = urlPatternMatcher(step.urlPattern);
+  const matches = (event) => matcher.test(event.url)
+    && (!step.method || event.method === step.method)
+    && (step.status === undefined || event.status === step.status);
+  const entry = observer
+    ? await observer.wait(timeout)
+    : await tracker.waitForResponseSince(marker, matches, timeout);
+  if (entry) return entry;
   throw new JevBrowserError(`wait_for_request did not observe ${step.method || "any method"} ${JSON.stringify(step.urlPattern)}${step.status ? ` status ${step.status}` : ""} within ${timeout}ms`);
 }
 
@@ -2485,12 +3026,13 @@ function xpathRolePredicate(role) {
   return native ? `@role='${role}' or ${native}` : `@role='${role}'`;
 }
 
-function relativeTarget(anchor, role) {
-  const selector = TEXT_ROLES.has(role)
-    ? "xpath=following::*[self::input or self::textarea or self::select or @role='textbox' or @role='searchbox' or @role='combobox'][1]"
-    : role === "link" ? "xpath=following::*[self::a or @role='link'][1]"
-      : role === "button" ? "xpath=following::*[self::button or @role='button'][1]"
-        : "xpath=following::*[self::input or self::textarea or self::select or self::button or self::a or @role='textbox' or @role='combobox' or @role='button' or @role='link'][1]";
+function relativeTarget(anchor, role, includeFollowingControls = false) {
+  const firstOnly = includeFollowingControls ? "" : "[1]";
+  const selector = TEXT_ROLES.has(role)
+    ? `xpath=following::*[self::input or self::textarea or self::select or @role='textbox' or @role='searchbox' or @role='combobox']${firstOnly}`
+    : role === "link" ? `xpath=following::*[self::a or @role='link']${firstOnly}`
+      : role === "button" ? `xpath=following::*[self::button or @role='button']${firstOnly}`
+        : `xpath=following::*[self::input or self::textarea or self::select or self::button or self::a or @role='textbox' or @role='combobox' or @role='button' or @role='link']${firstOnly}`;
   return anchor.locator(selector);
 }
 
@@ -2525,8 +3067,10 @@ async function targetLocator(root, step, timeout, settings) {
     locator = step.action === "type" && step.role ? relativeTarget(anchor, step.role) : anchor;
   } else if (field === "test_id") {
     locator = targetRoot.getByTestId(step.testId);
-  } else if (step.near) {
-    locator = relativeTarget(targetRoot.getByText(step.near.text, { exact: true }).first(), step.role);
+  } else if (step.near) {
+    const anchor = targetRoot.getByText(step.near.text, { exact: true }).first();
+    locator = relativeTarget(anchor, step.role, step.name !== undefined);
+    if (step.name !== undefined) locator = locator.and(targetRoot.getByRole(step.role, roleOptions(step)));
   } else if (step.role) {
     locator = targetRoot.getByRole(step.role, roleOptions(step));
     if (step.name && (!step.nameMatch || step.nameMatch === "exact") && await locator.count() === 0) {
@@ -2651,19 +3195,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;
 }
 
@@ -2697,17 +3251,18 @@ function fileMimeType(fileName) {
   return MIME_TYPES.get(path.extname(fileName).toLowerCase()) || "application/octet-stream";
 }
 
-async function uploadFiles(step, settings) {
-  const uploadRoot = settings.browser.uploadRoot;
-  if (!uploadRoot) throw new JevBrowserError("file uploads are disabled; configure JEV_BROWSER_UPLOAD_ROOT first");
-  let root;
-  try {
-    root = await realpath(uploadRoot);
-  } catch {
-    throw new JevBrowserError("configured JEV_BROWSER_UPLOAD_ROOT does not exist or is not accessible");
-  }
-  const rootInfo = await stat(root);
-  if (!rootInfo.isDirectory()) throw new JevBrowserError("configured JEV_BROWSER_UPLOAD_ROOT must be a directory");
+async function uploadFiles(step, settings) {
+  const roots = [settings.browser.uploadRoot, await prepareUploadStagingDirectory(settings)].filter(Boolean);
+  const allowedRoots = [];
+  for (const candidate of roots) {
+    try {
+      const root = await realpath(candidate);
+      if ((await stat(root)).isDirectory()) allowedRoots.push(root);
+    } catch {
+      if (candidate === settings.browser.uploadRoot) throw new JevBrowserError("configured JEV_BROWSER_UPLOAD_ROOT does not exist or is not accessible");
+    }
+  }
+  if (!allowedRoots.length) throw new JevBrowserError("no permitted upload directory is available");
   let totalBytes = 0;
   const files = [];
   for (const requestedPath of step.filePaths) {
@@ -2718,9 +3273,12 @@ async function uploadFiles(step, settings) {
     } catch {
       throw new JevBrowserError("upload_file could not read one of the configured files");
     }
-    const relativePath = path.relative(root, resolved);
-    if (!relativePath || relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
-      throw new JevBrowserError("upload_file path must stay inside JEV_BROWSER_UPLOAD_ROOT");
+    const allowed = allowedRoots.some((root) => {
+      const relativePath = path.relative(root, resolved);
+      return Boolean(relativePath) && relativePath !== ".." && !relativePath.startsWith(`..${path.sep}`) && !path.isAbsolute(relativePath);
+    });
+    if (!allowed) {
+      throw new JevBrowserError("upload_file path must stay inside JEV_BROWSER_UPLOAD_ROOT");
     }
     const fileInfo = await stat(resolved);
     if (!fileInfo.isFile()) throw new JevBrowserError("upload_file accepts regular files only");
@@ -2770,7 +3328,7 @@ async function removeBrowserDownload(download) {
   }
 }
 
-async function saveDownload(download, settings, ledger) {
+async function saveDownload(download, settings, ledger, networkTracker) {
   if (ledger.count >= settings.browser.maxDownloadFiles) {
     await removeBrowserDownload(download);
     throw new JevBrowserError("download exceeds the configured file-count limit");
@@ -2831,7 +3389,14 @@ async function saveDownload(download, settings, ledger) {
     ledger.count += 1;
     ledger.bytes += savedInfo.size;
     await removeBrowserDownload(download);
-    return { name, path: destination, size_bytes: savedInfo.size };
+    let responseMimeType;
+    try {
+      const entry = networkTracker?.historySince?.(0)?.filter(({ url: responseUrl, status }) => responseUrl === download.url() && status !== undefined).at(-1);
+      responseMimeType = entry?.responseHeaders?.["content-type"]?.split(";")[0]?.trim().toLowerCase();
+    } catch { /* The download remains verifiable by content hash and extension when response headers are unavailable. */ }
+    const saved = { name, path: destination, size_bytes: savedInfo.size, mime_type: responseMimeType || fileMimeType(name) };
+    ledger.files?.push({ name, path: destination, sizeBytes: savedInfo.size, mimeType: responseMimeType });
+    return saved;
   } catch (error) {
     await rm(destination, { force: true }).catch(() => {});
     await removeBrowserDownload(download);
@@ -2859,8 +3424,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,26 +3462,77 @@ 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 (["http_request", "generate_fixture", "assert_download", "assert_db", "assert_log", "start_email_capture", "assert_email", "assert_remote_file", "delete_remote_file", "run_hook"].includes(step.action)) {
+    return executeIntegrationStep(step, {
+      settings,
+      profile: execution.environmentProfile,
+      session: execution.integrationSession,
+      variables: execution.variables,
+      page,
+      execution: { ...execution, downloadLedger },
+    });
+  }
   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");
     }
     destination = validateUrl(destination);
-    if (execution.allowMutations && !localHostOnly(destination)) {
-      throw new JevBrowserError("allow_mutations only permits navigation to localhost, 127.0.0.1, or ::1");
+    if (execution.allowMutations && !localHostOnly(destination) && !isProfileOriginAllowed(execution.environmentProfile, destination)) {
+      throw new JevBrowserError("allow_mutations navigation must stay on localhost or an application origin allow-listed by the selected DEV/HML profile");
     }
     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 === "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;
@@ -2931,7 +3565,9 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     await execution.networkTracker.attachPage(next);
     if (step.url) {
       const destination = validateUrl(new URL(step.url, page.url()).toString());
-      if (execution.allowMutations && !localHostOnly(destination)) throw new JevBrowserError("allow_mutations only permits navigation to localhost, 127.0.0.1, or ::1");
+      if (execution.allowMutations && !localHostOnly(destination) && !isProfileOriginAllowed(execution.environmentProfile, destination)) {
+        throw new JevBrowserError("allow_mutations navigation must stay on localhost or an application origin allow-listed by the selected DEV/HML profile");
+      }
       await next.goto(destination, { waitUntil: "domcontentloaded", timeout });
     }
     execution.capture.attachPage(next);
@@ -2956,9 +3592,20 @@ 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,
+      execution.requestObserver,
+    );
+    return {
+      action: step.action, asserted: true, method: request.method, response_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 +3616,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);
@@ -3038,7 +3692,17 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     if (step.source === "url") value = page.url();
     else if (step.source === "title") value = await page.title();
     else if (step.source === "value") value = await control.inputValue({ timeout });
-    else if (step.source === "attribute") value = await control.getAttribute(step.attribute, { timeout }) || "";
+    else if (step.source === "attribute") {
+      value = await control.getAttribute(step.attribute, { timeout }) || "";
+      if (new Set(["href", "src", "action", "formaction", "poster"]).has(step.attribute.toLowerCase()) && value) {
+        try {
+          const parsed = new URL(value, page.url());
+          parsed.search = "";
+          parsed.hash = "";
+          value = parsed.toString();
+        } catch { value = "[redacted invalid URL attribute]"; }
+      }
+    }
     else value = (await control.innerText({ timeout })).replace(/\s+/g, " ").trim();
     if (value.length > settings.browser.maxTextEntryChars) {
       throw new JevBrowserError("extracted value exceeds the configured character limit");
@@ -3297,14 +3961,30 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
       ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
     };
   }
-  if (step.action === "assert_value") {
-    await waitForValue(control, step.expected, timeout, `assert_value for ${describeTarget(step, secrets)}`, settings);
-    return {
-      action: step.action,
-      asserted: true,
-      ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
-    };
-  }
+  if (step.action === "assert_value") {
+    await waitForValue(control, step.expected, timeout, `assert_value for ${describeTarget(step, secrets)}`, settings);
+    return {
+      action: step.action,
+      asserted: true,
+      ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
+    };
+  }
+  if (step.action === "assert_attribute") {
+    const actual = await control.getAttribute(step.attribute, { timeout });
+    const matches = actual !== null && (step.match === "contains"
+      ? actual.includes(step.expected)
+      : actual === step.expected);
+    if (!matches) {
+      throw new JevBrowserError(`assert_attribute failed for ${describeTarget(step, secrets)}: attribute ${step.attribute} did not match the expected value`);
+    }
+    return {
+      action: step.action,
+      asserted: true,
+      attribute: step.attribute,
+      match: step.match,
+      ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
+    };
+  }
   if (step.action === "assert_enabled") {
     if (!(await control.isEnabled())) throw new JevBrowserError(`assert_enabled failed for ${describeTarget(step, secrets)}`);
     return { action: step.action, asserted: true, enabled: true, ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)) };
@@ -3659,7 +4339,7 @@ async function writeFlowReport(result, reportPath, settings) {
   return outputPath;
 }
 
-async function collectPerformanceMetrics(page) {
+async function collectPerformanceMetrics(page) {
   try {
     return await page.evaluate(() => {
       const navigation = performance.getEntriesByType("navigation")[0];
@@ -3677,9 +4357,52 @@ async function collectPerformanceMetrics(page) {
   } catch {
     return undefined;
   }
-}
-
-async function redactObject(value, secrets) {
+}
+
+function validateIntegratedActions(plans, options, settings) {
+  const profile = options.environmentProfile
+    ? requireEnvironmentProfile(settings, options.environmentProfile, "integrated test actions")
+    : undefined;
+  for (const [planId, plan] of Object.entries(plans)) {
+    for (const [index, step] of plan.steps.entries()) {
+      const where = `candidate plan ${planId} step ${index + 1}`;
+      if (profile?.environment === "prd" && step.mutating === true) throw new JevBrowserError(`${where} mutating actions are forbidden for PRD profiles`);
+      if (["assert_db", "assert_log", "start_email_capture", "assert_email", "assert_remote_file", "delete_remote_file", "run_hook"].includes(step.action) && !profile) {
+        throw new JevBrowserError(`${where} action ${step.action} requires options.environment_profile`);
+      }
+      if (step.action === "http_request") {
+        if (!profile && !options.localOnly) throw new JevBrowserError(`${where} http_request requires local_only or a configured environment_profile`);
+        if (!profile && step.method !== "GET" && step.method !== "HEAD") throw new JevBrowserError(`${where} mutating http_request requires a configured DEV or HML profile`);
+        if (profile?.environment === "prd" && !["GET", "HEAD"].includes(step.method)) throw new JevBrowserError(`${where} mutating http_request is forbidden for PRD`);
+        if (!["GET", "HEAD"].includes(step.method) && !options.allowMutations) throw new JevBrowserError(`${where} mutating http_request requires explicit options.allow_mutations authorization`);
+      }
+      if (step.action === "assert_db" && !profile?.database) throw new JevBrowserError(`${where} needs a database connection in environment profile ${profile?.id || ""}`);
+      if (step.action === "assert_db") assertReadOnlySql(step.sql, settings.browser.maxDatabaseQueryChars);
+      if (step.action === "assert_log" && !Object.hasOwn(profile?.logSources || {}, step.source)) throw new JevBrowserError(`${where} log source ${step.source} is not allow-listed`);
+      if (["start_email_capture", "assert_email"].includes(step.action) && !profile?.smtpCapture) throw new JevBrowserError(`${where} needs smtp_capture in environment profile ${profile?.id || ""}`);
+      if (step.action === "assert_remote_file" || step.action === "delete_remote_file") {
+        if (!Object.hasOwn(profile?.remotes || {}, step.server)) throw new JevBrowserError(`${where} remote server ${step.server} is not allow-listed`);
+        if (step.action === "delete_remote_file" && profile.environment !== "dev") throw new JevBrowserError(`${where} delete_remote_file is restricted to DEV profiles`);
+        if (step.action === "delete_remote_file" && !options.allowMutations) throw new JevBrowserError(`${where} delete_remote_file requires explicit options.allow_mutations authorization`);
+      }
+      if (step.action === "run_hook") {
+        if (!Object.hasOwn(profile?.hooks || {}, step.hook)) throw new JevBrowserError(`${where} hook ${step.hook} is not allow-listed`);
+        if (profile.environment !== "dev") throw new JevBrowserError(`${where} run_hook is restricted to DEV profiles`);
+        if (!options.allowMutations) throw new JevBrowserError(`${where} run_hook requires explicit options.allow_mutations authorization`);
+      }
+      if (step.action === "generate_fixture") {
+        const extension = path.extname(step.fileName).toLowerCase();
+        if (step.kind === "pdf" && extension !== ".pdf") throw new JevBrowserError(`${where} PDF fixtures must use a .pdf filename`);
+        if (step.kind === "text" && extension !== ".txt") throw new JevBrowserError(`${where} text fixtures must use a .txt filename`);
+        if (/[\\/\0]/.test(step.fileName) || step.fileName === "." || step.fileName === "..") throw new JevBrowserError(`${where} fixture file_name cannot contain a path`);
+      }
+    }
+  }
+  if (options.allowMutations && profile?.environment === "prd") throw new JevBrowserError("allow_mutations is forbidden for PRD profiles");
+  return profile;
+}
+
+async function redactObject(value, secrets) {
   if (typeof value === "string") return redact(value, secrets);
   if (Array.isArray(value)) return Promise.all(value.map((item) => redactObject(item, secrets)));
   if (isRecord(value)) {
@@ -3709,43 +4432,53 @@ function snapshotDiff(initialSnapshot, finalSnapshot) {
   return added.length ? added.join("\n") : "[no new snapshot lines]";
 }
 
-function stripUnnamedControlsSection(snapshot) {
-  return snapshot.replace(/\n\n\[interactive controls without accessible names;[^\]]+\][\s\S]*$/i, "").trim();
-}
-
-export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, candidatePlans, params: rawParams, options: rawOptions, settings, browserPool, fetchImpl = fetch, serverVersion, mutationAuthorizationStore = defaultMutationAuthorizationStore }) {
+export function validateBrowserFlowRequest({ flow, initialUrl, expectedOutcome, candidatePlans, params: rawParams, options: rawOptions, settings }) {
   if (typeof flow !== "string" || (expectedOutcome !== undefined && typeof expectedOutcome !== "string" && !isRecord(expectedOutcome))) {
     throw new JevBrowserError("flow must be text and expected_outcome must be text or a structured assertion object");
   }
-  let variables = validateParams(rawParams, settings);
+  const variables = validateParams(rawParams, settings);
   const requestedFlow = replaceKnownParams(flow, variables).trim();
   const expected = normalizeExpectedOutcome(expectedOutcome, variables, settings);
-  const outcome = expected.description;
-  const outcomeText = expected.text;
   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);
+  if (expected.description.length > settings.jev.maxActionDescriptionChars) throw new JevBrowserError("expected_outcome exceeds the configured character limit");
+  const url = initialUrl === undefined ? undefined : validateUrl(initialUrl);
   const options = resolveFlowOptions(rawOptions, settings);
   const plans = validateCandidatePlans(replaceKnownParams(candidatePlans, variables, true), settings, options.maxFlowSteps);
+  const selectedProfile = validateIntegratedActions(plans, options, settings);
   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)
     && (!url || new URL(options.waitForHttp.url).hostname.toLowerCase() !== new URL(url).hostname.toLowerCase())) {
     throw new JevBrowserError("wait_for_http must target localhost or the same host as initial_url");
   }
-  if (!url && options.allowMutations) throw new JevBrowserError("allow_mutations needs an explicit localhost initial_url");
-  resolveEnvironmentText(plans, settings);
-  if (options.localOnly && Object.keys(plans).length > 0 && !(options.fastPath && Object.keys(plans).length === 1)) {
-    throw new JevBrowserError("local_only does not call Jev; provide exactly one candidate plan and enable fast_path");
-  }
-  if (options.allowMutations && url && !localHostOnly(url)) {
-    throw new JevBrowserError("allow_mutations is limited to localhost, 127.0.0.1, and ::1 URLs");
-  }
-  const secretBearingFlow = Object.values(plans).some((plan) => plan.steps.some((step) => step.action === "type" && step.sensitive));
-  if (options.recordVideo && secretBearingFlow) {
-    throw new JevBrowserError("record_video is disabled for flows that type sensitive text");
-  }
+  if (!url && options.allowMutations && !selectedProfile) throw new JevBrowserError("allow_mutations needs an explicit localhost initial_url or a configured environment_profile");
+  resolveEnvironmentText(plans, settings);
+  if (options.localOnly && Object.keys(plans).length > 0 && !(options.fastPath && Object.keys(plans).length === 1)) {
+    throw new JevBrowserError("local_only does not call Jev; provide exactly one candidate plan and enable fast_path");
+  }
+  if (options.allowMutations && url && !localHostOnly(url) && !isProfileOriginAllowed(selectedProfile, url)) {
+    throw new JevBrowserError("allow_mutations URL must be localhost or an application origin allow-listed by the selected DEV/HML profile");
+  }
+  if (options.freshContext && !url) throw new JevBrowserError("fresh_context requires initial_url so the isolated context never inherits a previous page or account");
+  const secretBearingFlow = Object.values(plans).some((plan) => plan.steps.some((step) => step.action === "type" && step.sensitive));
+  if (options.recordVideo && secretBearingFlow) throw new JevBrowserError("record_video is disabled for flows that type sensitive text");
+  return { variables, requestedFlow, expected, url, options, plans, selectedProfile, secretBearingFlow };
+}
+
+function stripUnnamedControlsSection(snapshot) {
+  return snapshot.replace(/\n\n\[interactive controls without accessible names;[^\]]+\][\s\S]*$/i, "").trim();
+}
+
+async function executeBrowserFlowCore({ flow, initialUrl, expectedOutcome, candidatePlans, params: rawParams, options: rawOptions, settings, browserPool, fetchImpl = fetch, serverVersion, integrationSession, mutationAuthorizationStore = defaultMutationAuthorizationStore }) {
+  const preflight = validateBrowserFlowRequest({ flow, initialUrl, expectedOutcome, candidatePlans, params: rawParams, options: rawOptions, settings });
+  const { requestedFlow, expected, url, options, plans, selectedProfile, secretBearingFlow } = preflight;
+  let variables = preflight.variables;
+  const outcome = expected.description;
+  const outcomeText = expected.text;
+  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));
   const fingerprint = flowFingerprint({ flow, initialUrl: url, expectedOutcome, candidatePlans, params: rawParams, options });
   const continuation = options.confirmationToken
     ? mutationAuthorizationStore.consume(options.confirmationToken, fingerprint)
@@ -3778,12 +4511,20 @@ 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 } : {}),
+    ...(serverVersion ? { server_version: serverVersion } : {}),
+    ...(selectedProfile ? { environment_profile: { id: selectedProfile.id, environment: selectedProfile.environment } } : {}),
     status: "failed",
     expected_outcome_visible: false,
     acceptance_criteria_met: false,
@@ -3796,11 +4537,31 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     final_snapshot: "",
   };
   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);
+  if (options.allowMutations) result.mutation_authorization = selectedProfile
+    ? `allowed_on_${selectedProfile.environment}_profile`
+    : "allowed_on_localhost";
+  const downloadLedger = { count: 0, bytes: 0, files: [] };
   await networkTracker.waitForWebSocketObservers();
-  const initialNetworkMarker = networkTracker.mark();
+  const initialNetworkMarker = networkTracker.mark();
+  const requestObservers = new Map();
+  const armAvailableRequestObservers = () => {
+    for (const [planId, candidatePlan] of Object.entries(plans)) {
+      candidatePlan.steps.forEach((templateStep, stepIndex) => {
+        const observerKey = `${planId}:${stepIndex}`;
+        if (templateStep.action !== "wait_for_request" || requestObservers.has(observerKey)) return;
+        const unresolved = [...templateStep.urlPattern.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g)]
+          .some(([, name]) => !Object.hasOwn(variables, name));
+        if (unresolved) return;
+        const resolvedPattern = replaceKnownParams(templateStep.urlPattern, variables);
+        const matcher = urlPatternMatcher(resolvedPattern);
+        requestObservers.set(observerKey, networkTracker.observeResponseSince(initialNetworkMarker, (event) => matcher.test(event.url)
+          && (!templateStep.method || event.method === templateStep.method)
+          && (templateStep.status === undefined || event.status === templateStep.status)));
+      });
+    }
+  };
+  armAvailableRequestObservers();
+  let initialNavigationMarker;
   const timings = { navigationMs: 0, initialSnapshotMs: 0, readyMs: 0, decisionMs: 0, browserPlanMs: 0 };
   const routeCleanups = [];
   const contextStack = [context];
@@ -3855,17 +4616,27 @@ 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 (options.allowMutations && !localHostOnly(currentUrl) && !isProfileOriginAllowed(selectedProfile, currentUrl)) {
+        throw new JevBrowserError("allow_mutations cannot continue on a page outside localhost or the selected profile's application origin allowlist");
+      }
+      if (!navigationError && currentUrl && currentUrl !== "about:blank") {
         let currentRoute;
         try {
           currentRoute = normalizedRouteUrl(currentUrl);
@@ -3888,18 +4659,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 +4692,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 +4708,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) {
@@ -4007,8 +4797,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         result.accessibility_audits = continuation?.accessibilityAudits || [];
         if (continuation?.downloadLedger) Object.assign(downloadLedger, continuation.downloadLedger);
         const planStarted = performance.now();
-        const runAllSteps = plan.steps.some(({ action, expectDownload }) => action.startsWith("assert_")
-          || ["navigate", "clear", "clear_storage", "new_tab", "new_context", "switch_tab", "screenshot", "wait_for_request", "upload_file", "select_option", "hover", "like_comment", "unlike_comment", "audit_accessibility"].includes(action)
+        const runAllSteps = plan.steps.some(({ action, expectDownload }) => action.startsWith("assert_")
+          || ["navigate", "clear", "clear_storage", "new_tab", "new_context", "switch_tab", "screenshot", "wait_for_request", "upload_file", "generate_fixture", "http_request", "assert_db", "assert_log", "start_email_capture", "assert_email", "assert_remote_file", "delete_remote_file", "run_hook", "select_option", "hover", "like_comment", "unlike_comment", "audit_accessibility"].includes(action)
           || expectDownload === true);
         let approvedMutationIndex = continuation?.nextStep;
         for (let index = continuation?.nextStep || 0; index < plan.steps.length; index += 1) {
@@ -4060,7 +4850,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
             if (index === approvedMutationIndex) approvedMutationIndex = undefined;
             if (step.fragileName) addDiagnostic(result.warnings, `step ${index + 1} uses an empty accessible name with index ${step.index}; this target is fragile`, settings.jev.maxDiagnosticItems);
             if (step.fragileSelector) addDiagnostic(result.warnings, `step ${index + 1} uses an explicit CSS/XPath selector as a last resort`, settings.jev.maxDiagnosticItems);
-            if (step.action === "click" && plan.steps[index + 1]?.action === "confirm_dialog") {
+            await integrationSession?.markStep?.(index + 1);
+            if (step.action === "click" && plan.steps[index + 1]?.action === "confirm_dialog") {
               nativeDialog.expectedStep = interpolateStep(plan.steps[index + 1], variables);
               nativeDialog.result = undefined;
             } else if (step.action !== "confirm_dialog") {
@@ -4068,17 +4859,25 @@ 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,
-              allowMutations: options.allowMutations,
+            const execution = {
+              networkTracker,
+              networkMarker,
+              initialNavigationMarker,
+              flowNetworkMarker: initialNetworkMarker,
+              autoAngularIdle: options.autoAngularIdle,
+              readyStableMs: options.readyStableMs,
+              localOnly: options.localOnly,
+              allowMutations: options.allowMutations || index === approvedMutationIndex,
+              environmentProfile: selectedProfile,
+              integrationSession,
+              downloadLedger,
               browserPool,
               nativeDialog,
-              preResolvedTarget: mutationInspection.target,
-              popupPage,
-              variables,
+              preResolvedTarget: mutationInspection.target,
+              requestObserver: requestObservers.get(`${planId}:${index}`),
+              popupPage,
+              variables,
+              secrets,
               context,
               contextStack,
               capture,
@@ -4096,6 +4895,7 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
               },
             };
             const traceStep = await executeStep(stepPage, step, settings, snapshot, secrets, downloadLedger, execution);
+            armAvailableRequestObservers();
             popupPage = execution.popupPage;
             if (traceStep.activeContext) context = traceStep.activeContext;
             const nextActivePage = traceStep.activePage;
@@ -4130,18 +4930,20 @@ 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;
+        if (options.stopOnExpected && outcome && !runAllSteps && containsExpectedOutcome(snapshot, outcome)) break;
           } catch (error) {
             environmentFailure = browserDisconnected(error);
             failure = error instanceof JevBrowserError
@@ -4160,7 +4962,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 +4974,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;
@@ -4236,8 +5040,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         }
       }
     }
-  } catch (error) {
-    const authenticationFailure = networkTracker.authenticationFailureSince(initialNetworkMarker);
+  } catch (error) {
+    const authenticationFailure = networkTracker.authenticationFailureSince(initialNetworkMarker);
     const disconnected = (!options.freshContext && browserPool.getNavigationError?.() === "BROWSER_DISCONNECTED") || browserDisconnected(error);
     if (authenticationFailure) {
       navigationError = "AUTHENTICATION_REQUIRED";
@@ -4339,7 +5143,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 +5152,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 +5172,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;
@@ -4371,10 +5184,64 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
       safeResult.artifact_errors = [...(safeResult.artifact_errors || []), error instanceof JevBrowserError ? error.message : "flow report could not be saved"];
     }
   }
-  return safeResult;
-}
-
-export async function chooseNextAction({ flow, pageSnapshot, actions, completedSteps = [], localOnly = false, settings, fetchImpl = fetch }) {
+  return safeResult;
+}
+
+function candidatePlansIncludeUpload(candidatePlans) {
+  const plans = isRecord(candidatePlans) && Array.isArray(candidatePlans.steps)
+    ? [candidatePlans]
+    : isRecord(candidatePlans) ? Object.values(candidatePlans) : [];
+  return plans.some((plan) => isRecord(plan)
+    && Array.isArray(plan.steps)
+    && plan.steps.some((step) => isRecord(step) && (
+      step.action === "upload_file" || step.action === "generate_fixture"
+      || step.action === "http_request" && Array.isArray(step.multipart) && step.multipart.some((field) => isRecord(field) && field.file_path)
+    )));
+}
+
+export async function executeBrowserFlow(args) {
+  const run = async () => {
+    const ownsIntegrationSession = !args.integrationSession;
+    let integrationSession = args.integrationSession;
+    let result;
+    let flowError;
+    try {
+      if (!integrationSession) integrationSession = createIntegrationSession(args.settings, args.options?.environment_profile);
+      if (ownsIntegrationSession) await integrationSession.markFlowStart();
+      result = await executeBrowserFlowCore({ ...args, integrationSession });
+    } catch (error) {
+      flowError = error;
+    } finally {
+      if (ownsIntegrationSession) await integrationSession?.close?.();
+    }
+    const retainFilesForConfirmation = result?.status === "confirmation_required" || result?.status === "dry_run";
+    let cleanupError;
+    if (candidatePlansIncludeUpload(args.candidatePlans) && !args.retainUploadStaging && !retainFilesForConfirmation && args.settings.browser.managedUploadStaging) {
+      try {
+        await cleanupUploadStagingDirectory(args.settings);
+      } catch {
+        cleanupError = true;
+      }
+    }
+    if (flowError) {
+      if (cleanupError) throw new JevBrowserError("the browser flow failed and managed upload staging cleanup also failed");
+      throw flowError;
+    }
+    if (cleanupError) {
+      result.status = "failed";
+      result.acceptance_criteria_met = false;
+      result.reason = "The browser flow finished, but managed upload staging cleanup failed.";
+      result.artifact_errors = [...(result.artifact_errors || []), "managed upload staging cleanup failed"];
+    }
+    return result;
+  };
+  if (args.settings.browser.managedUploadStaging && candidatePlansIncludeUpload(args.candidatePlans)) {
+    return withUploadStagingLock(args.settings, run);
+  }
+  return run();
+}
+
+export async function chooseNextAction({ flow, pageSnapshot, actions, completedSteps = [], localOnly = false, settings, fetchImpl = fetch }) {
   if (localOnly) throw new JevBrowserError("local_only is enabled; choose_next_action cannot call the Jev provider");
   const { request, criteria } = buildChoicePayload({ flow, pageSnapshot, actions, completedSteps }, settings.jev);
   return parseDecision(await requestJev(request, settings, fetchImpl), criteria);