@diegosouzacdv/jev-browser-mcp 0.7.1 → 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,6 +64,7 @@ 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",
@@ -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,14 +234,23 @@ 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: [], optional: ["path", "screen", "toggle_selector", "timeout_seconds"] },
         assert_network: { required: ["url_contains", "method", "status"], optional: ["message_contains", "timeout_seconds", "timeout_ms"] },
         assert_ws: { required: ["url_contains"], optional: ["message_contains", "json", "close_code", "timeout_seconds", "timeout_ms"] },
         wait_for_request: { required: ["url"], optional: ["method", "status", "timeout_seconds", "timeout_ms"] },
-        http_request: { required: ["url"], optional: ["method", "include_body", "timeout_seconds", "timeout_ms"] },
+        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"] },
@@ -248,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"] },
@@ -260,7 +281,7 @@ 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 {
@@ -272,16 +293,71 @@ export function describeBrowserActions() {
         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",
-      local_only: "required for http_request, read_angular_state and inspect_cookies; only localhost loopback is allowed",
+      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",
@@ -301,7 +377,7 @@ 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.",
   };
@@ -601,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)) {
@@ -675,13 +751,128 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
       if (action === "http_request") {
         step.url = requiredText(rawStep.url, "http_request URL", settings.jev.maxActionDescriptionChars);
         step.method = rawStep.method === undefined ? "GET" : requiredText(rawStep.method, "http_request method", 16).toUpperCase();
-        if (step.method !== "GET") throw new JevBrowserError("http_request supports GET only");
+        if (!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 === "evaluate") {
+      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");
@@ -727,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)) {
@@ -794,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"
@@ -880,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;
@@ -933,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) {
@@ -1092,7 +1310,8 @@ function resolveFlowOptions(rawOptions, settings) {
     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]),
@@ -1137,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);
@@ -1287,24 +1524,24 @@ function redactLocalPayload(value) {
   ]));
 }
 
-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) {
@@ -1807,6 +2044,9 @@ function createNetworkTracker(page, settings, loginUrlContains = [], watchPatter
   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();
@@ -1855,12 +2095,29 @@ function createNetworkTracker(page, settings, loginUrlContains = [], watchPatter
     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);
@@ -1958,7 +2215,7 @@ function createNetworkTracker(page, settings, loginUrlContains = [], watchPatter
     websocketObserverPromises.add(ready);
     return ready;
   };
-  const historySince = (marker) => [...new Map([...history, ...watchedHistory]
+  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);
@@ -1966,6 +2223,61 @@ function createNetworkTracker(page, settings, loginUrlContains = [], watchPatter
     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) => historySince(marker).filter((entry) =>
@@ -2031,6 +2343,8 @@ function createNetworkTracker(page, settings, loginUrlContains = [], watchPatter
       trackedPages.clear();
       active.clear();
       ignored.clear();
+      for (const observer of [...responseObservers]) observer.dispose();
+      responseObservers.clear();
       await Promise.allSettled([...pendingHeaderReads]);
       pendingHeaderReads.clear();
       cdpRequestUrls.clear();
@@ -2178,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`);
 }
 
@@ -2714,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);
 }
 
@@ -2754,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) {
@@ -2936,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) {
@@ -2957,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");
@@ -3009,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");
@@ -3070,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);
@@ -3139,6 +3465,16 @@ async function navigateMenu(page, root, step, settings, execution) {
 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" };
   }
@@ -3148,69 +3484,13 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
       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 === "http_request") {
-    assertLocalDebugPage(page, execution.localOnly, "http_request");
-    const pageUrl = new URL(page.url());
-    const requestUrl = new URL(step.url, pageUrl);
-    if (requestUrl.origin !== pageUrl.origin || !localHostOnly(requestUrl.toString())) {
-      throw new JevBrowserError("http_request must target the current localhost origin");
-    }
-    const reply = await page.evaluate(async ({ url, includeBody, maxBytes }) => {
-      const response = await fetch(url, {
-        method: "GET", credentials: "same-origin", redirect: "error", cache: "no-store",
-      });
-      const headers = {};
-      for (const name of ["cache-control", "content-length", "content-type", "date", "etag", "last-modified", "retry-after", "vary"]) {
-        const value = response.headers.get(name);
-        if (value !== null) headers[name] = value.slice(0, 256);
-      }
-      let body = "";
-      let truncated = false;
-      if (includeBody && response.body) {
-        const reader = response.body.getReader();
-        const chunks = [];
-        let size = 0;
-        while (size <= maxBytes) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          const chunk = value.slice(0, Math.max(0, maxBytes + 1 - size));
-          chunks.push(chunk);
-          size += chunk.length;
-          if (size > maxBytes || chunk.length < value.length) {
-            truncated = true;
-            await reader.cancel();
-            break;
-          }
-        }
-        const bytes = new Uint8Array(size);
-        let offset = 0;
-        for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
-        body = new TextDecoder().decode(bytes.slice(0, maxBytes));
-      }
-      return { status: response.status, ok: response.ok, headers, body, body_truncated: truncated };
-    }, { url: requestUrl.toString(), includeBody: step.includeBody, maxBytes: settings.browser.maxNetworkErrorBodyBytes });
-    let responseBody;
-    if (step.includeBody && reply.body) {
-      try { responseBody = redactLocalPayload(JSON.parse(reply.body)); }
-      catch { responseBody = sanitizeDiagnosticText(reply.body, secrets, settings.browser.maxNetworkErrorMessageChars); }
-    }
-    return {
-      action: step.action,
-      method: "GET",
-      url: evidenceUrl(requestUrl.toString(), secrets, settings.jev.maxDiagnosticChars),
-      status: reply.status,
-      ok: reply.ok,
-      response_headers: reply.headers,
-      ...(step.includeBody ? { response_body: responseBody ?? "", body_truncated: reply.body_truncated } : {}),
-    };
-  }
   if (step.action === "inspect_cookies") {
     assertLocalDebugPage(page, execution.localOnly, "inspect_cookies");
     const cookies = await execution.context.cookies([page.url()]);
@@ -3285,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);
@@ -3311,9 +3593,15 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     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.flowNetworkMarker ?? execution.networkMarker, timeout, settings);
+    const request = await waitForRequestAssertion(
+      execution.networkTracker,
+      step,
+      execution.flowNetworkMarker ?? execution.networkMarker,
+      timeout,
+      execution.requestObserver,
+    );
     return {
-      action: step.action, asserted: true, method: request.method, status: request.status,
+      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),
@@ -3404,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");
@@ -3663,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)) };
@@ -4025,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];
@@ -4043,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)) {
@@ -4075,46 +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");
+  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 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 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)
@@ -4159,7 +4523,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   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,
@@ -4172,10 +4537,30 @@ 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 };
+  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 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 = [];
@@ -4248,6 +4633,9 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         }
       }
       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 {
@@ -4409,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) {
@@ -4462,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") {
@@ -4478,12 +4867,17 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
               autoAngularIdle: options.autoAngularIdle,
               readyStableMs: options.readyStableMs,
               localOnly: options.localOnly,
-              allowMutations: options.allowMutations,
+              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,
@@ -4501,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;
@@ -4548,7 +4943,7 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
               );
             }
             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
@@ -4645,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";
@@ -4789,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);