@enricai/barnacle 1.12.69 → 1.12.71

package/dist/scraper/flow-runner.js

@@ -25,6 +25,7 @@ exports.findRecentBackendError = findRecentBackendError;
 exports.findRecentPageTransition = findRecentPageTransition;
 exports.isWizardExitAction = isWizardExitAction;
 exports.isAdvanceStep = isAdvanceStep;
+exports.isSubmitIntentStep = isSubmitIntentStep;
 exports.isCheckboxOrRadioIntentStep = isCheckboxOrRadioIntentStep;
 exports.shouldCaptureSelectionState = shouldCaptureSelectionState;
 exports.flowHasSubmitSemantics = flowHasSubmitSemantics;
@@ -128,6 +129,7 @@ const session_teardown_1 = require("./session-teardown");
 const spa_readiness_1 = require("./spa-readiness");
 const stagehand_guard_1 = require("./stagehand-guard");
 const submit_control_1 = require("./submit-control");
+const target_resolution_diagnostic_1 = require("./target-resolution-diagnostic");
 const watchdog_1 = require("./watchdog");
 const recon_shared_1 = require("../scripts/recon-shared");
 const client_1 = require("../testmail/client");
@@ -1195,6 +1197,36 @@ function isAdvanceStep(instruction) {
     const haystack = instruction.toLowerCase();
     return ADVANCE_STEP_PHRASES.some((p) => haystack.includes(p));
 }
+/**
+ * Phrases (in the ORIGINAL flow instruction) that mark a step whose intent is to
+ * SUBMIT a form — a final "Submit" click — as opposed to a field-answer
+ * or advance step. Matched against the step text, not a resolved element
+ * description. Deliberately narrow (a click-on-submit phrase, not the bare
+ * word "submit") so a field named e.g. "Submit Date" or a verification step
+ * that merely mentions the submit button is never misclassified.
+ */
+const SUBMIT_INTENT_STEP_PHRASES = [
+    "to submit the",
+    "click 'submit'",
+    'click "submit"',
+    "click the submit",
+    "click submit",
+];
+/**
+ * Is this flow step a submit click (the final "Submit"/"Apply" action), rather
+ * than a field-answer or advance step? Mirrors `isAdvanceStep` so a step that
+ * unambiguously names a submit *click* in its own instruction is recognized as
+ * submit-shaped even when the flow file has no explicit `submitStep` flag and
+ * the step isn't the flow's last one. Keyed on the ORIGINAL step instruction,
+ * same discipline as `isAdvanceStep`/`isCheckboxOrRadioIntentStep`. Pure;
+ * unit-testable seam paralleling both.
+ */
+function isSubmitIntentStep(instruction) {
+    if (!instruction)
+        return false;
+    const haystack = instruction.toLowerCase();
+    return SUBMIT_INTENT_STEP_PHRASES.some((p) => haystack.includes(p));
+}
 /**
  * Is this flow step's intent to check a checkbox or select a radio option?
  * Used to veto a weak page-wide DOM signal (htmlDelta/textChanged/formValueChanged)
@@ -1698,7 +1730,7 @@ function describeAttemptEffectSignals(pre, post, recentCaptureMeta, preMetaLengt
  * keeps healing opportunistically.
  */
 function shouldSkipTechnique(params) {
-    const { technique, priorAttempts, advanceUnmovedAfterAttempt1, phantomClickAfterAttempt1, submitShapedStep, } = params;
+    const { technique, priorAttempts, advanceUnmovedAfterAttempt1, attempt1UnreachableViaLightDom, submitShapedStep, } = params;
     // Unmoved-advance short-circuit (measured: attempts 2-4 recovered a stuck
     // advance 0 times in 289 steps). When attempt-1's act-string clicked the Next
     // and the wizard did NOT move forward (non-advancing POST, or no effect),
@@ -1719,14 +1751,16 @@ function shouldSkipTechnique(params) {
             reason: "advance step did not move the wizard on attempt 1; re-observe/re-click cannot advance it — skipping to rephrase/replan",
         };
     }
