@enricai/barnacle 1.6.0 → 1.6.2

package/dist/scraper/flow-runner.js

@@ -60,6 +60,7 @@ exports.chooseRequiredSelectOption = chooseRequiredSelectOption;
 exports.buildRadioIdXPath = buildRadioIdXPath;
 exports.selectRadioGroupOption = selectRadioGroupOption;
 exports.narrowInvalidFormControl = narrowInvalidFormControl;
+exports.formatStepPrefix = formatStepPrefix;
 exports.probeStepBeforeAttempts = probeStepBeforeAttempts;
 exports.executeStepWithHealing = executeStepWithHealing;
 exports.waitForSpaReady = waitForSpaReady;
@@ -81,7 +82,9 @@ const logging_1 = require("../lib/logging");
 const call_capture_1 = require("../lib/telemetry/call-capture");
 const call_types_1 = require("../lib/telemetry/call-types");
 const errors_2 = require("../scraper/errors");
+const phantom_click_1 = require("../scraper/phantom-click");
 const stagehand_guard_1 = require("../scraper/stagehand-guard");
+const submit_control_1 = require("../scraper/submit-control");
 const recon_shared_1 = require("../scripts/recon-shared");
 const logger = (0, logging_1.getLogger)({ name: "scraper/flow-runner" });
 /** Cap on the rolling capture-filename window held in memory for failure dumps. */
