@enricai/barnacle 1.6.14 → 1.7.1

package/dist/scraper/flow-runner.js

@@ -77,7 +77,7 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
-const zod_1 = require("@anthropic-ai/sdk/helpers/zod");
+const ai_1 = require("ai");
 const config_1 = require("../config");
 const errors_1 = require("../lib/errors");
 const error_messages_1 = require("../lib/llm/judges/error-messages");
@@ -480,7 +480,7 @@ exports.TRAILING_GRACE_WINDOW = 2;
  * means no injection surface. Runs in browser context and returns a typed-narrow
  * shape via Runtime.callFunctionOn.
  */
-const DOM_SNAPSHOT_EXPR = `(() => { const b = document.body; if (!b) return { html: 0, text: "" }; const t = b.innerText || ""; return { html: (b.outerHTML || "").length, text: t.length + ":" + t.slice(0, 200) }; })()`;
+const DOM_SNAPSHOT_EXPR = `(() => { const b = document.body; if (!b) return { html: 0, text: "", values: "" }; const t = b.innerText || ""; const controls = Array.from(b.querySelectorAll("input, textarea, select")).filter((el) => el.offsetParent !== null); const values = controls.map((el) => { if (el.type === "checkbox" || el.type === "radio") return el.checked ? "1" : "0"; return el.value || ""; }).join("|").slice(0, 2000); return { html: (b.outerHTML || "").length, text: t.length + ":" + t.slice(0, 200), values }; })()`;
 /**
  * Captures the pre/post signal triple the submit-verify cascade diffs.
  * Accepts the optional `page` so a resolved child `FrameTarget` whose
@@ -491,6 +491,7 @@ const DOM_SNAPSHOT_EXPR = `(() => { const b = document.body; if (!b) return { ht
 async function snapshotPage(target, signalCounter, page) {
     let bodyHtmlLength = 0;
     let visibleTextSignature = "";
+    let formValueSignature = "";
     try {
         const result = await target.evaluate(DOM_SNAPSHOT_EXPR);
         if (result !== null &&
@@ -501,6 +502,8 @@ async function snapshotPage(target, signalCounter, page) {
             typeof result.text === "string") {
             bodyHtmlLength = result.html;
             visibleTextSignature = result.text;
+            const rawValues = result.values;
+            formValueSignature = typeof rawValues === "string" ? rawValues : "";
         }
     }
     catch {
@@ -519,6 +522,7 @@ async function snapshotPage(target, signalCounter, page) {
         url,
         bodyHtmlLength,
         visibleTextSignature,
+        formValueSignature,
     };
 }
 /**
@@ -906,11 +910,15 @@ function isDomOnlyAdvanceVerified(params) {
  * to the network/URL signal — which correctly verifies navigation but
  * false-negatives client-side view swaps. This gate fills that gap.
  *
- * **Threshold rationale:** 5000B is 10× the trivial boundary (500B) and
- * safely distinguishes real view swaps (measured case: +49518B) from
+ * **Threshold rationale:** default 5000B is 10× the trivial boundary (500B)
+ * and safely distinguishes real view swaps (measured case: +49518B) from
  * validation-error reflows (typically < 2KB per codebase evidence at
  * line 2040-2044: error text capped at 200 chars, container markup adds
- * 150-350B per error, worst-case ~10 errors = ~3500B max).
+ * 150-350B per error, worst-case ~10 errors = ~3500B max). Some sites render
+ * much smaller popups/comboboxes whose open-click grows the DOM by only a
+ * few hundred bytes; `config.scraper.viewSwapMinBytesThreshold`
+ * (`VIEW_SWAP_MIN_BYTES` env var) lets a deployment lower the threshold
+ * without regressing the shared default for other sites.
  *
  * **Scope guards:** Excludes final/submit steps (those require real network
  * per isSubmitRevealedInvalid + LLM submit judge) and advance-pattern steps
@@ -918,7 +926,7 @@ function isDomOnlyAdvanceVerified(params) {
  * to avoid wizard-ATS autosave-vs-transition ambiguity).
  */
 function isClickViewSwapVerified(params) {
-    const VIEW_SWAP_MIN_BYTES = 5000;
+    const VIEW_SWAP_MIN_BYTES = config_1.config.scraper.viewSwapMinBytesThreshold;
     const { resolvedAction, isFinalStep, submitStep, isAdvanceWithPattern, networkDelta, bytesDelta, } = params;
     if (resolvedAction?.method !== "click")
         return false;
@@ -972,6 +980,7 @@ function describeAttemptEffectSignals(pre, post, recentCaptureMeta, preMetaLengt
     const bytesDelta = post.bodyHtmlLength - pre.bodyHtmlLength;
     const networkDelta = post.networkCount - pre.networkCount;
     const textChanged = post.visibleTextSignature !== pre.visibleTextSignature;
+    const valueChanged = post.formValueSignature !== pre.formValueSignature;
     const windowCaptures = recentCaptureMeta.slice(preMetaLength);
     const observations = [];
     if (networkDelta === 0 && bytesDelta >= 500) {
@@ -986,6 +995,9 @@ function describeAttemptEffectSignals(pre, post, recentCaptureMeta, preMetaLengt
     if (textChanged && networkDelta === 0 && bytesDelta < 500) {
         observations.push("visible-text-changed-without-network: page reflowed slightly (likely tooltip/focus state)");
     }
+    if (valueChanged && !textChanged && networkDelta === 0) {
+        observations.push("form-value-changed-without-network: a visible input/textarea/select value changed with no other observable effect (plain field fill)");
+    }
     return observations.join(" | ");
 }
 /**
@@ -1036,7 +1048,7 @@ function shouldSkipTechnique(params) {
     // structured-click / observe-act-exclude re-resolves the SAME
     // light-DOM-only view of the page and would no-op identically, so skip
     // straight to deep-submit-locator (attempt 2) instead. llm-rephrase
-    // (attempt 5) is never skipped — a differently-worded instruction is still
+    // (attempt 4) is never skipped — a differently-worded instruction is still
     // a distinct attempt worth trying if the deep locator also fails. Gated on
     // submitShapedStep: the deep submit-control locator ranks submit-shaped
     // candidates only, so on a non-submit control (e.g. a radio/checkbox) it
@@ -1143,8 +1155,8 @@ function isAdvanceStalled(params) {
     return networkFired;
 }
 /**
- * Lazy Anthropic client for attempt 4's rephrase. Returns null when the
- * deployment is Bedrock-only (no ANTHROPIC_API_KEY) — attempt 4 then becomes
+ * Lazy Anthropic client for attempt 5's rephrase. Returns null when the
+ * deployment is Bedrock-only (no ANTHROPIC_API_KEY) — attempt 5 then becomes
  * a no-op and the executor escalates straight to the failure dump. The other
  * three attempts already cover the lion's share of recovery.
  */
@@ -1165,7 +1177,7 @@ function anthropicModelName() {
  */
 const REPHRASE_SYSTEM_PROMPT = "You rewrite a failed Stagehand act() instruction so the next attempt targets a different element than those already tried. If no different element exists on the page that could plausibly unblock the flow, return outcome=impossible. Never re-propose a selector or wording from the lists labeled SELECTORS ALREADY TRIED or INSTRUCTION TEXT ALREADY TRIED.";
 /**
- * Attempt-4 of the step-healing cascade: when three mechanical retry variations
+ * Attempt-5 of the step-healing cascade: when three mechanical retry variations
  * all fail, this is the last resort before the step is declared terminal. Exported
  * so tests can inject a fake capture sink without touching the browser session.
  */
@@ -1219,13 +1231,21 @@ priorAttempts,
  * "click harder" into "fill the actually-missing field." Telemetry
  * the engine already captures but never showed the LLM until now.
  */
-gaEventEvidence) {
+gaEventEvidence, 
+/**
+ * Anthropic client for the modal-priority judge inside
+ * `renderUnfocusedObserve`. Separate from `client` (the ai-SDK model used
+ * for the rephrase call itself) because that judge pipeline is unrelated
+ * to which provider generates the rephrase, and null on a Bedrock-only
+ * deployment falls back to `renderUnfocusedObserve`'s source-order default.
+ */
+judgeClient) {
     const candidateList = observeCandidates
         .slice(0, 12)
         .map((a, i) => `${i + 1}. ${a.description} — ${a.selector}`)
         .join("\n");
     const unfocusedList = unfocusedObserve
-        ? await renderUnfocusedObserve(unfocusedObserve, { client, captureFn })
+        ? await renderUnfocusedObserve(unfocusedObserve, { client: judgeClient, captureFn })
         : "";
     const triedList = triedSelectors.length > 0 ? triedSelectors.join("\n") : "(none)";
     const reasonList = failureReasons.map((r, i) => `attempt ${i + 1}: ${r}`).join("\n");
@@ -1297,35 +1317,28 @@ PAGE TRANSITION + VALIDATOR TELEMETRY (parsed from Google Analytics Measurement
 ${gaEventEvidence || "(none)"}
 
 Rewrite the instruction so a Stagehand act() call can resolve it unambiguously to a different element than the ones already tried. Keep it short — one sentence, natural language, no quotes around it. If the invalid-fields section above names a field AND the interactive-targets section below lists clickable options inside that same container, your rewrite picks one of those options (e.g. for a yes/no question rendered as two radio labels, choose the candidate-favorable answer — 'No' for "do you have a non-compete", 'Yes' for "are you authorized to work", 'Prefer not to say' for demographic disclosures) rather than retrying the original click. If the unfocused observe section shows an open modal/dialog with a Save or Close action, your rewrite invokes that action so the underlying form can clear its blocking state. Set outcome to "impossible" with a one-line reason only when the original instruction's element does not exist on the current page and no redirect target is available.`;
-    const model = anthropicModelName();
+    const model = client.modelId;
     const t0 = performance.now();
     try {
-        const response = await client.messages.parse({
-            model,
-            max_tokens: 400,
+        const response = await (0, ai_1.generateObject)({
+            model: client,
+            maxOutputTokens: 400,
             system: REPHRASE_SYSTEM_PROMPT,
-            messages: [{ role: "user", content: prompt }],
-            output_config: {
-                format: (0, zod_1.zodOutputFormat)(schemas_1.REPHRASE_RESPONSE_SCHEMA),
-            },
+            prompt,
+            schema: schemas_1.REPHRASE_RESPONSE_SCHEMA,
         });
         const latencyMs = performance.now() - t0;
-        const parsed = response.parsed_output;
-        if (parsed === null) {
-            throw new Error("structured-output enabled but parsed_output is null");
-        }
-        const textBlock = response.content.find((b) => b.type === "text");
-        const rawText = textBlock?.type === "text" ? textBlock.text : "";
+        const parsed = response.object;
         await captureFn({
             callId: (0, node_crypto_1.randomUUID)(),
             callType: call_types_1.CALL_TYPE_RECON_REPHRASE,
             model,
             systemPrompt: REPHRASE_SYSTEM_PROMPT,
             userContent: prompt,
-            responseContent: rawText,
+            responseContent: JSON.stringify(parsed),
             parsedOk: true,
-            inputTokens: response.usage?.input_tokens ?? null,
-            outputTokens: response.usage?.output_tokens ?? null,
+            inputTokens: response.usage.inputTokens ?? null,
+            outputTokens: response.usage.outputTokens ?? null,
             latencyMs,
             success: true,
             errorMessage: null,
@@ -2273,9 +2286,13 @@ const UPLOAD_NETWORK_POLL_INTERVAL_MS = 250;
  * wizard lands on the Apply page, so a single probe races that mount and the
  * primitive wrongly falls into the click-to-surface path (or skips). Only
  * reached on `upload:true` steps, so it never slows a page with no upload step.
+ * The poll exits on first success, so raising the attempt count via
+ * `config.scraper.uploadWidgetRenderAttempts` (`UPLOAD_WIDGET_RENDER_ATTEMPTS`
+ * env var) costs nothing extra for sites that mount promptly — only sites
+ * whose upload field mounts conditionally (e.g. only after a prior step
+ * commits) and needs a longer window should override the default.
  */
 const UPLOAD_WIDGET_RENDER_INTERVAL_MS = 600;
-const UPLOAD_WIDGET_RENDER_ATTEMPTS = 17;
 /**
  * URL substrings that mark a POST as an actual resume/attachment upload rather
  * than coincidental traffic (analytics beacons, `/interruption_check`,
@@ -2385,7 +2402,10 @@ async function tryUploadPrimitive(params) {
     // already rendered it pay nothing.
     let inputCount = 0;
     try {
-        inputCount = await pollEnumerate(page, target, "document.querySelectorAll('input[type=file]').length", (n) => (n ?? 0) > 0, { attempts: UPLOAD_WIDGET_RENDER_ATTEMPTS, intervalMs: UPLOAD_WIDGET_RENDER_INTERVAL_MS });
+        inputCount = await pollEnumerate(page, target, "document.querySelectorAll('input[type=file]').length", (n) => (n ?? 0) > 0, {
+            attempts: config_1.config.scraper.uploadWidgetRenderAttempts,
+            intervalMs: UPLOAD_WIDGET_RENDER_INTERVAL_MS,
+        });
     }
     catch (err) {
         logger.warn(`upload primitive: file-input probe threw: ${(0, errors_1.toErrorMessage)(err)}`);
@@ -2534,7 +2554,7 @@ async function surfaceAndUpload(params) {
     return { present: false };
   })()`;
     const gate = await pollEnumerate(page, target, targetExpr, (r) => r?.present === true, {
-        attempts: UPLOAD_WIDGET_RENDER_ATTEMPTS,
+        attempts: config_1.config.scraper.uploadWidgetRenderAttempts,
         intervalMs: UPLOAD_WIDGET_RENDER_INTERVAL_MS,
     });
     if (!gate?.present) {
@@ -2843,6 +2863,24 @@ function resolveDeepLocatorActuation(step) {
 function normalizeFieldLabel(text) {
     return text.replace(/\s+/g, " ").trim().toLowerCase();
 }
+/**
+ * Parses a fill/select step into the field it names plus the value to write,
+ * or `null` for any other step shape (click, a select whose question is
+ * un-quoted, etc). Shared by both the observe-empty deepLocator fallback and
+ * the field-label-first routing ahead of Stagehand's own act()/observe()
+ * resolution — see `findDeepLocatorCandidateByFieldLabel`'s docblock for why
+ * the field LABEL (not the value) is what a caller matches candidates
+ * against.
+ */
+function parseFieldLabelTarget(step) {
+    const fillStep = parseFillStep(step);
+    if (fillStep)
+        return { kind: "fill", fieldLabel: fillStep.fieldLabel, value: fillStep.value };
+    const selectStep = parseSelectStep(step);
+    return selectStep?.questionLabel
+        ? { kind: "select", fieldLabel: selectStep.questionLabel, value: selectStep.option }
+        : null;
+}
 /**
  * Finds the candidate whose accessible name identifies the named field —
  * `fieldLabel` (from {@link parseFillStep}/{@link parseSelectStep}), NOT the
@@ -3675,15 +3713,15 @@ async function tryRadioPrimitive(params) {
     const { option, questionLabel } = parsed;
     const optLabel = `option "${option.slice(0, 40)}"${questionLabel ? `, question "${questionLabel.slice(0, 40)}"` : ""}`;
     // Phase 1 (browser): find radio GROUPS and their options. A group is a
-    // `<fieldset>` / `[role=radiogroup]` / `[class*='RadioGroup']` container with
-    // radios. Question label = the group's legend / associated label; each option
+    // `<fieldset>` / `[role=radiogroup]` / `[role=group]` / `[class*='RadioGroup']`
+    // container with radios. Question label = the group's legend / associated label; each option
     // = the `<label for=radio-id>` text. Deterministic unique option-text match
     // commits immediately (no LLM). Else return groups for the LLM picker.
     // `commit` uses the React-safe native `checked` setter so MUI/React registers
     // the change, then reports `ok` = post-commit `radio.checked && !invalid`.
     const enumerateExpr = `((option) => {
     const norm = (s) => (s || "").replace(/\\s+/g, " ").trim().toLowerCase();
-    let groupEls = Array.from(document.querySelectorAll("fieldset,[role='radiogroup'],[class*='RadioGroup']"))
+    const groupEls = Array.from(document.querySelectorAll("fieldset,[role='radiogroup'],[role='group'],[class*='RadioGroup']"))
       .filter((g) => g.querySelector("input[type=radio]"));
     if (groupEls.length === 0) return { groupPresent: false };
     const groupLabel = (g) => {
@@ -3881,7 +3919,7 @@ async function applyRadioSelection(target, gi, ri, hint) {
     // Tier C — legacy synthetic-events backstop (native setter + bubbling events).
     const applyExpr = `((gi, ri) => {
       const isInvalid = ${INVALID_MARKER_EL_EXPR};
-      const groupEls = Array.from(document.querySelectorAll("fieldset,[role='radiogroup'],[class*='RadioGroup']"))
+      const groupEls = Array.from(document.querySelectorAll("fieldset,[role='radiogroup'],[role='group'],[class*='RadioGroup']"))
         .filter((g) => g.querySelector("input[type=radio]"));
       const grp = groupEls[gi];
       if (!grp) return { ok: false };
@@ -4174,10 +4212,15 @@ async function verifyDomEffect(target, action) {
                 // Same trust-boundary rationale as the click case below: xpath is from
                 // Stagehand's resolved selector, JSON.stringify produces a safe JS string
                 // literal, and the expression cannot inject behavior through xpath content.
-                const expr = `(() => { const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); const el = r.singleNodeValue; if (!el || el.tagName !== "SELECT") return null; const opt = el.options[el.selectedIndex]; if (!opt) return { value: "", label: "", text: "" }; return { value: (opt.value || "").trim(), label: (opt.label || "").trim(), text: (opt.textContent || "").trim() }; })()`;
+                // Custom (non-native-<select>) comboboxes — MUI/React-Select/Radix/Headless
+                // UI-style widgets — always fail the native-<select>-only check below,
+                // misreporting genuinely-successful selections as unverified. Fall back to
+                // reading the combobox's own displayed/aria value when the resolved element
+                // isn't a real <select>, mirroring what a real ARIA combobox exposes.
+                const exprNative = `(() => { const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); const el = r.singleNodeValue; if (!el || el.tagName !== "SELECT") return null; const opt = el.options[el.selectedIndex]; if (!opt) return { value: "", label: "", text: "" }; return { value: (opt.value || "").trim(), label: (opt.label || "").trim(), text: (opt.textContent || "").trim() }; })()`;
                 let selected = null;
                 try {
-                    const result = await target.evaluate(expr);
+                    const result = await target.evaluate(exprNative);
                     if (result !== null &&
                         typeof result === "object" &&
                         "value" in result &&
@@ -4189,6 +4232,42 @@ async function verifyDomEffect(target, action) {
                 catch {
                     return false;
                 }
+                if (!selected) {
+                    // MUI-style comboboxes render role="combobox" on a wrapper element with a
+                    // nested (often hidden/readonly) `<input value="...">` carrying the real
+                    // selected value — neither the wrapper nor the resolved element necessarily
+                    // has a usable `.value` itself, so search the element, its combobox
+                    // ancestor, and — since some resolved xpaths land on a sibling label rather
+                    // than the combobox itself — the nearest combobox within the same
+                    // field-group container, for a nested input value, falling back to visible
+                    // text or an aria label/valuetext.
+                    const exprCustom = `(() => {
+            const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+            const el = r.singleNodeValue;
+            if (!el) return null;
+            let combo = (el.closest && el.closest('[role="combobox"]')) || null;
+            if (!combo) {
+              const container = el.closest && (el.closest('[class*="Container"]') || el.parentElement);
+              combo = container && container.querySelector && container.querySelector('[role="combobox"]');
+            }
+            combo = combo || el;
+            const nestedInput = combo.querySelector && combo.querySelector('input');
+            const value = (nestedInput && nestedInput.value) || el.value || "";
+            const text = (combo.textContent || el.textContent || "").trim();
+            const ariaText = (el.getAttribute && (el.getAttribute('aria-label') || el.getAttribute('aria-valuetext'))) || "";
+            return { value: String(value).trim(), text: String(text || ariaText).trim() };
+          })()`;
+                    try {
+                        const customResult = await target.evaluate(exprCustom);
+                        if (customResult !== null && typeof customResult === "object") {
+                            const custom = customResult;
+                            selected = { value: custom.value ?? "", label: "", text: custom.text ?? "" };
+                        }
+                    }
+                    catch {
+                        return false;
+                    }
+                }
                 if (!selected)
                     return false;
                 const want = expected.toLowerCase();
@@ -4564,6 +4643,36 @@ async function resolveDeepLocatorCandidatesWithWidening(page, frameSelector, ins
     const widened = await (0, deep_locator_candidates_1.resolveDeepLocatorCandidates)(page, frameSelector, "*", instruction, timeoutOptions);
     return { candidates: widened, innerSelector: "*" };
 }
+/**
+ * Resolves and actuates a fill/select step's NAMED FIELD through the
+ * deterministic accessible-name match (`findDeepLocatorCandidateByFieldLabel`)
+ * against the frame's own deepLocator scan, independent of what Stagehand's
+ * `act()`/`observe()` resolved. A same-frame accessible-name label match
+ * cannot confuse a City input for an unrelated header search box the way
+ * Stagehand's semantic resolution can — Stagehand's own candidate is only a
+ * fallback for the caller to use when this returns `no-match` or
+ * `not-fill-or-select`, never the first attempt for a step that names a
+ * field. `triedSelectors` (already-attempted selectors from prior
+ * cascade attempts) is excluded so a step that already tried and failed on
+ * this candidate doesn't just re-pick it.
+ */
+async function tryDeterministicFieldLabelActuation(params) {
+    const { page, frameTarget, step, triedSelectors, timeoutOptions } = params;
+    const fieldTarget = parseFieldLabelTarget(step);
+    if (!fieldTarget)
+        return { kind: "not-fill-or-select" };
+    const { candidates, innerSelector } = await resolveDeepLocatorCandidatesWithWidening(page, frameTarget.frameSelector, step, timeoutOptions);
+    const unexcluded = candidates.filter((c) => !triedSelectors.includes(c.selector));
+    const matched = findDeepLocatorCandidateByFieldLabel(unexcluded, fieldTarget.fieldLabel);
+    if (!matched)
+        return { kind: "no-match", fieldTarget };
+    const actuated = fieldTarget.kind === "fill"
+        ? await (0, deep_locator_actuate_1.fillDeepLocatorCandidate)(page, frameTarget.frameSelector, innerSelector, matched.index, fieldTarget.value, { frameTarget })
+        : await (0, deep_locator_actuate_1.selectDeepLocatorCandidateOption)(page, frameTarget.frameSelector, innerSelector, matched.index, fieldTarget.value, { frameTarget });
+    return actuated
+        ? { kind: "actuated", matched, fieldTarget }
+        : { kind: "actuation-failed", matched, fieldTarget };
+}
 /**
  * Adapts `resolveDeepLocatorCandidatesWithWidening` results into
  * `Action`-shaped evidence for `rephraseWithLLM`, which only knows about
@@ -4674,7 +4783,7 @@ async function probeStepBeforeAttempts(params) {
     }
 }
 async function executeStepWithHealing(params) {
-    const { stagehand, page, step, optional, upload, submitStep, stepIndex, totalSteps, phase, signalCounter, recentCaptures, recentCaptureMeta, anthropic, logger, captureFn, uploadFixture, isFinalStep, submitEndpointPattern, submittedStateSelectors, requireSubmitEndpointMatch, advanceTransitionBodyPattern, successUrlFragments, successPageTitleHints, ownBackendHostnames, knownErrorClassPrefixes, wizardExitButtonLabels, getSuppressedAisdkElementIdErrorCount, trajectory, onStepFailure, } = params;
+    const { stagehand, page, step, optional, upload, submitStep, stepIndex, totalSteps, phase, signalCounter, recentCaptures, recentCaptureMeta, anthropic, rephraseModel, logger, captureFn, uploadFixture, isFinalStep, submitEndpointPattern, submittedStateSelectors, requireSubmitEndpointMatch, advanceTransitionBodyPattern, successUrlFragments, successPageTitleHints, ownBackendHostnames, knownErrorClassPrefixes, wizardExitButtonLabels, getSuppressedAisdkElementIdErrorCount, trajectory, onStepFailure, } = params;
     // Mutable (not the destructured const above) so a lost frame-attach race
     // can be upgraded in place once the OOPIF attaches later in the cascade —
     // see reresolveFrameTargetIfLost below. Every existing reference in this
@@ -4988,6 +5097,7 @@ async function executeStepWithHealing(params) {
                 url: page.url(),
                 bodyHtmlLength: 0,
                 visibleTextSignature: "",
+                formValueSignature: "",
             };
             attempts.push({
                 attempt: 0,
@@ -5089,6 +5199,57 @@ async function executeStepWithHealing(params) {
         // from DOM re-read. Captured here so both branches of the cascade write to it.
         let resolvedAction = null;
         try {
+            // Field-label-first routing: for a frame-scoped fill/select step,
+            // Stagehand's own act()/observe() can resolve a real, in-DOM, plausible-
+            // looking control that is nonetheless the WRONG one (a City field
+            // resolving to an unrelated header search box whose accessible name
+            // overlaps semantically with "city/location" is the motivating case).
+            // A same-frame accessible-name match against the field's own label
+            // can't make that mistake, so it's tried BEFORE any Stagehand
+            // act/observe call for every attempt, not only once observe() has
+            // already come back empty (bugfix-001's finding: observe() returning a
+            // wrong-but-nonempty candidate was exactly what let the phantom-fill
+            // through the old empty-candidates-only gate). Falls through to the
+            // existing Stagehand-driven attempt when no candidate names the field
+            // at all — this only preempts Stagehand's resolution, it never expands
+            // what counts as a match.
+            const fieldLabelOutcome = attempt !== 3 && frameTarget?.frame
+                ? await tryDeterministicFieldLabelActuation({
+                    page,
+                    frameTarget,
+                    step,
+                    triedSelectors,
+                    timeoutOptions: { frameTarget },
+                })
+                : { kind: "not-fill-or-select" };
+            if (fieldLabelOutcome.kind === "actuated") {
+                record.technique = "deep-locator-field-label";
+                record.instruction = `deepLocator: ${fieldLabelOutcome.matched.accessibleText || "(no accessible text)"}`;
+                triedSelectors.push(fieldLabelOutcome.matched.selector);
+                record.triedSelectors = [fieldLabelOutcome.matched.selector];
+                record.actResultSuccess = true;
+                record.actResultDescription = `deepLocator ${fieldLabelOutcome.fieldTarget.kind === "fill" ? "filled" : "selected"} "${fieldLabelOutcome.matched.accessibleText || fieldLabelOutcome.matched.selector}" with "${fieldLabelOutcome.fieldTarget.value}"`;
+                // Same rationale as the pre-existing candidates===0 branch below:
+                // the write + read-back the actuation helper already performed IS
+                // the verification signal — no resolvedAction/network/url verifier
+                // can score a `deeplocator=` selector.
+                record.verifiedBy = "dom";
+                attempts.push(record);
+                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} attempt ${attempt}: ${record.actResultDescription}`);
+                trajectory?.push({ stepIndex, verifiedBy: "dom" });
+                return "completed";
+            }
+            if (fieldLabelOutcome.kind === "actuation-failed") {
+                triedSelectors.push(fieldLabelOutcome.matched.selector);
+                record.triedSelectors = [fieldLabelOutcome.matched.selector];
+                const failureMessage = `deepLocator: ${fieldLabelOutcome.fieldTarget.kind} on "${fieldLabelOutcome.matched.accessibleText || fieldLabelOutcome.matched.selector}" did not verify (read-back mismatch or rejected write)`;
+                record.actResultSuccess = false;
+                record.errorMessage = failureMessage;
+                attempts.push(record);
+                failureReasons.push(failureMessage);
+                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} attempt ${attempt}: ${failureMessage}`);
+                continue;
+            }
             if (attempt === 1) {
                 record.technique = "act-string";
                 record.instruction = step;
@@ -5267,58 +5428,19 @@ async function executeStepWithHealing(params) {
                 const deepLocatorInnerSelector = deepLocatorResolution?.innerSelector ?? deep_locator_scan_1.INTERACTIVE_CANDIDATE_SELECTOR;
                 const deepLocatorCandidates = (deepLocatorResolution?.candidates ?? []).filter((c) => !triedSelectors.includes(c.selector));
                 if (candidates.length === 0 && deepLocatorCandidates.length > 0) {
-                    // A fill/select step must actuate the NAMED FIELD through the
-                    // fill/select seam, never the click-only walk below: candidate
-                    // ranking scores by the instruction's quoted VALUE (see
-                    // parseFillStep's docblock) — for "Fill in the First Name field
-                    // with 'Reginald'" no control's accessible name is ever 'Reginald',
-                    // so every candidate ties at score 0 and the click walk would fire
-                    // on whatever sits first in DOM order (the bug report's wizard
-                    // 'Close' mis-click). Detect that shape first and route
-                    // deterministically to the candidate matching the field's own
-                    // label, refusing to click when no candidate names that field.
-                    const fillStep = parseFillStep(step);
-                    const selectStep = fillStep ? null : parseSelectStep(step);
-                    const fieldTarget = fillStep
-                        ? { kind: "fill", fieldLabel: fillStep.fieldLabel, value: fillStep.value }
-                        : selectStep?.questionLabel
-                            ? { kind: "select", fieldLabel: selectStep.questionLabel, value: selectStep.option }
-                            : null;
+                    // Field-label routing for a fill/select-shaped step already ran
+                    // (and returned/continued on a MATCH) in the field-label-first
+                    // pre-check above, before this attempt's own act/observe call —
+                    // see `tryDeterministicFieldLabelActuation`. Reaching this
+                    // `if (fieldTarget)` means the pre-check found no candidate
+                    // naming the field either — the walk below scores by the
+                    // instruction's quoted VALUE (see parseFillStep's docblock), so
+                    // every candidate ties at score 0 and it would otherwise click
+                    // whichever sits first in DOM order (the bug report's wizard
+                    // 'Close' mis-click). Refuse instead of guessing.
+                    const fieldTarget = parseFieldLabelTarget(step);
                     if (fieldTarget) {
-                        const matched = findDeepLocatorCandidateByFieldLabel(deepLocatorCandidates, fieldTarget.fieldLabel);
-                        if (!matched) {
-                            const failureMessage = `deepLocator: no candidate matched field "${fieldTarget.fieldLabel}" (refusing to click an unrelated control)`;
-                            record.actResultSuccess = false;
-                            record.errorMessage = failureMessage;
-                            attempts.push(record);
-                            failureReasons.push(failureMessage);
-                            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} attempt ${attempt}: ${failureMessage}`);
-                            continue;
-                        }
-                        triedSelectors.push(matched.selector);
-                        record.triedSelectors = [matched.selector];
-                        const actuated = fieldTarget.kind === "fill"
-                            ? await (0, deep_locator_actuate_1.fillDeepLocatorCandidate)(page, frameTarget?.frameSelector, deepLocatorInnerSelector, matched.index, fieldTarget.value, { frameTarget })
-                            : await (0, deep_locator_actuate_1.selectDeepLocatorCandidateOption)(page, frameTarget?.frameSelector, deepLocatorInnerSelector, matched.index, fieldTarget.value, { frameTarget });
-                        if (actuated) {
-                            record.instruction = `deepLocator: ${matched.accessibleText || "(no accessible text)"}`;
-                            record.actResultSuccess = true;
-                            record.actResultDescription = `deepLocator ${fieldTarget.kind === "fill" ? "filled" : "selected"} "${matched.accessibleText || matched.selector}" with "${fieldTarget.value}"`;
-                            // verifyDomEffect can't resolve a `deeplocator=` selector (see
-                            // deep-locator-actuate.ts's module docblock: target.locator()
-                            // has no meaning for cross-origin OOPIF hop notation) — the
-                            // write + read-back fillDeepLocatorCandidate/
-                            // selectDeepLocatorCandidateOption already performed IS the
-                            // verification signal, so record it directly instead of
-                            // synthesizing a resolvedAction that a verifier can only ever
-                            // score false for.
-                            record.verifiedBy = "dom";
-                            attempts.push(record);
-                            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} attempt ${attempt}: ${record.actResultDescription}`);
-                            trajectory?.push({ stepIndex, verifiedBy: "dom" });
-                            return "completed";
-                        }
-                        const failureMessage = `deepLocator: ${fieldTarget.kind} on "${matched.accessibleText || matched.selector}" did not verify (read-back mismatch or rejected write)`;
+                        const failureMessage = `deepLocator: no candidate matched field "${fieldTarget.fieldLabel}" (refusing to click an unrelated control)`;
                         record.actResultSuccess = false;
                         record.errorMessage = failureMessage;
                         attempts.push(record);
@@ -5326,6 +5448,7 @@ async function executeStepWithHealing(params) {
                         logger.info(`${formatStepPrefix(stepIndex, totalSteps)} attempt ${attempt}: ${failureMessage}`);
                         continue;
                     }
+                    const selectStep = parseSelectStep(step);
                     // A select step whose question is phrased un-quoted (parseSelectStep
                     // returns `questionLabel: null`) has no fieldLabel to route through
                     // findDeepLocatorCandidateByFieldLabel above, so ranking below falls
@@ -5709,8 +5832,8 @@ async function executeStepWithHealing(params) {
             }
             else {
                 record.technique = "llm-rephrase";
-                if (!anthropic) {
-                    record.errorMessage = "no anthropic client (bedrock-only deployment); skipping rephrase";
+                if (!rephraseModel) {
+                    record.errorMessage = "no rephrase model configured; skipping rephrase";
                 }
                 else if (hasBillingErrorBeenLogged()) {
                     // Telemetry-driven skip: when Anthropic billing has already been
@@ -5758,7 +5881,7 @@ async function executeStepWithHealing(params) {
                         instruction: a.instruction,
                         verdict: a.errorMessage ?? failureReasons[i] ?? null,
                     }));
-                    const rephrased = await rephraseWithLLM(anthropic, step, triedSelectors, candidates, failureReasons, captureFn, livePageEvidence, unfocused, submitFailureList, priorAttemptsForPrompt, gaEventList);
+                    const rephrased = await rephraseWithLLM(rephraseModel, step, triedSelectors, candidates, failureReasons, captureFn, livePageEvidence, unfocused, submitFailureList, priorAttemptsForPrompt, gaEventList, anthropic);
                     if (!rephrased) {
                         record.errorMessage = "llm declined to rephrase or returned outcome=impossible";
                     }
@@ -5889,7 +6012,19 @@ async function executeStepWithHealing(params) {
             networkDelta: post.networkCount - pre.networkCount,
             bytesDelta: post.bodyHtmlLength - pre.bodyHtmlLength,
         });
-        let verified = networkIsRealAdvance || urlChanged || domVerifiedForStep || clickViewSwapVerified;
+        // Form-value-diff signal: `visibleTextSignature` never reflects a plain
+        // <input>/<textarea>/<select>'s `value` property, so a fill with no
+        // secondary UI side effect (no toggle, no formatted display) had ZERO
+        // verification signal — every cascade attempt reported "no observable
+        // effect" even though the value genuinely landed. Scoped to state-class
+        // actions (fill/check/etc.), same as domVerified, so it never lets an
+        // advance/submit step ride a stray value mutation elsewhere on the page.
+        const formValueVerified = isStateClass && post.formValueSignature !== pre.formValueSignature;
+        let verified = networkIsRealAdvance ||
+            urlChanged ||
+            domVerifiedForStep ||
+            clickViewSwapVerified ||
+            formValueVerified;
         // Final-step submit-verification gate. Replaces the deterministic
         // submitEndpointPattern regex with a Haiku 4.5 LLM judgment over
         // multi-signal evidence (network captures, page URL/title, DOM
@@ -6008,7 +6143,11 @@ async function executeStepWithHealing(params) {
                     ? "url"
                     : networkFired
                         ? "network"
-                        : "dom";
+                        : domVerifiedForStep
+                            ? "dom"
+                            : formValueVerified
+                                ? "form-value"
+                                : "dom";
         }
         // N+16 probe: Stagehand's CDP click sometimes lands on the button without
         // triggering React's SyntheticEvent layer (or jQuery delegated handlers).
@@ -6095,6 +6234,7 @@ async function executeStepWithHealing(params) {
                     const retryUrlChanged = retryPost.url !== pre.url;
                     const retryHtmlDelta = retryPost.bodyHtmlLength - pre.bodyHtmlLength;
                     const retryTextChanged = retryPost.visibleTextSignature !== pre.visibleTextSignature;
+                    const retryFormValueChanged = retryPost.formValueSignature !== pre.formValueSignature;
                     // RC2: an advance/`kind=click` "Next" that only grew the DOM
                     // (validation errors rendered) with NO network/URL change is a
                     // validation-blocked no-op, not a real transition — but the
@@ -6150,6 +6290,7 @@ async function executeStepWithHealing(params) {
                             retryUrlChanged ||
                             retryHtmlDelta !== 0 ||
                             retryTextChanged ||
+                            retryFormValueChanged ||
                             checkboxStateVerified);
                     // Apply the same submit-endpoint gate the primary verifier uses.
                     // Without this, the n+16 fallback would still ride past a
@@ -6223,7 +6364,7 @@ async function executeStepWithHealing(params) {
                             failureReasons.push(`n+16 fallback: submit-judge-rejected: ${judgeVerdict.reason}`);
                         }
                     }
-                    logger.info(`n+16 probe: step=${stepIndex + 1}/${totalSteps?.() ?? "?"} attempt=${attempt} el.click() fallback fired=${fired === true} kind=${probeResult.kind ?? "none"} checkboxStateVerified=${checkboxStateVerified} ancestorStillInvalid=${ancestorStillInvalid}; network=${retryNetworkFired} url=${retryUrlChanged} htmlDelta=${retryHtmlDelta} textChanged=${retryTextChanged} verified=${retryVerified}`);
+                    logger.info(`n+16 probe: step=${stepIndex + 1}/${totalSteps?.() ?? "?"} attempt=${attempt} el.click() fallback fired=${fired === true} kind=${probeResult.kind ?? "none"} checkboxStateVerified=${checkboxStateVerified} ancestorStillInvalid=${ancestorStillInvalid}; network=${retryNetworkFired} url=${retryUrlChanged} htmlDelta=${retryHtmlDelta} textChanged=${retryTextChanged} formValueChanged=${retryFormValueChanged} verified=${retryVerified}`);
                     if (retryVerified) {
                         if (record.verifiedBy === null) {
                             record.verifiedBy = retryUrlChanged ? "url" : retryNetworkFired ? "network" : "dom";
@@ -6488,7 +6629,7 @@ async function waitForSpaReady(page, logger, opts = {}) {
  * than let the flow report phantom success.
  */
 async function runHealingFlow(deps) {
-    const { stagehand, page, steps, logger, anthropic, uploadFixture, maxFlowMs } = deps;
+    const { stagehand, page, steps, logger, anthropic, rephraseModel, uploadFixture, maxFlowMs } = deps;
     const counter = { n: 0 };
     const signalCounter = { n: 0 };
     const recentCaptures = [];
@@ -6540,6 +6681,7 @@ async function runHealingFlow(deps) {
                 recentCaptures,
                 recentCaptureMeta,
                 anthropic,
+                rephraseModel,
                 logger,
                 uploadFixture,
                 frameTarget,