-    // Phantom-click short-circuit: attempt 1 clicked something Stagehand
-    // believes exists, but pre/post shows zero network, zero URL change, and
-    // no real DOM growth — the click almost certainly landed on nothing (the
-    // recon-submit-phantom-click bug report's light-DOM resolver can't see
-    // into a shadow root / web component). Repeating observe-act /
-    // 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
+    // Unreachable-via-light-DOM short-circuit: attempt 1 either phantom-clicked
+    // (Stagehand reported success but pre/post shows zero network, zero URL
+    // change, and no real DOM growth) or came back "unresolved" (act() found
+    // zero candidates at all) — the recon-submit-phantom-click bug report's
+    // light-DOM resolver can't see into a shadow root / web component in
+    // either case, and "unresolved" is if anything stronger evidence of that
+    // than "phantom" (there was no candidate to even click). Repeating
+    // observe-act / 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 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
@@ -1734,14 +1768,14 @@ function shouldSkipTechnique(params) {
     // is a guaranteed no-op — leave the normal ladder intact so
     // structured-click / observe-act-exclude, the techniques that can
     // actually click it, still run.
-    if (phantomClickAfterAttempt1 === true &&
+    if (attempt1UnreachableViaLightDom === true &&
         submitShapedStep === true &&
         (technique === "observe-act" ||
             technique === "structured-click" ||
             technique === "observe-act-exclude")) {
         return {
             skip: true,
-            reason: "attempt 1 was a phantom click (reported success, zero observable effect) on a submit-shaped step; re-observe/re-click cannot reach a target the light-DOM resolver can't see — escalating to the deep submit-control locator",
+            reason: "attempt 1 could not reach the target via the light-DOM resolver (phantom click or zero candidates resolved) on a submit-shaped step; re-observe/re-click cannot reach a target the light-DOM resolver can't see — escalating to the deep submit-control locator",
         };
     }
     if (technique === "structured-click") {
@@ -3237,6 +3271,46 @@ function xpathTailForRetarget(xpath) {
     const tail = steps.slice(-2).filter(Boolean);
     return tail.length > 0 ? tail.join("/") : null;
 }
+/**
+ * In-page source for `(tail) => Element | null`: resolves
+ * {@link xpathTailForRetarget}'s loose `//`+tail re-anchor against the live
+ * DOM, disambiguating when the loose pattern matches more than one element.
+ * The tail deliberately drops every attribute above the leaf+parent tag
+ * pair, so on a page with several same-tag-shaped siblings (e.g. a repeated
+ * "sign in" control sitting where a "create account" submit button used to
+ * resolve) `FIRST_ORDERED_NODE_TYPE` silently accepts whichever one happens
+ * to come first in document order — not necessarily the element the primary
+ * xpath was tracking. Snapshotting every match and preferring one that is
+ * objectively submit-shaped — native `type="submit"`/`type="image"`/
+ * form-owned button, or (reusing submit-control.ts's exported
+ * {@link SUBMIT_SHAPE_FALLBACK_EXPR}) a tag/role-agnostic generic-action
+ * control — and not negative-text (reuses submit-control.ts's own
+ * {@link NEGATIVE_TEXT_EXPR} vocabulary rather than a second copy) recovers
+ * the plausible candidate instead of an arbitrary one.
+ * Falls back to the first document-order match when no candidate clears that
+ * bar, preserving the previous behavior for every single-match (the common)
+ * case.
+ */
+const XPATH_TAIL_RETARGET_RESOLVE_FN_SRC = `((tail) => {
+    const isNegative = ${submit_control_1.NEGATIVE_TEXT_EXPR};
+    const accessibleName = (el) =>
+      (el.getAttribute("aria-label") || el.textContent || "").replace(/\\s+/g, " ").trim().toLowerCase();
+    const isFallbackShaped = ${submit_control_1.SUBMIT_SHAPE_FALLBACK_EXPR};
+    const isSubmitShaped = (el) => {
+      if (!el || !el.tagName) return false;
+      const tag = el.tagName.toUpperCase();
+      const type = (el.getAttribute("type") || "").toLowerCase();
+      if (tag === "INPUT" && (type === "submit" || type === "image")) return true;
+      if (tag === "BUTTON" && (type === "submit" || type === "") && el.closest("form")) return true;
+      return isFallbackShaped(el, accessibleName(el), isNegative);
+    };
+    const r = document.evaluate("//" + tail, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+    const nodes = [];
+    for (let i = 0; i < r.snapshotLength; i++) nodes.push(r.snapshotItem(i));
+    if (nodes.length <= 1) return nodes[0] || null;
+    const preferred = nodes.find((el) => isSubmitShaped(el) && !isNegative(accessibleName(el)));
+    return preferred || nodes[0];
+  })`;
 /**
  * Resolve any selector a caller might hold into a bare XPath body for
  * `document.evaluate`. `verifyFillReadback` is shared across call sites that
@@ -3487,17 +3561,21 @@ async function resolvedClickTargetStillPresent(target, selector) {
     }
 }
 /**
- * Site-agnostic, attribute-based submit-shape signal read directly from the
- * resolved click target — the counterpart to the flow-authored `submitStep`
- * flag. A step the flow never flagged can still resolve onto an objectively
- * submit-shaped control: `<input type="submit">` / `<input type="image">`, or
- * a `<button>` with no `type` (or `type="submit"`) owned by a `<form>` — per
- * the HTML spec a button's default type IS submit, so an unmarked in-form
- * button commits the form exactly like an explicit `type="submit"` one.
- * Deliberately NOT a CTA-wording word list (fragile, and site-specific) — only
- * the element's own tag/type/form-ownership, which is the same shape on any
- * site. Returns `false` — never manufactures a submit-shape veto — on a
- * non-xpath selector, a miss, or an evaluate failure.
+ * Site-agnostic submit-shape signal read directly from the resolved click
+ * target — the counterpart to the flow-authored `submitStep` flag. A step
+ * the flow never flagged can still resolve onto an objectively submit-shaped
+ * control: `<input type="submit">` / `<input type="image">`, a `<button>`
+ * with no `type` (or `type="submit"`) owned by a `<form>` — per the HTML
+ * spec a button's default type IS submit, so an unmarked in-form button
+ * commits the form exactly like an explicit `type="submit"` one — or, via
+ * {@link SUBMIT_SHAPE_FALLBACK_EXPR}, a tag/role-agnostic control (e.g. a
+ * `<div>`/`<a>`) whose accessible name reads a generic action verb, or is the
+ * sole actionable control in its form. Reuses submit-control.ts's own
+ * widened predicate instead of a narrower, hand-duplicated tag/type-only
+ * check, so a legitimately-clicked non-native submit control is not
+ * mis-classified as "not submit-shaped" here. Returns `false` — never
+ * manufactures a submit-shape veto — on a non-xpath selector, a miss, or an
+ * evaluate failure.
  *
  * `xpathTail` (optional): the n+16 fallback's own `xpathTailForRetarget`
  * re-anchor. Its `clickExpr` resolves primary-xpath-then-tail before
@@ -3516,15 +3594,20 @@ async function resolvedClickTargetIsSubmitShaped(target, selector, xpathTail = n
     const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
     let el = r.singleNodeValue;
     if (!el && ${JSON.stringify(xpathTail)}) {
-      const r2 = document.evaluate("//" + ${JSON.stringify(xpathTail)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
-      el = r2.singleNodeValue;
+      el = ${XPATH_TAIL_RETARGET_RESOLVE_FN_SRC}(${JSON.stringify(xpathTail)});
     }
     if (!el || !el.tagName) return false;
     const tag = el.tagName.toUpperCase();
     const type = (el.getAttribute("type") || "").toLowerCase();
     if (tag === "INPUT" && (type === "submit" || type === "image")) return true;
     if (tag === "BUTTON" && (type === "submit" || type === "") && el.closest("form")) return true;
-    return false;
+    const isNegative = ${submit_control_1.NEGATIVE_TEXT_EXPR};
+    const accessibleName = (node) =>
+      (node.getAttribute("aria-label") || node.textContent || "").replace(/\\s+/g, " ").trim().toLowerCase();
+    const isFallbackShaped = ${submit_control_1.SUBMIT_SHAPE_FALLBACK_EXPR};
+    const name = accessibleName(el);
+    if (isNegative(name)) return false;
+    return isFallbackShaped(el, name, isNegative);
   })()`;
     try {
         return (await target.evaluate(expr)) === true;
@@ -7741,6 +7824,118 @@ function spliceEmailStepFillValue(step, code) {
 function redactIfSensitive(text, sensitiveValue) {
     return sensitiveValue && text === sensitiveValue ? "[redacted]" : text;
 }
+/**
+ * Last-resort escalation for the cascade-exhaustion path: when every
+ * resolution technique has already failed against the resolved (declared-or-
+ * main) frame and no `frameSelector` was declared for this step, probe every
+ * same-origin CHILD frame Stagehand's CDP layer has attached to
+ * (`page.frames()`) for a submit-shaped candidate, using the same
+ * tag/role-agnostic ranking (`buildRankSubmitCandidatesExpr`) and click
+ * primitive (`buildClickByDeepIndexExpr`) the declared-frame cascade already
+ * trusts. This closes the "target lives inside an undeclared iframe" gap for
+ * the ONE case that's safe to probe blindly: a same-origin child, where
+ * `location.href` is readable and its origin can be compared directly against
+ * the top document's. A cross-origin child (e.g. a checkout iframe payment
+ * widget) is excluded on purpose — CDP's `Runtime.evaluate` can still reach a
+ * cross-origin OOPIF's document, so an origin check (not a thrown evaluate)
+ * is the only thing that would stop this function from guessing which
+ * cross-origin iframe hosts the target with no declared selector to anchor
+ * on. That guess is exactly what `frameSelector` exists so a flow author
+ * never has to make; this fallback stays within the same-origin case the
+ * gap report calls out and leaves cross-origin as the flow author's declared
+ * `frameSelector` responsibility, unchanged.
+ *
+ * Every candidate frame is ranked and, on a hit, clicked and verified through
+ * the SAME `snapshotPage`/`classifyPhantomClick` pre/post pair the cascade's
+ * own `deep-submit-locator` escalation uses (including the single runner-up
+ * retry on a phantom top pick) — there is no new unverified success path,
+ * only a new place to look for the candidate before giving up.
+ *
+ * Returns the clicked `FrameTarget` on a verified (non-phantom) click, or
+ * `null` if no same-origin child frame yielded a submit-shaped candidate, no
+ * candidate was actually clickable, or every click phantomed.
+ */
+async function probeChildFrameSubmitFallback(params) {
+    const { page, signalCounter } = params;
+    // `page.mainFrameId`/`page.frames` are read defensively: some call sites
+    // (and their test fakes) model a `Page` that never attaches child frames at
+    // all and doesn't implement this pair, which is indistinguishable here from
+    // "no child frames exist" — either way there is nothing for this fallback
+    // to probe, so it degrades to its normal "nothing found" return rather than
+    // throwing out of an otherwise-best-effort escalation.
+    let candidateFrames;
+    try {
+        const mainFrameId = page.mainFrameId();
+        candidateFrames = page.frames().filter((frame) => frame.frameId !== mainFrameId);
+    }
+    catch {
+        return null;
+    }
+    if (candidateFrames.length === 0)
+        return null;
+    const pageOrigin = (() => {
+        try {
+            return new URL(page.url()).origin;
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (!pageOrigin)
+        return null;
+    for (const frame of candidateFrames) {
+        const frameUrl = await Promise.resolve(frame.evaluate("location.href")).catch(() => null);
+        if (!frameUrl)
+            continue;
+        const frameOrigin = (() => {
+            try {
+                return new URL(frameUrl).origin;
+            }
+            catch {
+                return null;
+            }
+        })();
+        // Cross-origin: documented rule-out, not a code defect. See docblock.
+        if (frameOrigin !== pageOrigin)
+            continue;
+        const target = (0, frame_target_1.childFrameTarget)(page, frame, "(auto-discovered same-origin iframe)");
+        const rankResult = await Promise.resolve(target.evaluate((0, submit_control_1.buildRankSubmitCandidatesExpr)())).catch(() => null);
+        const ranked = Array.isArray(rankResult) ? rankResult : [];
+        if (ranked.length === 0)
+            continue;
+        // biome-ignore lint/style/noNonNullAssertion: guarded by the length check above
+        const top = ranked[0];
+        const pre = await snapshotPage(target, signalCounter, page);
+        const clickResult = (await Promise.resolve(target.evaluate((0, submit_control_1.buildClickByDeepIndexExpr)(top.deepIndex))).catch(() => ({ clicked: false })));
+        if (!clickResult.clicked)
+            continue;
+        const post = await snapshotPage(target, signalCounter, page);
+        const verdict = (0, phantom_click_1.classifyPhantomClick)({
+            actResultSuccess: true,
+            pre,
+            post,
+            isSubmitShapedStep: true,
+        });
+        if (verdict !== "phantom")
+            return target;
+        const runnerUp = ranked[1];
+        if (!runnerUp)
+            continue;
+        const runnerUpClickResult = (await Promise.resolve(target.evaluate((0, submit_control_1.buildClickByDeepIndexExpr)(runnerUp.deepIndex))).catch(() => ({ clicked: false })));
+        if (!runnerUpClickResult.clicked)
+            continue;
+        const runnerUpPost = await snapshotPage(target, signalCounter, page);
+        const runnerUpVerdict = (0, phantom_click_1.classifyPhantomClick)({
+            actResultSuccess: true,
+            pre,
+            post: runnerUpPost,
+            isSubmitShapedStep: true,
+        });
+        if (runnerUpVerdict !== "phantom")
+            return target;
+    }
+    return null;
+}
 async function executeStepWithHealing(params) {
     const { stagehand, page, optional, upload, submitStep, captchaGated = false, emailStep = false, emailStepConfig, allocatedInbox = null, sessionProxy = null, flowHasSubmitSemantics: flowHasSubmitSemanticsFlag, stepIndex, totalSteps, phase, signalCounter, recentCaptures, recentCaptureMeta, anthropic, rephraseModel, logger, captureFn, uploadFixture, isFinalStep, submitEndpointPattern, submittedStateSelectors, requireSubmitEndpointMatch, advanceTransitionBodyPattern, successUrlFragments, successPageTitleHints, ownBackendHostnames, knownErrorClassPrefixes, wizardExitButtonLabels, getSuppressedAisdkElementIdErrorCount, trajectory, onStepFailure, onStepHeal, } = params;
     // Mutable: the `emailStep` code-extract path splices the extracted code
@@ -8068,7 +8263,7 @@ async function executeStepWithHealing(params) {
     // when no solver key is configured or the solve otherwise fails — that
     // propagates out of this function unchanged, so the step fails cleanly
     // instead of silently falling through as if unverified-but-passing.
-    const isSubmitOrFinalStep = submitStep || (isFinalStep && flowHasSubmitSemanticsFlag);
+    const isSubmitOrFinalStep = submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step);
     if (captchaGated && isSubmitOrFinalStep) {
         let captchaTarget = frameTarget ?? (0, frame_target_1.mainFrameTarget)(page);
         const sitekeyProbeExpr = `(() => {
@@ -8410,6 +8605,25 @@ async function executeStepWithHealing(params) {
             logger.error(`${formatStepPrefix(stepIndex, totalSteps)} backend error detected (submit endpoint returned 5xx: ${backendErrorUrl}); aborting cascade`);
             throw new errors_2.StepVerificationError(`${formatStepPrefix(stepIndex, totalSteps)} (${step.slice(0, 60)}) backend 5xx at ${backendErrorUrl} — unrecoverable`, "backend-error-unrecoverable");
         }
+        // Bounded same-origin child-iframe fallback: the probe above only ever
+        // looked at the resolved (declared-or-main) frame's own light+shadow DOM,
+        // so a target genuinely inside an undeclared same-origin iframe is
+        // invisible to it. Only tried when this step never declared its own
+        // frameSelector — a declared-and-used frame means the flow author already
+        // told us where to look, and guessing elsewhere would second-guess that —
+        // and only when this step is itself submit-shaped, since the probe ranks
+        // for a submit-shaped candidate and firing it on a non-submit step (e.g.
+        // a radio/select answer) could complete the step by clicking an unrelated
+        // submit control in an unrelated same-origin child iframe.
+        if (!frameTarget?.declaredFrameSelector &&
+            (submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step))) {
+            const fallbackTarget = await probeChildFrameSubmitFallback({ page, signalCounter });
+            if (fallbackTarget) {
+                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} probe-absent: no candidate in the resolved frame, but a same-origin child iframe surfaced a submit-shaped candidate — clicked and verified there instead of failing`);
+                trajectory?.push({ stepIndex, verifiedBy: "dom" });
+                return "completed";
+            }
+        }
         // Capture diagnostics + write a failure dump BEFORE throwing so the
         // global replan path's `readFailureDumpEvidence` can populate the
         // prompt's CURRENTLY VISIBLE / UNFOCUSED OBSERVE / PAGE BODY HTML
@@ -8433,6 +8647,9 @@ async function executeStepWithHealing(params) {
         const unfocusedObserve = probeAbsentObservedUnfocused.length === 0 && frameTarget?.frame
             ? await deepLocatorCandidatesAsActions(page, frameTarget)
             : probeAbsentObservedUnfocused;
+        const targetResolutionDiagnostic = submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step)
+            ? await (0, target_resolution_diagnostic_1.captureTargetResolutionDiagnosticSnapshot)(frameTarget, page)
+            : null;
         const dumpPath = onStepFailure?.({
             stepIndex,
             phase,
@@ -8444,6 +8661,7 @@ async function executeStepWithHealing(params) {
             recentCaptures,
             bodyOuterHtml,
             unfocusedObserve,
+            targetResolutionDiagnostic,
         }) ?? null;
         throw new errors_2.StepVerificationError(`${formatStepPrefix(stepIndex, totalSteps)} (${step.slice(0, 60)}) probe found no candidates on page${dumpPath ? `; see ${dumpPath}` : ""}`, "probe-absent");
     }
@@ -8705,6 +8923,13 @@ async function executeStepWithHealing(params) {
         }
     };
     let phantomClickAfterAttempt1 = false;
+    let attempt1UnreachableViaLightDom = false;
+    // Last candidate list the deep-submit-locator itself ranked this step, if
+    // any — reused by the cascade-exhausted diagnostic snapshot below so it
+    // doesn't re-run buildRankSubmitCandidatesExpr (and inflate the rank-call
+    // count the phantom-click-escalation tests assert on) when the cascade
+    // already has an up-to-date ranking to report from.
+    let lastRankedSubmitCandidates = null;
     for (let attempt = 1; attempt <= MAX_STEP_ATTEMPTS; attempt++) {
         // Telemetry-driven technique-skip: when a cascade technique's
         // preconditions cannot be met by the prior attempts' state, running
@@ -8713,7 +8938,8 @@ async function executeStepWithHealing(params) {
         // techniques faster.
         if (attempt > 1) {
             const wouldBeTechnique = attempt === 2
-                ? phantomClickAfterAttempt1 && (submitStep || (isFinalStep && flowHasSubmitSemanticsFlag))
+                ? attempt1UnreachableViaLightDom &&
+                    (submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step))
                     ? "deep-submit-locator"
                     : phantomClickAfterAttempt1
                         ? "trusted-click-retry"
@@ -8731,8 +8957,8 @@ async function executeStepWithHealing(params) {
                     errorMessage: a.errorMessage,
                 })),
                 advanceUnmovedAfterAttempt1,
-                phantomClickAfterAttempt1,
-                submitShapedStep: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag),
+                attempt1UnreachableViaLightDom,
+                submitShapedStep: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step),
             });
             if (decision.skip) {
                 logger.info(`${formatStepPrefix(stepIndex, totalSteps)} attempt ${attempt} (${wouldBeTechnique}) skipped: ${decision.reason}`);
@@ -8869,13 +9095,14 @@ async function executeStepWithHealing(params) {
                 }
             }
             else if (attempt === 2 &&
-                phantomClickAfterAttempt1 &&
-                (submitStep || (isFinalStep && flowHasSubmitSemanticsFlag))) {
-                // Deep submit-control locator: attempt 1 phantom-clicked (Stagehand
-                // reported success but pre/post showed zero effect), so the target is
-                // almost certainly unreachable via document.querySelectorAll — most
-                // likely rendered inside an open shadow root by a web-component /
-                // framework-native submit control (see recon-submit-phantom-click bug
+                attempt1UnreachableViaLightDom &&
+                (submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step))) {
+                // Deep submit-control locator: attempt 1 either phantom-clicked
+                // (Stagehand reported success but pre/post showed zero effect) or
+                // came back "unresolved" (act() found zero candidates at all), so the
+                // target is almost certainly unreachable via document.querySelectorAll
+                // — most likely rendered inside an open shadow root by a web-component
+                // / framework-native submit control (see recon-submit-phantom-click bug
                 // report). Rank every submit-shaped candidate the deep traversal can
                 // reach and click the top-ranked one; the ranking already excludes
                 // Back/Cancel/Save-draft-shaped controls, so a false-positive submit
@@ -8902,6 +9129,7 @@ async function executeStepWithHealing(params) {
                         record.errorMessage = `deep-submit-locator: rank evaluate threw ${(0, errors_1.toErrorMessage)(err)}`;
                         break;
                     }
+                    lastRankedSubmitCandidates = ranked;
                     if (ranked.length === 0) {
                         record.errorMessage = "deep-submit-locator: no submit-shaped candidate found";
                         break;
@@ -8994,7 +9222,7 @@ async function executeStepWithHealing(params) {
             }
             else if (attempt === 2 &&
                 phantomClickAfterAttempt1 &&
-                !(submitStep || (isFinalStep && flowHasSubmitSemanticsFlag))) {
+                !(submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step))) {
                 // Trusted-click retry: attempt 1 phantom-clicked a NON-submit control —
                 // Stagehand reported success but pre/post showed zero effect. On a
                 // design-system widget (React synthetic-event delegation, custom
@@ -9674,7 +9902,7 @@ async function executeStepWithHealing(params) {
         // `advanceTransitionBodyPattern` are unaffected.
         const domVerifiedForStep = isDomOnlyAdvanceVerified({
             hasPattern: advanceTransitionBodyPattern !== null,
-            isFinalOrSubmit: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag),
+            isFinalOrSubmit: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step),
             isAdvance: isAdvanceStep(step),
             domVerified,
             networkIsRealAdvance,
@@ -9762,7 +9990,8 @@ async function executeStepWithHealing(params) {
         // gate (requireSubmitEndpoint) will re-litigate the credit below.
         const formValueWeakSignalAllowed = !(submitStep ||
             (isFinalStep && flowHasSubmitSemanticsFlag) ||
-            resolvedElementIsSubmitShaped) || requireSubmitEndpoint;
+            resolvedElementIsSubmitShaped ||
+            isSubmitIntentStep(step)) || requireSubmitEndpoint;
         const formValueVerified = isStateClass &&
             formValueWeakSignalAllowed &&
             post.formValueSignature !== pre.formValueSignature;
@@ -9868,7 +10097,7 @@ async function executeStepWithHealing(params) {
             pre,
             post,
             elementStateChanged: domVerified,
-            isSubmitShapedStep: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag),
+            isSubmitShapedStep: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step),
         });
         // An `"effective"` verdict driven purely by the page-wide byte-delta
         // floor (`TRIVIAL_DOM_DELTA_BYTES`, 500B) is intentionally NOT trusted