@@ -126,6 +129,12 @@ function wireSignalCapture(page, params) {
     // into the capture once, in `onFinished` (the only place a Capture is built).
     // See mergeResponseHeaders.
     const extraResponseHeaders = new Map();
+    // Cookie (and other extra-info-only request headers) keyed by requestId.
+    // Mirrors extraResponseHeaders: Network.requestWillBeSent omits the outgoing
+    // Cookie header by design, and requestWillBeSentExtraInfo — which carries it —
+    // can race requestWillBeSent in either order. Buffered here and folded into
+    // the capture once, in `onFinished`. See mergeResponseHeaders.
+    const extraRequestHeaders = new Map();
     // One-shot per-run warning state for the GA `ep.isExpired=true` beacon.
     // Defensive instrumentation: across 5,542 captures surveyed 2026-06-15,
     // every observation was `false` — but if a future job ever ships in the
@@ -158,6 +167,13 @@ function wireSignalCapture(page, params) {
         const merged = mergeResponseHeaders(extraResponseHeaders.get(params.requestId) ?? {}, params.headers);
         extraResponseHeaders.set(params.requestId, merged);
     };
+    const onRequestExtraInfo = (params) => {
+        // Accumulate — can race requestWillBeSent in either order, and a redirect
+        // fires this more than once per requestId. The fold into the capture
+        // happens once, in onFinished, so order with requestWillBeSent never matters.
+        const merged = mergeResponseHeaders(extraRequestHeaders.get(params.requestId) ?? {}, params.headers);
+        extraRequestHeaders.set(params.requestId, merged);
+    };
     const onFinished = async (params) => {
         const req = inFlight.get(params.requestId);
         if (!req)
@@ -168,6 +184,10 @@ function wireSignalCapture(page, params) {
         // it can't leak per run.
         req.responseHeaders = mergeResponseHeaders(req.responseHeaders, extraResponseHeaders.get(params.requestId));
         extraResponseHeaders.delete(params.requestId);
+        // Same fold, request side: recovers the outgoing Cookie header that
+        // requestWillBeSent omits by design.
+        req.requestHeaders = mergeResponseHeaders(req.requestHeaders, extraRequestHeaders.get(params.requestId));
+        extraRequestHeaders.delete(params.requestId);
         const phase = getCurrentPhase();
         let responseBody = null;
         try {
@@ -298,11 +318,13 @@ function wireSignalCapture(page, params) {
         logger.info(`captured [${capture.status}] ${capture.method} ${req.url} → ${filename}`);
     };
     session.on("Network.requestWillBeSent", onRequest);
+    session.on("Network.requestWillBeSentExtraInfo", onRequestExtraInfo);
     session.on("Network.responseReceived", onResponse);
     session.on("Network.responseReceivedExtraInfo", onResponseExtraInfo);
     session.on("Network.loadingFinished", onFinished);
     return () => {
         session.off("Network.requestWillBeSent", onRequest);
+        session.off("Network.requestWillBeSentExtraInfo", onRequestExtraInfo);
         session.off("Network.responseReceived", onResponse);
         session.off("Network.responseReceivedExtraInfo", onResponseExtraInfo);
         session.off("Network.loadingFinished", onFinished);
@@ -711,7 +733,7 @@ function windowHasTransitionBody(params) {
     const { preIdx, advanceTransitionBodyPattern } = params;
     if (!advanceTransitionBodyPattern)
         return false;
-    const capturesDir = params.capturesDir ?? recon_shared_1.CAPTURES_DIR;
+    const capturesDir = params.capturesDir ?? (0, recon_shared_1.resolveReconRunDir)().graphqlDir;
     let rx;
     try {
         rx = new RegExp(advanceTransitionBodyPattern);
@@ -753,7 +775,7 @@ function windowHasAdvanceTransition(params) {
     const { preIdx, advanceTransitionBodyPattern } = params;
     if (!advanceTransitionBodyPattern)
         return false;
-    const capturesDir = params.capturesDir ?? recon_shared_1.CAPTURES_DIR;
+    const capturesDir = params.capturesDir ?? (0, recon_shared_1.resolveReconRunDir)().graphqlDir;
     let rx;
     try {
         rx = new RegExp(advanceTransitionBodyPattern);
@@ -902,7 +924,7 @@ function describeAttemptEffectSignals(pre, post, recentCaptureMeta, preMetaLengt
  * keeps healing opportunistically.
  */
 function shouldSkipTechnique(params) {
-    const { technique, priorAttempts, advanceUnmovedAfterAttempt1 } = params;
+    const { technique, priorAttempts, advanceUnmovedAfterAttempt1, phantomClickAfterAttempt1 } = 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),
@@ -923,6 +945,25 @@ 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
+    // (attempt 5) is never skipped — a differently-worded instruction is still
+    // a distinct attempt worth trying if the deep locator also fails.
+    if (phantomClickAfterAttempt1 === 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); 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") {
         const anyXpathResolved = priorAttempts.some((a) => a.triedSelectors.length > 0);
         if (!anyXpathResolved) {
@@ -1691,8 +1732,9 @@ async function extractInteractiveTargetsNearInvalid(page) {
 /**
  * Scan recent capture files for failed submit-endpoint requests and pull
  * out structured field-level errors from the response body. The cascade
- * already saves every captured request to `CAPTURES_DIR` with its parsed
- * `responseBody`; this helper reads those files back, filters to captures
+ * already saves every captured request to the run's graphql capture dir
+ * (see {@link resolveReconRunDir}) with its parsed `responseBody`; this
+ * helper reads those files back, filters to captures
  * matching the configured submit pattern with status >= 400, and walks
  * common error-shape conventions (`{ errors: [{ field, message }] }`,
  * `{ validation/fieldErrors: { … } }`, `{ message }`).
@@ -1709,7 +1751,7 @@ function extractSubmitFailureEvidence(recentCaptureFilenames,
  * deterministic hostname equality. Empty list / "any-4xx" mode disables
  * the host filter and returns any 4xx in the window.
  */
-ownBackendHostnames, capturesDir = recon_shared_1.CAPTURES_DIR, mode = "strict") {
+ownBackendHostnames, capturesDir = (0, recon_shared_1.resolveReconRunDir)().graphqlDir, mode = "strict") {
     if (recentCaptureFilenames.length === 0)
         return "";
     if (mode === "strict" && ownBackendHostnames.length === 0)
@@ -1800,7 +1842,7 @@ ownBackendHostnames, capturesDir = recon_shared_1.CAPTURES_DIR, mode = "strict")
  * Returns a numbered evidence list. Empty string when no GA collect
  * captures are present. Advisory — never load-bearing.
  */
-function extractGaEventEvidence(recentCaptureFilenames, capturesDir = recon_shared_1.CAPTURES_DIR) {
+function extractGaEventEvidence(recentCaptureFilenames, capturesDir = (0, recon_shared_1.resolveReconRunDir)().graphqlDir) {
     if (recentCaptureFilenames.length === 0)
         return "";
     const records = [];
@@ -4265,8 +4307,23 @@ function narrowInvalidFormControl(entry) {
         autoFilled: narrowedAutoFilled,
     };
 }
+/**
+ * Single source of truth for step-line prefixes. Exists because the cascade
+ * here has only ever received `stepIndex`, while the orchestrator loop in
+ * recon-browser owns the plan array — so half the step lines in a run printed
+ * a `N/total` denominator and half printed a bare `N`.
+ *
+ * Takes a getter rather than a number: a global replan splices new steps into
+ * the live plan array mid-run, so the total must be read when the line is
+ * emitted, not when the step started. Callers with no total omit it and get
+ * the bare form.
+ */
+function formatStepPrefix(stepIndex, totalSteps) {
+    const total = totalSteps?.();
+    return total === undefined ? `step ${stepIndex + 1}` : `step ${stepIndex + 1}/${total}`;
+}
 async function probeFormValidityBeforeSubmit(params) {
-    const { page, stepIndex, logger } = params;
+    const { page, stepIndex, totalSteps, logger } = params;
     try {
         const raw = await page.evaluate(FORM_VALIDITY_PROBE_EXPR);
         if (!Array.isArray(raw))
@@ -4280,15 +4337,15 @@ async function probeFormValidityBeforeSubmit(params) {
         }
         const autoCount = out.filter((e) => e.autoFilled !== null).length;
         if (out.length > 0) {
-            logger.info(`step ${stepIndex + 1} pre-submit probe: ${out.length} ng-invalid form control(s) detected; empty=${out.filter((e) => e.emptyOrUnchecked).length}; auto-picked=${autoCount}`);
+            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} pre-submit probe: ${out.length} ng-invalid form control(s) detected; empty=${out.filter((e) => e.emptyOrUnchecked).length}; auto-picked=${autoCount}`);
         }
         else {
-            logger.info(`step ${stepIndex + 1} pre-submit probe: no ng-invalid form controls detected`);
+            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} pre-submit probe: no ng-invalid form controls detected`);
         }
         return out;
     }
     catch (err) {
-        logger.warn(`step ${stepIndex + 1} pre-submit probe threw: ${(0, errors_1.toErrorMessage)(err)} — proceeding without pre-flight evidence`);
+        logger.warn(`${formatStepPrefix(stepIndex, totalSteps)} pre-submit probe threw: ${(0, errors_1.toErrorMessage)(err)} — proceeding without pre-flight evidence`);
         return [];
     }
 }
@@ -4302,7 +4359,7 @@ async function probeFormValidityBeforeSubmit(params) {
  * step is declared "absent". Exported for tests.
  */
 async function probeStepBeforeAttempts(params) {
-    const { stagehand, step, stepIndex, logger, captureFn } = params;
+    const { stagehand, step, stepIndex, totalSteps, logger, captureFn } = params;
     try {
         const candidates = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, { timeout: exports.STEP_WATCHDOG_MS }, captureFn);
         if (candidates.length === 0) {
@@ -4319,24 +4376,24 @@ async function probeStepBeforeAttempts(params) {
             // where the unfocused observe is also empty — stay "absent".
             const unfocused = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn);
             if (unfocused.length > 0) {
-                logger.info(`step ${stepIndex + 1}: focused probe found 0 candidates but unfocused observe found ${unfocused.length} — treating as present (let cascade resolve)`);
+                logger.info(`${formatStepPrefix(stepIndex, totalSteps)}: focused probe found 0 candidates but unfocused observe found ${unfocused.length} — treating as present (let cascade resolve)`);
                 return "present";
             }
-            logger.info(`step ${stepIndex + 1}: probe found 0 candidates (focused and unfocused) — treating as absent (skip cascade, route to replan if required)`);
+            logger.info(`${formatStepPrefix(stepIndex, totalSteps)}: probe found 0 candidates (focused and unfocused) — treating as absent (skip cascade, route to replan if required)`);
             return "absent";
         }
-        logger.info(`step ${stepIndex + 1}: probe found ${candidates.length} candidate(s)`);
+        logger.info(`${formatStepPrefix(stepIndex, totalSteps)}: probe found ${candidates.length} candidate(s)`);
         return "present";
     }
     catch (err) {
         // Bias toward the existing behavior on errors: don't trigger a spurious
         // replan when the probe itself is the broken thing.
-        logger.warn(`step ${stepIndex + 1}: probe threw ${(0, errors_1.toErrorMessage)(err)} — treating as present (cascade will run)`);
+        logger.warn(`${formatStepPrefix(stepIndex, totalSteps)}: probe threw ${(0, errors_1.toErrorMessage)(err)} — treating as present (cascade will run)`);
         return "present";
     }
 }
 async function executeStepWithHealing(params) {
-    const { stagehand, page, step, optional, upload, submitStep, stepIndex, phase, signalCounter, recentCaptures, recentCaptureMeta, anthropic, logger, captureFn, resumeFixture, isFinalStep, submitEndpointPattern, submittedStateSelectors, requireSubmitEndpointMatch, advanceTransitionBodyPattern, successUrlFragments, successPageTitleHints, ownBackendHostnames, knownErrorClassPrefixes, wizardExitButtonLabels, trajectory, onStepFailure, } = params;
+    const { stagehand, page, step, optional, upload, submitStep, stepIndex, totalSteps, phase, signalCounter, recentCaptures, recentCaptureMeta, anthropic, logger, captureFn, resumeFixture, isFinalStep, submitEndpointPattern, submittedStateSelectors, requireSubmitEndpointMatch, advanceTransitionBodyPattern, successUrlFragments, successPageTitleHints, ownBackendHostnames, knownErrorClassPrefixes, wizardExitButtonLabels, getSuppressedAisdkElementIdErrorCount, trajectory, onStepFailure, } = params;
     // Read-once to suppress "unused" — knownErrorClassPrefixes is threaded
     // through executeStepWithHealing's signature so the cascade has it in
     // scope when the invalid-fields judge migration (Task #43) lands. The
@@ -4376,7 +4433,7 @@ async function executeStepWithHealing(params) {
         signalCounter,
         recentCaptureMeta,
     })) {
-        logger.info(`step ${stepIndex + 1} resolved by upload primitive`);
+        logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by upload primitive`);
         trajectory?.push({ stepIndex, verifiedBy: "network" });
         return "completed";
     }
@@ -4387,7 +4444,7 @@ async function executeStepWithHealing(params) {
     // question unanswered. No-op (returns false → falls through) when the step
     // isn't a single-dropdown select or no option matches.
     if (await trySelectPrimitive({ page, instruction: step, logger, anthropic, captureFn })) {
-        logger.info(`step ${stepIndex + 1} resolved by select primitive`);
+        logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by select primitive`);
         trajectory?.push({ stepIndex, verifiedBy: "dom" });
         return "completed";
     }
@@ -4397,7 +4454,7 @@ async function executeStepWithHealing(params) {
     // trySelectPrimitive (which handles <select> and no-ops on checkbox-only
     // pages). No-op (falls through) when there's no checkbox group or no match.
     if (await tryCheckboxPrimitive({ page, instruction: step, logger, anthropic, captureFn })) {
-        logger.info(`step ${stepIndex + 1} resolved by checkbox primitive`);
+        logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by checkbox primitive`);
         trajectory?.push({ stepIndex, verifiedBy: "dom" });
         return "completed";
     }
@@ -4408,7 +4465,7 @@ async function executeStepWithHealing(params) {
     // React controlled state (the HCA Basic-Info Step-2 wall). No-op (falls
     // through) when there's no radio group or no confident option match.
     if (await tryRadioPrimitive({ page, instruction: step, logger, anthropic, captureFn })) {
-        logger.info(`step ${stepIndex + 1} resolved by radio primitive`);
+        logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by radio primitive`);
         trajectory?.push({ stepIndex, verifiedBy: "dom" });
         return "completed";
     }
@@ -4419,7 +4476,7 @@ async function executeStepWithHealing(params) {
     // catch-all (parseSelectStep returns null there, so trySelectPrimitive above
     // skipped it) and no-ops when the page has no required-empty select.
     if (await tryFillRequiredSelectsPrimitive({ page, instruction: step, logger, anthropic, captureFn })) {
-        logger.info(`step ${stepIndex + 1} resolved by required-select primitive`);
+        logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by required-select primitive`);
         trajectory?.push({ stepIndex, verifiedBy: "dom" });
         return "completed";
     }
@@ -4435,6 +4492,7 @@ async function executeStepWithHealing(params) {
         stagehand,
         step,
         stepIndex,
+        totalSteps,
         logger,
         captureFn,
     });
@@ -4445,10 +4503,10 @@ async function executeStepWithHealing(params) {
             // can't resolve the widget) — skipping would leave a required field empty
             // and silently doom the later submit. Fall through to the cascade instead.
             if (await hasUnfilledRequiredControlForStep(page, step)) {
-                logger.info(`step ${stepIndex + 1} probe-absent but a required unfilled control matches the question; NOT skipping (escalating to cascade)`);
+                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} probe-absent but a required unfilled control matches the question; NOT skipping (escalating to cascade)`);
             }
             else {
-                logger.info(`step ${stepIndex + 1} skipped (optional, probe found no candidates)`);
+                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} skipped (optional, probe found no candidates)`);
                 return "skipped";
             }
         }
@@ -4463,7 +4521,7 @@ async function executeStepWithHealing(params) {
             preMetaLength: stepStartMetaLength,
         });
         if (transitionUrl !== null) {
-            logger.info(`step ${stepIndex + 1} skipped (probe absent but recent transition detected: ${transitionUrl})`);
+            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} skipped (probe absent but recent transition detected: ${transitionUrl})`);
             trajectory?.push({ stepIndex, verifiedBy: "url" });
             return "completed";
         }
@@ -4478,8 +4536,8 @@ async function executeStepWithHealing(params) {
             ownBackendHostnames,
         });
         if (backendErrorUrl !== null) {
-            logger.error(`step ${stepIndex + 1} backend error detected (submit endpoint returned 5xx: ${backendErrorUrl}); aborting cascade`);
-            throw new errors_2.StepVerificationError(`step ${stepIndex + 1} (${step.slice(0, 60)}) backend 5xx at ${backendErrorUrl} — unrecoverable`, "backend-error-unrecoverable");
+            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");
         }
         // Capture diagnostics + write a failure dump BEFORE throwing so the
         // global replan path's `readFailureDumpEvidence` can populate the
@@ -4507,7 +4565,7 @@ async function executeStepWithHealing(params) {
             bodyOuterHtml,
             unfocusedObserve,
         }) ?? null;
-        throw new errors_2.StepVerificationError(`step ${stepIndex + 1} (${step.slice(0, 60)}) probe found no candidates on page${dumpPath ? `; see ${dumpPath}` : ""}`, "probe-absent");
+        throw new errors_2.StepVerificationError(`${formatStepPrefix(stepIndex, totalSteps)} (${step.slice(0, 60)}) probe found no candidates on page${dumpPath ? `; see ${dumpPath}` : ""}`, "probe-absent");
     }
     // Pre-submit form-validity probe. Fires on the canonical submit step
     // (either the final flow step OR a step explicitly flagged `submitStep:
@@ -4532,6 +4590,7 @@ async function executeStepWithHealing(params) {
         const invalidControls = await probeFormValidityBeforeSubmit({
             page,
             stepIndex,
+            totalSteps,
             logger,
         });
         for (const c of invalidControls) {
@@ -4573,6 +4632,7 @@ async function executeStepWithHealing(params) {
                 resolvedMethod: null,
                 resolvedArguments: null,
                 verifiedBy: null,
+                phantomClickVerdict: null,
             });
         }
         // Brief settle window after auto-picks so Angular's change-detection
@@ -4588,6 +4648,11 @@ async function executeStepWithHealing(params) {
     // NOT move the wizard forward. Read at the top of attempts 2-4 to skip the
     // proven-dead re-observe/re-click techniques (see shouldSkipTechnique).
     let advanceUnmovedAfterAttempt1 = false;
+    // Set after attempt 1: Stagehand reported success but pre/post shows zero
+    // observable effect (see classifyPhantomClick). Reroutes attempt 2 to
+    // deep-submit-locator instead of observe-act, since re-resolving via the
+    // same light-DOM view cannot reach a target the resolver can't see.
+    let phantomClickAfterAttempt1 = false;
     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
@@ -4596,7 +4661,9 @@ async function executeStepWithHealing(params) {
         // techniques faster.
         if (attempt > 1) {
             const wouldBeTechnique = attempt === 2
-                ? "observe-act"
+                ? phantomClickAfterAttempt1
+                    ? "deep-submit-locator"
+                    : "observe-act"
                 : attempt === 3
                     ? "structured-click"
                     : attempt === 4
@@ -4610,9 +4677,10 @@ async function executeStepWithHealing(params) {
                     errorMessage: a.errorMessage,
                 })),
                 advanceUnmovedAfterAttempt1,
+                phantomClickAfterAttempt1,
             });
             if (decision.skip) {
-                logger.info(`step ${stepIndex + 1} attempt ${attempt} (${wouldBeTechnique}) skipped: ${decision.reason}`);
+                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} attempt ${attempt} (${wouldBeTechnique}) skipped: ${decision.reason}`);
                 failureReasons.push(`attempt ${attempt} skipped: ${decision.reason}`);
                 continue;
             }
@@ -4643,6 +4711,7 @@ async function executeStepWithHealing(params) {
             resolvedMethod: null,
             resolvedArguments: null,
             verifiedBy: null,
+            phantomClickVerdict: null,
         };
         // First resolved action from Stagehand's `act` result — used to decide
         // whether this attempt's signal should come from the network/URL pair or
@@ -4679,6 +4748,124 @@ async function executeStepWithHealing(params) {
                     }
                 }
             }
+            else if (attempt === 2 && phantomClickAfterAttempt1) {
+                // 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
+                // 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
+                // click cannot fire.
+                //
+                // Rank and click are two separate page.evaluate round trips over a
+                // live Angular page, so any re-render between them shifts every
+                // deepIndex — the click then lands on nothing (`{clicked: false}`),
+                // not because the page is broken but because the snapshot the index
+                // was computed from is already gone. That's a transient, self-clearing
+                // condition, so re-rank against the CURRENT DOM and click once more
+                // before giving up. Capped at one retry (two rank+click rounds total)
+                // so a page re-rendering on every tick can't turn this into a loop.
+                record.technique = "deep-submit-locator";
+                for (let deepAttempt = 1; deepAttempt <= 2; deepAttempt++) {
+                    let ranked;
+                    try {
+                        ranked = (await page.evaluate((0, submit_control_1.buildRankSubmitCandidatesExpr)()));
+                    }
+                    catch (err) {
+                        // A thrown evaluate (page navigated away / frame detached) is not
+                        // a stale-index race — re-ranking a detached page will throw
+                        // again, so don't retry; record it and let the cascade move on.
+                        record.errorMessage = `deep-submit-locator: rank evaluate threw ${(0, errors_1.toErrorMessage)(err)}`;
+                        break;
+                    }
+                    if (ranked.length === 0) {
+                        record.errorMessage = "deep-submit-locator: no submit-shaped candidate found";
+                        break;
+                    }
+                    // biome-ignore lint/style/noNonNullAssertion: guarded by the length check above
+                    const top = ranked[0];
+                    record.instruction = `deep-submit-locator: ${top.tag} "${top.accessibleName}" (tier ${top.tier})`;
+                    record.triedSelectors = [`deep-index:${top.deepIndex}`];
+                    triedSelectors.push(`deep-index:${top.deepIndex}`);
+                    let clickResult;
+                    try {
+                        clickResult = (await page.evaluate((0, submit_control_1.buildClickByDeepIndexExpr)(top.deepIndex)));
+                    }
+                    catch (err) {
+                        record.errorMessage = `deep-submit-locator: click evaluate threw ${(0, errors_1.toErrorMessage)(err)}`;
+                        break;
+                    }
+                    record.actResultSuccess = clickResult.clicked;
+                    record.actResultDescription = clickResult.clicked
+                        ? `deep-submit-locator clicked ${top.tag} "${top.accessibleName}"`
+                        : "deep-submit-locator: candidate vanished before click (deepIndex stale)";
+                    if (clickResult.clicked) {
+                        // Synthesize a click action so downstream verification (network /
+                        // url / dom) treats this exactly like any other resolved click.
+                        resolvedAction = {
+                            selector: `deep-index:${top.deepIndex}`,
+                            description: record.actResultDescription,
+                            method: "click",
+                        };
+                        // Runner-up retry: the top pick can itself phantom-click (a
+                        // second web-component / shadow-root control that LOOKS
+                        // submit-shaped but doesn't wire a real handler — see
+                        // submit-control.ts's module docblock). Re-snapshot right here
+                        // and re-classify with the same classifyPhantomClick primitive
+                        // that escalated attempt 1, so a phantom top pick doesn't fall
+                        // through to attempt 3's structured-click, which can't reach a
+                        // shadow-root control either. Cap at ranked[1] only (not the
+                        // full list) so a page with many submit-shaped candidates can't
+                        // burn the step budget probing all of them.
+                        const runnerUp = ranked[1];
+                        if (runnerUp) {
+                            const midPost = await snapshotPage(page, signalCounter);
+                            const topVerdict = (0, phantom_click_1.classifyPhantomClick)({
+                                actResultSuccess: true,
+                                pre,
+                                post: midPost,
+                            });
+                            if (topVerdict === "phantom") {
+                                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} deep-submit-locator top pick (${top.tag} "${top.accessibleName}") phantom-clicked; retrying runner-up ${runnerUp.tag} "${runnerUp.accessibleName}" (tier ${runnerUp.tier})`);
+                                record.instruction = `deep-submit-locator: ${runnerUp.tag} "${runnerUp.accessibleName}" (tier ${runnerUp.tier}), runner-up after top pick ${top.tag} "${top.accessibleName}" phantomed`;
+                                record.triedSelectors = [
+                                    `deep-index:${top.deepIndex}`,
+                                    `deep-index:${runnerUp.deepIndex}`,
+                                ];
+                                triedSelectors.push(`deep-index:${runnerUp.deepIndex}`);
+                                const runnerUpClickResult = (await page
+                                    .evaluate((0, submit_control_1.buildClickByDeepIndexExpr)(runnerUp.deepIndex))
+                                    .catch(() => ({ clicked: false })));
+                                record.actResultSuccess = runnerUpClickResult.clicked;
+                                record.actResultDescription = runnerUpClickResult.clicked
+                                    ? `deep-submit-locator clicked runner-up ${runnerUp.tag} "${runnerUp.accessibleName}" after top pick phantomed`
+                                    : "deep-submit-locator: runner-up candidate vanished before click (deepIndex stale)";
+                                resolvedAction = runnerUpClickResult.clicked
+                                    ? {
+                                        selector: `deep-index:${runnerUp.deepIndex}`,
+                                        description: record.actResultDescription,
+                                        method: "click",
+                                    }
+                                    : null;
+                                if (!runnerUpClickResult.clicked) {
+                                    record.errorMessage = record.actResultDescription;
+                                }
+                            }
+                        }
+                        // The top pick (or its runner-up) was reached and clicked. A
+                        // runner-up that itself vanished is not the stale-index race the
+                        // re-rank exists for — the rank was fresh enough to click the top
+                        // pick — so exit either way and let the cascade classify.
+                        break;
+                    }
+                    record.errorMessage = record.actResultDescription;
+                    if (deepAttempt === 1) {
+                        logger.info(`${formatStepPrefix(stepIndex, totalSteps)} deep-submit-locator: deepIndex stale on first click, re-ranking once`);
+                    }
+                }
+            }
             else if (attempt === 2 || attempt === 4) {
                 record.technique = attempt === 2 ? "observe-act" : "observe-act-exclude";
                 const observeOptions = attempt === 4 && triedSelectors.length > 0
@@ -4706,12 +4893,12 @@ async function executeStepWithHealing(params) {
                         // don't fast-skip — let the healing cascade continue so the
                         // required field gets answered instead of silently doomed.
                         if (await hasUnfilledRequiredControlForStep(page, step)) {
-                            logger.info(`step ${stepIndex + 1} no candidates after act+observe but a required unfilled control matches; NOT skipping (continuing cascade)`);
+                            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} no candidates after act+observe but a required unfilled control matches; NOT skipping (continuing cascade)`);
                         }
                         else {
                             record.verifiedBy = null;
                             attempts.push(record);
-                            logger.info(`step ${stepIndex + 1} skipped (optional, no candidates after act+observe)`);
+                            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} skipped (optional, no candidates after act+observe)`);
                             return "skipped";
                         }
                     }
@@ -4729,7 +4916,7 @@ async function executeStepWithHealing(params) {
                         record.triedSelectors = [target.selector];
                         attempts.push(record);
                         failureReasons.push(record.errorMessage);
-                        logger.info(`step ${stepIndex + 1} attempt ${attempt}: ${record.errorMessage}`);
+                        logger.info(`${formatStepPrefix(stepIndex, totalSteps)} attempt ${attempt}: ${record.errorMessage}`);
                         continue;
                     }
                     record.instruction = target.description;
@@ -4789,7 +4976,7 @@ async function executeStepWithHealing(params) {
                                         record.actResultSuccess = false;
                                     }
                                     else if (readback.outcome === "differs") {
-                                        logger.info(`step ${stepIndex + 1} fill-value-differs: tried "${fillValue.slice(0, 60)}" got "${readback.postValue.slice(0, 60)}" (framework reformatted)`);
+                                        logger.info(`${formatStepPrefix(stepIndex, totalSteps)} fill-value-differs: tried "${fillValue.slice(0, 60)}" got "${readback.postValue.slice(0, 60)}" (framework reformatted)`);
                                     }
                                 }
                             }
@@ -5061,7 +5248,7 @@ async function executeStepWithHealing(params) {
                 intervalMs: ADVANCE_TRANSITION_POLL_INTERVAL_MS,
             });
         if (advanceGateActive && !networkIsRealAdvance) {
-            logger.info(`step ${stepIndex + 1} network fired but no advance-transition (type=next) body matched within ${ADVANCE_TRANSITION_POLL_MS}ms poll (non-advancing POST); not treating as verified`);
+            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} network fired but no advance-transition (type=next) body matched within ${ADVANCE_TRANSITION_POLL_MS}ms poll (non-advancing POST); not treating as verified`);
         }
         // DOM-only-advance veto (opt-in). A rephrase can turn an advance/"Next" step
         // into a field click (e.g. "click the Yes radio for '18?' then Next"), which
@@ -5087,7 +5274,7 @@ async function executeStepWithHealing(params) {
             ? domVerified
             : false;
         if (domVerified && !domVerifiedForStep) {
-            logger.info(`step ${stepIndex + 1} advance step succeeded only via DOM state change (field toggle / non-advancing POST), not a real transition; not treating as verified`);
+            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} advance step succeeded only via DOM state change (field toggle / non-advancing POST), not a real transition; not treating as verified`);
         }
         let verified = networkIsRealAdvance || urlChanged || domVerifiedForStep;
         // Final-step submit-verification gate. Replaces the deterministic