@@ -9889,7 +10118,8 @@ async function executeStepWithHealing(params) {
         // respects the SAME DOM-only-advance veto as the block above: a wizard
         // "Next" step on a pattern-configured site whose only signal is a field
         // toggle must stay unverified, not get waved through by the verdict.
-        const domEffectiveVerdict = !(submitStep || (isFinalStep && flowHasSubmitSemanticsFlag)) && domVerifiedForStep;
+        const domEffectiveVerdict = !(submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step)) &&
+            domVerifiedForStep;
         let verified = networkIsRealAdvance ||
             urlChanged ||
             domVerifiedForStep ||
@@ -10140,7 +10370,7 @@ async function executeStepWithHealing(params) {
                     const n16TrustedClickFailure = !n16TrustedDelivered && "reason" in n16TrustedClickResult
                         ? n16TrustedClickResult
                         : null;
-                    const clickExpr = `(() => { const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); let el = r.singleNodeValue; if (!el && ${JSON.stringify(xpathTail)}) { const r2 = document.evaluate("//" + ${JSON.stringify(xpathTail)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); el = r2.singleNodeValue; } if (!el || typeof el.click !== "function") return { fired: false }; if (el.tagName === "LABEL") { const wrapped = el.querySelector("input[type=checkbox], input[type=radio]"); if (wrapped) el = wrapped; } if (el.type === "checkbox" || el.type === "radio") { el.checked = true; el.dispatchEvent(new Event("click", { bubbles: true })); el.dispatchEvent(new Event("change", { bubbles: true })); return { fired: true, kind: "checkbox", checked: el.checked }; } let __n16SmMatched = false; ${(0, browser_click_expr_1.retargetToSelectionMarkerExpr)("el", "__n16SmMatched")} ${n16TrustedDelivered ? "" : (0, browser_click_expr_1.clickActivationExpr)("el")} if (__n16SmMatched) { el.dispatchEvent(new Event("change", { bubbles: true })); } return { fired: true, kind: "click" }; })()`;
+                    const clickExpr = `(() => { const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); let el = r.singleNodeValue; if (!el && ${JSON.stringify(xpathTail)}) { el = ${XPATH_TAIL_RETARGET_RESOLVE_FN_SRC}(${JSON.stringify(xpathTail)}); } if (!el || typeof el.click !== "function") return { fired: false }; if (el.tagName === "LABEL") { const wrapped = el.querySelector("input[type=checkbox], input[type=radio]"); if (wrapped) el = wrapped; } if (el.type === "checkbox" || el.type === "radio") { el.checked = true; el.dispatchEvent(new Event("click", { bubbles: true })); el.dispatchEvent(new Event("change", { bubbles: true })); return { fired: true, kind: "checkbox", checked: el.checked }; } let __n16SmMatched = false; ${(0, browser_click_expr_1.retargetToSelectionMarkerExpr)("el", "__n16SmMatched")} ${n16TrustedDelivered ? "" : (0, browser_click_expr_1.clickActivationExpr)("el")} if (__n16SmMatched) { el.dispatchEvent(new Event("change", { bubbles: true })); } return { fired: true, kind: "click" }; })()`;
                     const n16FallbackTarget = frameTarget ?? (0, frame_target_1.mainFrameTarget)(page);
                     const probeResult = (await n16FallbackTarget.evaluate(clickExpr));
                     const fired = probeResult.fired;
@@ -10159,8 +10389,7 @@ async function executeStepWithHealing(params) {
               const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
               let node = r.singleNodeValue;
               if (!node && ${JSON.stringify(xpathTail)}) {
-                const r2 = document.evaluate("//" + ${JSON.stringify(xpathTail)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
-                node = r2.singleNodeValue;
+                node = ${XPATH_TAIL_RETARGET_RESOLVE_FN_SRC}(${JSON.stringify(xpathTail)});
               }
               if (!node) return false;
               for (let depth = 0; depth < 6 && node; depth++) {
@@ -10243,8 +10472,7 @@ async function executeStepWithHealing(params) {
                 const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
                 let el = r.singleNodeValue;
                 if (!el && ${JSON.stringify(xpathTail)}) {
-                  const r2 = document.evaluate("//" + ${JSON.stringify(xpathTail)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
-                  el = r2.singleNodeValue;
+                  el = ${XPATH_TAIL_RETARGET_RESOLVE_FN_SRC}(${JSON.stringify(xpathTail)});
                 }
                 return el ? isDisabled(el) : false;
               })()`;
@@ -10284,7 +10512,7 @@ async function executeStepWithHealing(params) {
                         }));
                     const fallbackDomOnlyAdvance = shouldVetoFallbackAdvance({
                         hasPattern: advanceTransitionBodyPattern !== null,
-                        isFinalOrSubmit: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag),
+                        isFinalOrSubmit: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step),
                         isAdvance: isAdvanceStep(step),
                         retryUrlChanged,
                         retryNetworkIsRealAdvance,
@@ -10345,7 +10573,8 @@ async function executeStepWithHealing(params) {
                     // value is read below.
                     const retrySubmitShaped = submitStep ||
                         (isFinalStep && flowHasSubmitSemanticsFlag) ||
-                        retryResolvedElementIsSubmitShaped;
+                        retryResolvedElementIsSubmitShaped ||
+                        isSubmitIntentStep(step);
                     const weakDomSignalsAllowed = ((!isFinalStep && !submitStep && !retryResolvedElementIsSubmitShaped) ||
                         requireSubmitEndpoint) &&
                         !isCheckboxOrRadioIntentStep(step) &&
@@ -10568,7 +10797,7 @@ async function executeStepWithHealing(params) {
         // dumps in a 2026-06-10 survey had the paired touched+dirty + visible
         // error text pattern with 3 distinct rejection messages.
         if (record.resolvedMethod === "click" &&
-            (submitStep || (isFinalStep && flowHasSubmitSemanticsFlag))) {
+            (submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step))) {
             const live = await extractLivePageFormEvidence(page, frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), {
                 client: anthropic,
                 knownErrorClassPrefixes,
@@ -10604,26 +10833,44 @@ async function executeStepWithHealing(params) {
                     isAdvanceStep(step) &&
                     !urlChanged &&
                     !networkIsRealAdvance;
-            // Attempt 1 phantom-clicked: Stagehand reported success but pre/post
-            // shows zero observable effect. The zero-effect delta is the primary
-            // signal (classifyPhantomClick above); the live AISDK elementId
-            // suppression counter is corroborating evidence only — logged, never
-            // gating, since a nonzero count alone is too weak a signal on a run
-            // that sees dozens of suppressions across hundreds of unrelated steps.
+            // Attempt 1's classifyPhantomClick verdict: "phantom" means Stagehand
+            // reported success but pre/post shows zero observable effect; the
+            // zero-effect delta is the primary signal there (classifyPhantomClick
+            // above). "unresolved" means act() found zero candidates at all — a
+            // strictly stronger signal that the target is unreachable via the
+            // light-DOM resolver, since there wasn't even a candidate to click. The
+            // live AISDK elementId suppression counter is corroborating evidence
+            // only — logged, never gating, since a nonzero count alone is too weak
+            // a signal on a run that sees dozens of suppressions across hundreds of
+            // unrelated steps.
             phantomClickAfterAttempt1 = record.phantomClickVerdict === "phantom";
-            if (phantomClickAfterAttempt1) {
+            const attempt1Unresolved = record.phantomClickVerdict === "unresolved";
+            attempt1UnreachableViaLightDom = phantomClickAfterAttempt1 || attempt1Unresolved;
+            if (attempt1UnreachableViaLightDom) {
                 const suppressedCount = getSuppressedAisdkElementIdErrorCount?.();
-                const escalationTarget = submitStep || (isFinalStep && flowHasSubmitSemanticsFlag)
+                const verdictDescription = phantomClickAfterAttempt1
+                    ? "phantom click detected"
+                    : "no candidates resolved (unresolved verdict)";
+                const outcomeDescription = phantomClickAfterAttempt1
+                    ? "reported success with no network/url/dom change"
+                    : "act() found zero candidates";
+                // trusted-click-retry needs attempt 1's resolved selector
+                // (triedSelectors), which is empty on an "unresolved" verdict, so a
+                // non-submit step with that verdict falls through to the normal
+                // ladder instead of escalating.
+                const escalationTarget = submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step)
                     ? "escalating attempt 2 to deep-submit-locator"
-                    : "non-submit step — escalating attempt 2 to trusted-click-retry (trusted CDP click on the resolved target)";
-                logger.warn(`${formatStepPrefix(stepIndex, totalSteps)} phantom click detected on attempt 1 (${record.technique}): reported success with no network/url/dom change${suppressedCount !== undefined ? `; ${suppressedCount} AISDK elementId errors suppressed this session (corroborating, not causal)` : ""} — ${escalationTarget}`);
+                    : phantomClickAfterAttempt1
+                        ? "non-submit step — escalating attempt 2 to trusted-click-retry (trusted CDP click on the resolved target)"
+                        : "non-submit step — no resolved target for trusted-click-retry; attempt 2 continues the normal ladder";
+                logger.warn(`${formatStepPrefix(stepIndex, totalSteps)} ${verdictDescription} on attempt 1 (${record.technique}): ${outcomeDescription}${suppressedCount !== undefined ? `; ${suppressedCount} AISDK elementId errors suppressed this session (corroborating, not causal)` : ""} — ${escalationTarget}`);
             }
             const postAttemptInvalidCount = await countNgInvalidContainers(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page));
             const earlyExit = isSubmitRevealedInvalid({
                 // Treat the canonical submit click as "final" for this predicate
                 // even when it lives mid-flow. See requireSubmitEndpoint derivation
                 // above for the same gate-widening rationale.
-                isFinalStep: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag),
+                isFinalStep: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step),
                 requireSubmitEndpoint,
                 resolvedMethod: record.resolvedMethod,
                 effectSignals,
@@ -10643,7 +10890,7 @@ async function executeStepWithHealing(params) {
             // can reorder a later step forward — instead of burning the cascade.
             const advanceStalled = isAdvanceStalled({
                 isAdvance: isAdvanceStep(step),
-                isFinalOrSubmit: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag),
+                isFinalOrSubmit: submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step),
                 hasPattern: advanceTransitionBodyPattern !== null,
                 clickFired: record.resolvedMethod === "click" && record.actResultSuccess === true,
                 networkFired,
@@ -10658,6 +10905,26 @@ async function executeStepWithHealing(params) {
             }
         }
     }
+    // Bounded same-origin child-iframe fallback: every attempt above only ever
+    // operated against the resolved (declared-or-main) frame, so a target
+    // genuinely inside an undeclared same-origin iframe was invisible to all of
+    // them. Only tried when this step never declared its own frameSelector — a
+    // declared-and-used frame means the flow author already told us where to
+    // look, so this can only ever fire on a case that today always fails
+    // (no regression risk to any currently-passing path) — and only when this
+    // step is itself submit-shaped, matching every other
+    // buildRankSubmitCandidatesExpr call site's guard in this file, since
+    // firing on a non-submit step could complete it by clicking an unrelated
+    // submit control in an unrelated same-origin child iframe.
+    if (!frameTarget?.declaredFrameSelector &&
+        (submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step))) {
+        const fallbackTarget = await probeChildFrameSubmitFallback({ page, signalCounter });
+        if (fallbackTarget) {
+            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} cascade-exhausted: no candidate resolvable in the declared/main frame, but a same-origin child iframe surfaced a submit-shaped candidate — clicked and verified there instead of failing`);
+            trajectory?.push({ stepIndex, verifiedBy: "dom" });
+            return "completed";
+        }
+    }
     const cascadeExhaustObservedFinal = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
     // observe() is blind to a cross-origin OOPIF, so a frame-scoped empty
     // result degrades to the deep-locator resolver for dump evidence — this
@@ -10680,6 +10947,9 @@ async function executeStepWithHealing(params) {
     const unfocusedObserve = cascadeExhaustObservedUnfocused.length === 0 && frameTarget?.frame
         ? await deepLocatorCandidatesAsActions(page, frameTarget)
         : cascadeExhaustObservedUnfocused;
+    const targetResolutionDiagnostic = submitStep || (isFinalStep && flowHasSubmitSemanticsFlag) || isSubmitIntentStep(step)
+        ? await (0, target_resolution_diagnostic_1.captureTargetResolutionDiagnosticSnapshot)(frameTarget, page, lastRankedSubmitCandidates)
+        : null;
     const dumpPath = onStepFailure?.({
         stepIndex,
         phase,
@@ -10691,6 +10961,7 @@ async function executeStepWithHealing(params) {
         recentCaptures,
         bodyOuterHtml,
         unfocusedObserve,
+        targetResolutionDiagnostic,
     }) ?? null;
     if (dumpPath !== null) {
         logger.error(`${formatStepPrefix(stepIndex, totalSteps)} failed after ${MAX_STEP_ATTEMPTS} attempts; diagnostic bundle: ${dumpPath}`);