@@ -5189,7 +5376,7 @@ async function executeStepWithHealing(params) {
                 // Any-4xx fallback. The judge said failed; surface any captured 4xx
                 // body's field-level error JSON for the rephrase prompt downstream
                 // — same role as before the migration.
-                const fallbackEvidence = extractSubmitFailureEvidence(recentCaptures.slice(-tail.length), [], recon_shared_1.CAPTURES_DIR, "any-4xx");
+                const fallbackEvidence = extractSubmitFailureEvidence(recentCaptures.slice(-tail.length), [], (0, recon_shared_1.resolveReconRunDir)().graphqlDir, "any-4xx");
                 if (fallbackEvidence.length > 0) {
                     failureReasons.push(`any-4xx fallback: ${fallbackEvidence.split("\n")[0]}`.slice(0, 240));
                 }
@@ -5329,7 +5516,7 @@ async function executeStepWithHealing(params) {
                         retryNetworkIsRealAdvance,
                     });
                     if (fallbackDomOnlyAdvance) {
-                        logger.info(`step ${stepIndex + 1} n+16 fallback advanced but no real transition (non-advancing POST / field toggle); not treating as verified`);
+                        logger.info(`${formatStepPrefix(stepIndex, totalSteps)} n+16 fallback advanced but no real transition (non-advancing POST / field toggle); not treating as verified`);
                     }
                     let retryVerified = !clickBlockedByInvalid &&
                         !fallbackDomOnlyAdvance &&
@@ -5407,7 +5594,7 @@ async function executeStepWithHealing(params) {
                             failureReasons.push(`n+16 fallback: submit-judge-rejected: ${judgeVerdict.reason}`);
                         }
                     }
-                    logger.info(`n+16 probe: step=${stepIndex + 1} 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} verified=${retryVerified}`);
                     if (retryVerified) {
                         if (record.verifiedBy === null) {
                             record.verifiedBy = retryUrlChanged ? "url" : retryNetworkFired ? "network" : "dom";
@@ -5415,24 +5602,24 @@ async function executeStepWithHealing(params) {
                         record.post = retryPost;
                         attempts.push(record);
                         if (attempt > 1) {
-                            logger.info(`step ${stepIndex + 1} healed on attempt ${attempt} via ${record.technique} + el.click() fallback`);
+                            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} healed on attempt ${attempt} via ${record.technique} + el.click() fallback`);
                         }
                         else {
-                            logger.info(`step ${stepIndex + 1} succeeded on attempt 1 via ${record.technique} + el.click() fallback`);
+                            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} succeeded on attempt 1 via ${record.technique} + el.click() fallback`);
                         }
                         trajectory?.push({ stepIndex, verifiedBy: record.verifiedBy });
                         return "completed";
                     }
                 }
                 catch (probeErr) {
-                    logger.warn(`n+16 probe: step=${stepIndex + 1} attempt=${attempt} el.click() fallback threw: ${(0, errors_1.toErrorMessage)(probeErr)}`);
+                    logger.warn(`n+16 probe: step=${stepIndex + 1}/${totalSteps?.() ?? "?"} attempt=${attempt} el.click() fallback threw: ${(0, errors_1.toErrorMessage)(probeErr)}`);
                 }
             }
         }
         attempts.push(record);
         if (verified) {
             if (attempt > 1) {
-                logger.info(`step ${stepIndex + 1} healed on attempt ${attempt} via ${record.technique} (network=${networkFired} url=${urlChanged} dom=${domVerified})`);
+                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} healed on attempt ${attempt} via ${record.technique} (network=${networkFired} url=${urlChanged} dom=${domVerified})`);
             }
             else {
                 // Why log first-try wins explicitly: prior to this change, attempt-1
@@ -5442,19 +5629,29 @@ async function executeStepWithHealing(params) {
                 // collapse" (log showed 2 heals) but telemetry calls.ndjson showed
                 // 32 successful Stagehand acts. Surfacing attempt-1 wins lets the
                 // log match telemetry and prevents the same false alarm.
-                logger.info(`step ${stepIndex + 1} succeeded on attempt 1 via ${record.technique} (network=${networkFired} url=${urlChanged} dom=${domVerified})`);
+                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} succeeded on attempt 1 via ${record.technique} (network=${networkFired} url=${urlChanged} dom=${domVerified})`);
             }
             trajectory?.push({ stepIndex, verifiedBy: record.verifiedBy });
             return "completed";
         }
         const effectSignals = describeAttemptEffectSignals(pre, post, recentCaptureMeta, preMetaLength);
+        // Phantom-click verdict, computed from the SAME pre/post pair
+        // describeAttemptEffectSignals just rendered — not recomputed deltas.
+        // Recorded on every unverified attempt (not just attempt 1) so the
+        // failure dump's attempts[] always carries the classification; only
+        // attempt 1's verdict drives the escalation flag below.
+        record.phantomClickVerdict = (0, phantom_click_1.classifyPhantomClick)({
+            actResultSuccess: record.actResultSuccess,
+            pre,
+            post,
+        });
         const reason = record.errorMessage
             ? effectSignals
                 ? `${record.errorMessage}; ${effectSignals}`
                 : record.errorMessage
             : effectSignals || "no observable effect (no network, url, or dom change)";
         failureReasons.push(reason);
-        logger.warn(`step ${stepIndex + 1} attempt ${attempt} (${record.technique}) produced no observable effect — ${reason}`);
+        logger.warn(`${formatStepPrefix(stepIndex, totalSteps)} attempt ${attempt} (${record.technique}) produced no observable effect — ${reason}`);
         // One additive strategy among many: when a click on a final-step
         // submit/continue button fails AND the page surfaces a visible
         // <error> sibling next to a touched+dirty ng-invalid wrapper, surface
@@ -5479,7 +5676,7 @@ async function executeStepWithHealing(params) {
             for (const p of pairs) {
                 const validationReason = formatValidationRejectedReason(p);
                 failureReasons.push(validationReason);
-                logger.warn(`step ${stepIndex + 1} ${validationReason}`);
+                logger.warn(`${formatStepPrefix(stepIndex, totalSteps)} ${validationReason}`);
             }
         }
         // Telemetry-driven early-exit: when attempt 1 on a final-Submit click
@@ -5501,6 +5698,17 @@ 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.
+            phantomClickAfterAttempt1 = record.phantomClickVerdict === "phantom";
+            if (phantomClickAfterAttempt1) {
+                const suppressedCount = getSuppressedAisdkElementIdErrorCount?.();
+                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)` : ""} — escalating attempt 2 to deep-submit-locator`);
+            }
             const postAttemptInvalidCount = await countNgInvalidContainers(page);
             const earlyExit = isSubmitRevealedInvalid({
                 // Treat the canonical submit click as "final" for this predicate
@@ -5516,7 +5724,7 @@ async function executeStepWithHealing(params) {
             if (earlyExit) {
                 const exitReason = `submit-revealed-invalid: click surfaced ${postAttemptInvalidCount - preSubmitInvalidCount} new ng-invalid container(s) (was ${preSubmitInvalidCount}, now ${postAttemptInvalidCount}); attempts 2-${MAX_STEP_ATTEMPTS} cannot heal a form that needs answers — routing to replan`;
                 failureReasons.push(exitReason);
-                logger.warn(`step ${stepIndex + 1} ${exitReason}`);
+                logger.warn(`${formatStepPrefix(stepIndex, totalSteps)} ${exitReason}`);
                 break;
             }
             // Telemetry-driven early-exit for interior ADVANCE steps: if the Next
@@ -5536,7 +5744,7 @@ async function executeStepWithHealing(params) {
             if (advanceStalled) {
                 const exitReason = `advance-stalled: the Next click fired network but no real transition (type=next) landed within the poll window; attempts 2-${MAX_STEP_ATTEMPTS} would only re-bounce the wizard — routing to replan`;
                 failureReasons.push(exitReason);
-                logger.warn(`step ${stepIndex + 1} ${exitReason}`);
+                logger.warn(`${formatStepPrefix(stepIndex, totalSteps)} ${exitReason}`);
                 break;
             }
         }
@@ -5564,9 +5772,9 @@ async function executeStepWithHealing(params) {
         unfocusedObserve,
     }) ?? null;
     if (dumpPath !== null) {
-        logger.error(`step ${stepIndex + 1} failed after ${MAX_STEP_ATTEMPTS} attempts; diagnostic bundle: ${dumpPath}`);
+        logger.error(`${formatStepPrefix(stepIndex, totalSteps)} failed after ${MAX_STEP_ATTEMPTS} attempts; diagnostic bundle: ${dumpPath}`);
     }
-    throw new errors_2.StepVerificationError(`step ${stepIndex + 1} (${step.slice(0, 60)}) failed verification after ${MAX_STEP_ATTEMPTS} attempts${dumpPath ? `; see ${dumpPath}` : ""}`, "cascade-exhausted");
+    throw new errors_2.StepVerificationError(`${formatStepPrefix(stepIndex, totalSteps)} (${step.slice(0, 60)}) failed verification after ${MAX_STEP_ATTEMPTS} attempts${dumpPath ? `; see ${dumpPath}` : ""}`, phantomClickAfterAttempt1 ? "phantom-click-exhausted" : "cascade-exhausted");
 }
 /** SPA-readiness gate defaults — mirror the recon CLI's post-navigation wait. */
 const SPA_READINESS_TIMEOUT_MS = 15_000;
@@ -5648,6 +5856,7 @@ async function runHealingFlow(deps) {
                 upload: s.upload,
                 submitStep: s.submitStep,
                 stepIndex: i,
+                totalSteps: () => steps.length,
                 phase: "flow",
                 signalCounter,
                 recentCaptures,