@enricai/barnacle 1.6.1 → 1.6.3

package/dist/scraper/deep-query.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shadow-DOM-piercing element resolver. Every other primitive in
+ * flow-runner.ts locates elements via `document.querySelectorAll` /
+ * `document.evaluate`, which cannot see inside a shadow root — so a
+ * submit-shaped control rendered by a web component (Angular Elements,
+ * Stencil, etc.) is invisible to the engine even though it's live on the
+ * page. This module composes a `page.evaluate` expression string (the
+ * repo's established interpolation pattern — see `INVALID_MARKER_EL_EXPR`
+ * in flow-runner.ts) that recurses through `el.shadowRoot` for OPEN roots
+ * to find and click such a control. Closed roots are unreachable from page
+ * script by design; the traversal treats them as a dead end rather than
+ * throwing.
+ */
+/**
+ * Builds a self-contained `page.evaluate` expression string that locates
+ * the first submit-shaped control anywhere in the document — piercing open
+ * shadow roots — clicks it (setting focus, then dispatching bubbling
+ * mousedown/mouseup/click events, matching the repo's controlled-state
+ * click convention rather than a bare `el.click()`, see flow-runner.ts's
+ * checkbox/radio primitives), and returns a structured result so the
+ * caller can verify what happened without a second round-trip.
+ *
+ * Locate-only mode (`{ clickIfFound: false }`) is exposed for callers that
+ * want to probe for a deep submit control before deciding whether to act
+ * on it (e.g. to distinguish "no candidate anywhere" from "found but the
+ * click cascade should try a different technique first").
+ */
+export declare function buildDeepSubmitClickExpr(options?: {
+    clickIfFound?: boolean;
+}): string;
+/** Structured result of {@link buildDeepSubmitClickExpr}'s `page.evaluate` call. */
+export interface DeepSubmitClickResult {
+    found: boolean;
+    clicked: boolean;
+}
+//# sourceMappingURL=deep-query.d.ts.map

package/dist/scraper/deep-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-query.d.ts","sourceRoot":"","sources":["../../src/scraper/deep-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA4CH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAerF;AAED,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/dist/scraper/deep-query.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Shadow-DOM-piercing element resolver. Every other primitive in
+ * flow-runner.ts locates elements via `document.querySelectorAll` /
+ * `document.evaluate`, which cannot see inside a shadow root — so a
+ * submit-shaped control rendered by a web component (Angular Elements,
+ * Stencil, etc.) is invisible to the engine even though it's live on the
+ * page. This module composes a `page.evaluate` expression string (the
+ * repo's established interpolation pattern — see `INVALID_MARKER_EL_EXPR`
+ * in flow-runner.ts) that recurses through `el.shadowRoot` for OPEN roots
+ * to find and click such a control. Closed roots are unreachable from page
+ * script by design; the traversal treats them as a dead end rather than
+ * throwing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDeepSubmitClickExpr = buildDeepSubmitClickExpr;
+/**
+ * Text/attribute predicate for "this element is submit-shaped": a native
+ * `type="submit"` control, a `<button>` with no explicit `type` inside a
+ * `<form>` (the HTML default is submit), or a button-role element whose
+ * visible text/aria-label contains "submit". Kept as a standalone
+ * expression (not a RegExp) so it can be interpolated into a browser-
+ * context `page.evaluate` string, mirroring `INVALID_MARKER_EL_EXPR`.
+ */
+const SUBMIT_SHAPED_EL_EXPR = `((el) => {
+  const tag = (el.tagName || "").toLowerCase();
+  const type = (el.getAttribute("type") || "").toLowerCase();
+  if ((tag === "button" || tag === "input") && type === "submit") return true;
+  if (tag === "button" && !el.getAttribute("type") && el.closest("form")) return true;
+  const role = (el.getAttribute("role") || "").toLowerCase();
+  const isButtonLike = tag === "button" || role === "button";
+  if (!isButtonLike) return false;
+  const norm = (s) => (s || "").replace(/\\s+/g, " ").trim().toLowerCase();
+  const text = norm(el.getAttribute("aria-label") || el.textContent || "");
+  return /\\bsubmit\\b/.test(text);
+})`;
+/**
+ * Recursive open-shadow-root walker: returns every element in `root`
+ * (light DOM or a shadow root) plus, for each child with an OPEN
+ * `shadowRoot`, every element inside that shadow tree, arbitrarily deep.
+ * A closed shadow root (`element.shadowRoot === null` from page script's
+ * perspective) is simply not descended into — it contributes no elements,
+ * it does not throw.
+ */
+const DEEP_ELEMENTS_EXPR = `((root) => {
+  const out = [];
+  const walk = (node) => {
+    const kids = node.querySelectorAll ? Array.from(node.querySelectorAll("*")) : [];
+    for (const el of kids) {
+      out.push(el);
+      if (el.shadowRoot) walk(el.shadowRoot);
+    }
+  };
+  walk(root);
+  return out;
+})`;
+/**
+ * Builds a self-contained `page.evaluate` expression string that locates
+ * the first submit-shaped control anywhere in the document — piercing open
+ * shadow roots — clicks it (setting focus, then dispatching bubbling
+ * mousedown/mouseup/click events, matching the repo's controlled-state
+ * click convention rather than a bare `el.click()`, see flow-runner.ts's
+ * checkbox/radio primitives), and returns a structured result so the
+ * caller can verify what happened without a second round-trip.
+ *
+ * Locate-only mode (`{ clickIfFound: false }`) is exposed for callers that
+ * want to probe for a deep submit control before deciding whether to act
+ * on it (e.g. to distinguish "no candidate anywhere" from "found but the
+ * click cascade should try a different technique first").
+ */
+function buildDeepSubmitClickExpr(options) {
+    const clickIfFound = options?.clickIfFound ?? true;
+    return `(() => {
+    const isSubmitShaped = ${SUBMIT_SHAPED_EL_EXPR};
+    const deepElements = ${DEEP_ELEMENTS_EXPR};
+    const candidates = deepElements(document).filter(isSubmitShaped);
+    if (candidates.length === 0) return { found: false, clicked: false };
+    const el = candidates[0];
+    if (!${JSON.stringify(clickIfFound)}) return { found: true, clicked: false };
+    if (typeof el.focus === "function") { try { el.focus(); } catch (e) {} }
+    el.dispatchEvent(new Event("mousedown", { bubbles: true }));
+    el.dispatchEvent(new Event("mouseup", { bubbles: true }));
+    el.dispatchEvent(new Event("click", { bubbles: true }));
+    return { found: true, clicked: true };
+  })()`;
+}
+//# sourceMappingURL=deep-query.js.map

package/dist/scraper/deep-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-query.js","sourceRoot":"","sources":["../../src/scraper/deep-query.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH;;;;;;;GAOG;AACH,MAAM,qBAAqB,GAAG;;;;;;;;;;;GAW3B,CAAC;AAEJ;;;;;;;GAOG;AACH,MAAM,kBAAkB,GAAG;;;;;;;;;;;GAWxB,CAAC;AAEJ;;;;;;;;;;;;;GAaG;AACH,kCAAyC,OAAoC;IAC3E,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,IAAI,CAAC;IACnD,OAAO;6BACoB,qBAAqB;2BACvB,kBAAkB;;;;WAIlC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC;;;;;;OAMhC,CAAC;AACR,CAAC"}

package/dist/scraper/errors.d.ts

@@ -59,15 +59,24 @@ export declare class UnknownScraperError extends ScraperError {
     constructor(message?: string);
 }
 /** Discriminator for {@link StepVerificationError}. See the class TSDoc for the per-variant semantics. */
-export type StepVerificationErrorKind = "cascade-exhausted" | "probe-absent" | "backend-error-unrecoverable" | "replan-cycle-detected" | "wizard-regression";
+export type StepVerificationErrorKind = "cascade-exhausted" | "phantom-click-exhausted" | "probe-absent" | "backend-error-unrecoverable" | "replan-cycle-detected" | "wizard-regression";
 /**
- * Recon-only: a flow step in recon-browser.ts could not be acted on. Four
+ * Recon-only: a flow step in recon-browser.ts could not be acted on. Six
  * variants per `kind`:
  *
  *   - "cascade-exhausted": the full 4-attempt self-healing cascade ran and
  *     none of the attempts produced an observable effect. Expensive (the
  *     cascade burned its full LLM/observe budget) — counted against the
  *     cascade replan budget.
+ *   - "phantom-click-exhausted": attempt 1 phantom-clicked (Stagehand
+ *     reported success with zero network/url/DOM effect) and the cascade
+ *     escalated straight to the deep submit-control locator on attempt 2,
+ *     but every attempt through {@link MAX_STEP_ATTEMPTS} still produced no
+ *     observable effect — the submit control is unreachable by any
+ *     resolution strategy the cascade has, not just the light-DOM one.
+ *     Distinguished from "cascade-exhausted" so a replan/triager can skip
+ *     straight to a structural fix (e.g. a new locator strategy) instead of
+ *     re-trying the same techniques.
  *   - "probe-absent": the cheap page-state probe ran BEFORE the cascade
  *     and observed zero candidates for the step's instruction. We skip the
  *     cascade and ask for a replan immediately because the page state is
@@ -140,22 +149,11 @@ export declare class HttpRateLimitError extends ScraperError {
  * HTTP request nor a fresh Stagehand browser session can succeed. The caller must
  * back off and surface a "retry later" state rather than burning a Steel session.
  * Kept distinct from HttpRateLimitError so metrics/logs (classifyDispatchError)
- * can tell a requisition lock apart from a self-inflicted 429 rate limit.
+ * can tell a resource lock apart from a self-inflicted 429 rate limit.
  */
 export declare class HttpUrlLockedError extends ScraperError {
     constructor(message?: string);
 }
-/**
- * @deprecated Removed in 2.0.0. Oracle-specific and no longer thrown by the
- * engine — response-body sentinel detection now lives in the plugin via
- * `HttpClientOptions.classifyResponseBody`. A plugin that needs a retryable
- * token-expiry signal should define its own `ScraperError` subclass (see the
- * encompasshealth plugin). Retained only so existing importers of
- * `@enricai/barnacle/scraper/errors` keep resolving under a minor release.
- */
-export declare class OracleTokenExpiredError extends ScraperError {
-    constructor(message?: string);
-}
 /**
  * Structured result returned (not thrown) by the hot path when it cannot
  * complete the application because the user must supply additional data.

package/dist/scraper/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/scraper/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,8BAAsB,YAAa,SAAQ,KAAK;IAC9C,SAAgB,SAAS,EAAE,OAAO,CAAC;IAEnC,YAAY,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAI9C;CACF;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,YAAY;IAC5C,YAAY,OAAO,SAAkC,EAEpD;CACF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,YAAY,OAAO,SAA+B,EAEjD;CACF;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,YAAY,OAAO,SAA6B,EAE/C;CACF;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,YAAY,OAAO,SAA8B,EAEhD;CACF;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,YAAY,OAAO,SAA4B,EAE9C;CACF;AAED,0GAA0G;AAC1G,MAAM,MAAM,yBAAyB,GACjC,mBAAmB,GACnB,cAAc,GACd,6BAA6B,GAC7B,uBAAuB,GACvB,mBAAmB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,YACE,OAAO,SAA2D,EAClE,IAAI,GAAE,yBAA+C,EAItD;CACF;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,YAAY,OAAO,SAAkC,EAEpD;CACF;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,YAAY,OAAO,SAAwC,EAE1D;CACF;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,YAAY,OAAO,SAA0B,EAE5C;CACF;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IAClD,YAAY,OAAO,SAAiC,EAEnD;CACF;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IAClD,YAAY,OAAO,SAA2B,EAE7C;CACF;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;IACvD,YAAY,OAAO,SAAiD,EAEnE;CACF;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,KAAK,CAAC;IAChB,aAAa,EAAE,IAAI,CAAC;IACpB,aAAa,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;IACtD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,YAAY,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAI1D;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/scraper/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,8BAAsB,YAAa,SAAQ,KAAK;IAC9C,SAAgB,SAAS,EAAE,OAAO,CAAC;IAEnC,YAAY,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAI9C;CACF;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,YAAY;IAC5C,YAAY,OAAO,SAAkC,EAEpD;CACF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,YAAY,OAAO,SAA+B,EAEjD;CACF;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,YAAY,OAAO,SAA6B,EAE/C;CACF;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,YAAY,OAAO,SAA8B,EAEhD;CACF;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,YAAY,OAAO,SAA4B,EAE9C;CACF;AAED,0GAA0G;AAC1G,MAAM,MAAM,yBAAyB,GACjC,mBAAmB,GACnB,yBAAyB,GACzB,cAAc,GACd,6BAA6B,GAC7B,uBAAuB,GACvB,mBAAmB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,YACE,OAAO,SAA2D,EAClE,IAAI,GAAE,yBAA+C,EAItD;CACF;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,YAAY,OAAO,SAAkC,EAEpD;CACF;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,YAAY,OAAO,SAAwC,EAE1D;CACF;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,YAAY,OAAO,SAA0B,EAE5C;CACF;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IAClD,YAAY,OAAO,SAAiC,EAEnD;CACF;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IAClD,YAAY,OAAO,SAA2B,EAE7C;CACF;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,KAAK,CAAC;IAChB,aAAa,EAAE,IAAI,CAAC;IACpB,aAAa,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;IACtD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,YAAY,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAI1D;CACF"}

package/dist/scraper/errors.js

@@ -13,7 +13,7 @@
  * and the diagnostic it represents.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MissingFormMapKeyError = exports.OracleTokenExpiredError = exports.HttpUrlLockedError = exports.HttpRateLimitError = exports.HttpServerError = exports.HttpBotChallengeError = exports.HttpSchemaError = exports.StepVerificationError = exports.UnknownScraperError = exports.SessionTimeoutError = exports.SelectorFailureError = exports.EmptyResultsError = exports.CaptchaError = exports.ScraperError = void 0;
+exports.MissingFormMapKeyError = exports.HttpUrlLockedError = exports.HttpRateLimitError = exports.HttpServerError = exports.HttpBotChallengeError = exports.HttpSchemaError = exports.StepVerificationError = exports.UnknownScraperError = exports.SessionTimeoutError = exports.SelectorFailureError = exports.EmptyResultsError = exports.CaptchaError = exports.ScraperError = void 0;
 /**
  * Base class for all scraper-internal errors. Each subclass encodes a
  * distinct recovery policy (retryable or not) that retry.ts and loader.ts
@@ -82,13 +82,22 @@ class UnknownScraperError extends ScraperError {
 }
 exports.UnknownScraperError = UnknownScraperError;
 /**
- * Recon-only: a flow step in recon-browser.ts could not be acted on. Four
+ * Recon-only: a flow step in recon-browser.ts could not be acted on. Six
  * variants per `kind`:
  *
  *   - "cascade-exhausted": the full 4-attempt self-healing cascade ran and
  *     none of the attempts produced an observable effect. Expensive (the
  *     cascade burned its full LLM/observe budget) — counted against the
  *     cascade replan budget.
+ *   - "phantom-click-exhausted": attempt 1 phantom-clicked (Stagehand
+ *     reported success with zero network/url/DOM effect) and the cascade
+ *     escalated straight to the deep submit-control locator on attempt 2,
+ *     but every attempt through {@link MAX_STEP_ATTEMPTS} still produced no
+ *     observable effect — the submit control is unreachable by any
+ *     resolution strategy the cascade has, not just the light-DOM one.
+ *     Distinguished from "cascade-exhausted" so a replan/triager can skip
+ *     straight to a structural fix (e.g. a new locator strategy) instead of
+ *     re-trying the same techniques.
  *   - "probe-absent": the cheap page-state probe ran BEFORE the cascade
  *     and observed zero candidates for the step's instruction. We skip the
  *     cascade and ask for a replan immediately because the page state is
@@ -177,7 +186,7 @@ exports.HttpRateLimitError = HttpRateLimitError;
  * HTTP request nor a fresh Stagehand browser session can succeed. The caller must
  * back off and surface a "retry later" state rather than burning a Steel session.
  * Kept distinct from HttpRateLimitError so metrics/logs (classifyDispatchError)
- * can tell a requisition lock apart from a self-inflicted 429 rate limit.
+ * can tell a resource lock apart from a self-inflicted 429 rate limit.
  */
 class HttpUrlLockedError extends ScraperError {
     constructor(message = "requisition url locked") {
@@ -185,20 +194,6 @@ class HttpUrlLockedError extends ScraperError {
     }
 }
 exports.HttpUrlLockedError = HttpUrlLockedError;
-/**
- * @deprecated Removed in 2.0.0. Oracle-specific and no longer thrown by the
- * engine — response-body sentinel detection now lives in the plugin via
- * `HttpClientOptions.classifyResponseBody`. A plugin that needs a retryable
- * token-expiry signal should define its own `ScraperError` subclass (see the
- * encompasshealth plugin). Retained only so existing importers of
- * `@enricai/barnacle/scraper/errors` keep resolving under a minor release.
- */
-class OracleTokenExpiredError extends ScraperError {
-    constructor(message = "oracle token expired (ORA_IRC_TOKEN_EXPIRED)") {
-        super(message, true);
-    }
-}
-exports.OracleTokenExpiredError = OracleTokenExpiredError;
 /**
  * Thrown when code that translates stable semantic field keys (`address.city`,
  * `firstName`, `applicantGender`) into tenant-specific GUIDs via a runtime

package/dist/scraper/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/scraper/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/scraper/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH;;;;GAIG;AACH,kBAAmC,SAAQ,KAAK;IAC9B,SAAS,CAAU;IAEnC,YAAY,OAAe,EAAE,SAAkB;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;;AAED;;;GAGG;AACH,kBAA0B,SAAQ,YAAY;IAC5C,YAAY,OAAO,GAAG,+BAA+B;QACnD,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;CACF;;AAED;;;;GAIG;AACH,uBAA+B,SAAQ,YAAY;IACjD,YAAY,OAAO,GAAG,4BAA4B;QAChD,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;CACF;;AAED;;;;GAIG;AACH,0BAAkC,SAAQ,YAAY;IACpD,YAAY,OAAO,GAAG,0BAA0B;QAC9C,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACvB,CAAC;CACF;;AAED;;;;GAIG;AACH,yBAAiC,SAAQ,YAAY;IACnD,YAAY,OAAO,GAAG,2BAA2B;QAC/C,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACvB,CAAC;CACF;;AAED;;;GAGG;AACH,yBAAiC,SAAQ,YAAY;IACnD,YAAY,OAAO,GAAG,yBAAyB;QAC7C,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACvB,CAAC;CACF;;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,2BAAmC,SAAQ,YAAY;IAC5C,IAAI,CAA4B;IACzC,YACE,OAAO,GAAG,wDAAwD,EAClE,IAAI,GAA8B,mBAAmB;QAErD,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;;AAED;;;;GAIG;AACH,qBAA6B,SAAQ,YAAY;IAC/C,YAAY,OAAO,GAAG,+BAA+B;QACnD,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;CACF;;AAED;;;GAGG;AACH,2BAAmC,SAAQ,YAAY;IACrD,YAAY,OAAO,GAAG,qCAAqC;QACzD,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;CACF;;AAED;;;;;GAKG;AACH,qBAA6B,SAAQ,YAAY;IAC/C,YAAY,OAAO,GAAG,uBAAuB;QAC3C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;CACF;;AAED;;;;;GAKG;AACH,wBAAgC,SAAQ,YAAY;IAClD,YAAY,OAAO,GAAG,8BAA8B;QAClD,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;CACF;;AAED;;;;;;;;;GASG;AACH,wBAAgC,SAAQ,YAAY;IAClD,YAAY,OAAO,GAAG,wBAAwB;QAC5C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;CACF;;AAeD;;;;;;;;;;;;;GAaG;AACH,4BAAoC,SAAQ,YAAY;IAC7C,WAAW,CAAoB;IAC/B,OAAO,CAAS;IACzB,YAAY,WAA8B,EAAE,OAAe;QACzD,KAAK,CAAC,mCAAmC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC;QACzF,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/scraper/flow-runner.d.ts

@@ -15,6 +15,7 @@
 import type Anthropic from "@anthropic-ai/sdk";
 import type { Action, Page, Stagehand } from "@browserbasehq/stagehand";
 import { type LlmCallInput } from "../lib/telemetry/call-capture";
+import { type PhantomClickVerdict } from "../scraper/phantom-click";
 import { type Capture } from "../scripts/recon-shared";
 import type { Logger } from "../types/logging";
 /**
@@ -102,7 +103,7 @@ interface StepSnapshot {
 /** One attempt's audit trail — included verbatim in the failure dump. */
 export interface AttemptRecord {
     attempt: number;
-    technique: "act-string" | "observe-act" | "structured-click" | "observe-act-exclude" | "llm-rephrase";
+    technique: "act-string" | "observe-act" | "structured-click" | "observe-act-exclude" | "deep-submit-locator" | "llm-rephrase";
     instruction: string | null;
     triedSelectors: string[];
     actResultSuccess: boolean | null;
@@ -130,6 +131,15 @@ export interface AttemptRecord {
      * - `null`: failure path.
      */
     verifiedBy: "network" | "url" | "dom" | "submitted-state-dom" | null;
+    /**
+     * {@link classifyPhantomClick}'s verdict for this attempt, computed from
+     * the same pre/post snapshot pair `describeAttemptEffectSignals` already
+     * renders — `null` until the no-observable-effect branch runs (verified
+     * attempts never reach it). `"phantom"` (Stagehand claimed success but
+     * nothing observably happened) is what escalates the next attempt to
+     * `deep-submit-locator` instead of repeating a light-DOM technique.
+     */
+    phantomClickVerdict: PhantomClickVerdict | null;
 }
 export declare function snapshotPage(page: Page, signalCounter: {
     n: number;
@@ -137,11 +147,11 @@ export declare function snapshotPage(page: Page, signalCounter: {
 /**
  * Detect whether a 2xx response body indicates the server REJECTED the
  * application despite returning a 2xx HTTP status. Many ATSs use a "200 OK
- * with rejection envelope" pattern instead of a 4xx: AppCast returns
+ * with rejection envelope" pattern instead of a 4xx: one JSON-envelope ATS returns
  * `{not_qualified: true, error: "Not qualified reason: <field>"}`,
  * Greenhouse uses `{rejected: true, reason: "..."}`, Lever uses
  * `{qualified: false, reason: "..."}`, Workday uses
- * `{status: "rejected"}`. Empirically verified on AppCast: 4/6 historical
+ * `{status: "rejected"}`. Empirically verified on a JSON-envelope ATS: 4/6 historical
  * /integrated_apply 200s on this codebase had `not_qualified: true` and
  * we treated them as wins because the audit only checked HTTP status.
  *
@@ -247,7 +257,7 @@ export declare function latestCaptureIndex(recentCaptures: readonly string[]): n
  * read straight from `capturesDir` — NOT from the in-memory `recentCaptures`
  * array, which is front-evicted to `RECENT_CAPTURES_WINDOW` and therefore drops
  * a step's transition when >20 captures flood during the step (measured 43
- * across one HCA cascade). Scanning disk by filename index is eviction-proof:
+ * across one wizard-ATS cascade). Scanning disk by filename index is eviction-proof:
  * the transition file is always on disk regardless of array churn. `.decoded.json`
  * sidecars are excluded (the raw file carries `requestPostData`). Sorted by index
  * so callers scan in capture order. Returns [] when the dir is unreadable.
@@ -257,7 +267,7 @@ export declare function capturesAfterIndex(preIdx: number, capturesDir: string):
  * Detects a multi-page-wizard RESTART / backward navigation by scanning the
  * captures written during this step for a configured restart-signal pattern
  * (e.g. `init-apply`, `application_canceled=true`). The restart signal is often
- * a plain GET (Talemetry's `GET .../init-apply?...&application_canceled=true`),
+ * a plain GET (the wizard ATS's `GET .../init-apply?...&application_canceled=true`),
  * so it scans the raw capture files' `url` field (GETs are written to disk even
  * though they're dropped from `recentCaptureMeta`). Window scoped by
  * `preIdx` via {@link capturesAfterIndex} (eviction-proof). Returns the matching
@@ -267,7 +277,7 @@ export declare function capturesAfterIndex(preIdx: number, capturesDir: string):
  * Does any same-window network capture's REQUEST BODY match the configured
  * transition pattern? Proves an interior "advance"/"Next" step really moved the
  * wizard forward when advance and non-advance mutations share one endpoint URL
- * (e.g. Talemetry `/gq`: a real advance is a `TransitionWorklet` mutation, a
+ * (e.g. the wizard ATS's `/gq`: a real advance is a `TransitionWorklet` mutation, a
  * field edit is `EditQuestionItem` — same URL, only the body differs, so a
  * URL/meta-based check can't tell them apart). Window scoped by `preIdx` via
  * {@link capturesAfterIndex} (disk-scan by filename index — eviction-proof, so a
@@ -283,7 +293,7 @@ export declare function windowHasTransitionBody(params: {
  * Stricter sibling of {@link windowHasTransitionBody}: a same-window capture
  * whose request body matches the transition pattern AND whose parsed
  * `variables.input.type === "next"`. The mutation NAME alone is a weak
- * distinguisher — on Talemetry a `back` bounce is ALSO a `TransitionWorklet`
+ * distinguisher — on the wizard ATS a `back` bounce is ALSO a `TransitionWorklet`
  * mutation (its body contains the pattern too) and would wrongly count as an
  * advance; and the fast `WorkletPayload` autosave that precedes the real
  * transition is a different mutation with no `input.type`. Requiring the parsed
@@ -304,7 +314,7 @@ export declare function windowHasAdvanceTransition(params: {
  * the RC2 gate is unit-testable.
  *
  * An interior "Next" on an SPA where an advance and a mere field-edit share one
- * endpoint (Talemetry `/gq`: TransitionWorklet vs EditQuestionItem — same URL,
+ * endpoint (the wizard ATS's `/gq`: TransitionWorklet vs EditQuestionItem — same URL,
  * different body) can fire a network POST that is NOT a real advance; the
  * fallback's htmlDelta/textChanged/checked-radio signals are then validation
  * re-renders / field toggles that don't move the wizard. So for an opted-in
@@ -329,7 +339,7 @@ export declare function shouldVetoFallbackAdvance(params: {
  * transition fired — a URL change OR a real `type=next` (`networkIsRealAdvance`).
  * A DOM change alone is a validation re-render / field toggle that never moves
  * the wizard. Crucially this must veto even when a NON-advancing network POST
- * fired (Talemetry's `WorkletPayload` autosave): keying the veto on "no network
+ * fired (the wizard ATS's `WorkletPayload` autosave): keying the veto on "no network
  * at all" let a rephrase that triggered an autosave + DOM reflow false-verify an
  * advance, desyncing the flow from the wizard. Returns whether the DOM signal is
  * ALLOWED to verify: false = veto it. Non-advance/field steps, sites without the
@@ -386,7 +396,7 @@ export declare function describeAttemptEffectSignals(pre: StepSnapshot, post: St
  * keeps healing opportunistically.
  */
 export declare function shouldSkipTechnique(params: {
-    technique: "act-string" | "observe-act" | "structured-click" | "observe-act-exclude" | "llm-rephrase";
+    technique: "act-string" | "observe-act" | "structured-click" | "observe-act-exclude" | "deep-submit-locator" | "llm-rephrase";
     priorAttempts: readonly {
         technique: string;
         triedSelectors: readonly string[];
@@ -398,6 +408,32 @@ export declare function shouldSkipTechnique(params: {
      * effect at all. Optional so existing callers are unchanged.
      */
     advanceUnmovedAfterAttempt1?: boolean;
+    /**
+     * True when attempt 1 reported success but the pre/post snapshot shows zero
+     * observable effect (see {@link classifyPhantomClick}) — a phantom click.
+     * Re-observing/re-clicking the light DOM will no-op identically (the target
+     * is almost certainly unreachable via `document.querySelectorAll`, e.g.
+     * inside a shadow root), so skip straight to the deep submit-control locator
+     * instead of burning attempts 2-4 repeating the same no-op. Optional so
+     * existing callers are unchanged. Gated by {@link submitShapedStep} below —
+     * on a non-submit control the deep submit-control locator cannot resolve
+     * the target either, so this short-circuit only applies when the step is
+     * submit-shaped.
+     */
+    phantomClickAfterAttempt1?: boolean;
+    /**
+     * True when the current step is a submit-shaped action (`isFinalStep ||
+     * submitStep`, the canonical gate used elsewhere in this file). The deep
+     * submit-control locator ranks submit-shaped candidates only and
+     * deliberately excludes Back/Cancel/Save-draft controls, so it is a
+     * guaranteed no-op on a non-submit control (e.g. a radio/checkbox). Scopes
+     * the phantom-click short-circuit above to submit-shaped steps only —
+     * on a non-submit step the fallback ladder (`structured-click`,
+     * `observe-act-exclude`) is left intact since those are the techniques
+     * that can actually click a radio or checkbox. Optional so existing
+     * callers are unchanged.
+     */
+    submitShapedStep?: boolean;
 }): {
     skip: boolean;
     reason: string;
@@ -445,7 +481,7 @@ export declare function isSubmitRevealedInvalid(params: {
  * landed within the poll window (`networkIsRealAdvance` false), the button works
  * but the wizard is refusing to advance (a precondition isn't met, e.g. a
  * required field the flow answers on a LATER step). Re-clicking the same button
- * only re-fires the autosave / a `back` bounce — measured across HCA runs as the
+ * only re-fires the autosave / a `back` bounce — measured across wizard-ATS runs as the
  * next→back oscillation. Break to replan instead, which can reorder a later step
  * forward. Conservative: any condition unmet → run the full cascade as before.
  * Never fires on final/submit steps (they own `isSubmitRevealedInvalid`) or on
@@ -486,7 +522,7 @@ export declare function rephraseWithLLM(client: Anthropic, originalStep: string,
  * invalid form fields and visible error messages so the rephrase LLM can
  * propose corrective fills instead of
  * just "click harder" — the previous limitation observed in the
- * telemetry of the appcast Encompass run (every rephrase converged on
+ * telemetry of the JSON-envelope ATS run (every rephrase converged on
  * "Click Submit Application using JavaScript" because the prompt had no
  * signal that the form was invalid).
  */
@@ -618,8 +654,8 @@ export declare function formatValidationRejectedReason(pair: ValidationRejection
  * Default: first 8KB. That window held for tenants whose form was at the
  * top of the page (early sweeps in 2026-06).
  *
- * For pages where the form HTML lives below 8KB (verified on AppCast's
- * applyboard SPA: ng-invalid first appears at byte ~15,500 after a header
+ * For pages where the form HTML lives below 8KB (verified on an Angular
+ * apply SPA: ng-invalid first appears at byte ~15,500 after a header
  * of Angular hydration JS + chrome), the 8KB cap silently produced
  * "FORM FIELDS CURRENTLY MARKED INVALID: (none)" in the replan prompt,
  * leaving the LLM with no evidence and causing it to hallucinate steps
@@ -630,7 +666,7 @@ export declare function formatValidationRejectedReason(pair: ValidationRejection
  *
  * Site-agnostic: the markers we look for (ng-invalid, mat-form-field-
  * invalid, is-invalid, <form) are framework-level CSS-class conventions
- * used across countless SPAs, not AppCast-specific.
+ * used across countless SPAs, not specific to any one ATS.
  */
 export declare function selectBodyExcerpt(body: string): string;
 /**
@@ -674,7 +710,7 @@ export interface LeafInvalidField {
  * matches `ng-invalid` because of bubbling, but its child `<app-input
  * class="ng-invalid">` ALSO matches; `:not(:has(...))` filters out the parent.
  *
- * Today's Encompass-Fitchburg smoke (run 1781478440322) showed E1's prompt
+ * A JSON-envelope ATS tenant's smoke (run 1781478440322) showed E1's prompt
  * instruction ("prefer the leaf, not the bubbled parent") only got Haiku from
  * 5 wrong fields → 1 wrong field — still surfaced `(unlabeled) <ol>` instead
  * of `<app-input autocomplete="zip-code">` at byte 95,033. All 3 replans + 4
@@ -703,8 +739,9 @@ export declare function renderLeafInvalidFields(fields: readonly LeafInvalidFiel
 /**
  * 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 }`).
@@ -724,7 +761,7 @@ export declare function extractSubmitFailureEvidence(recentCaptureFilenames: rea
 ownBackendHostnames: readonly string[], capturesDir?: string, mode?: "strict" | "any-4xx"): string;
 /**
  * Surface Google Analytics Measurement Protocol events captured during a
- * step's attempt window. AppCast (and most GA4-instrumented SPAs) emit
+ * step's attempt window. A JSON-envelope ATS (and most GA4-instrumented SPAs) emits
  * `view_secondPage`, `view_thankYouPage`, `form_submit` and similar events
  * via `https://www.google-analytics.com/g/collect` — the engine already
  * stores these in `recentCaptures[]` but no code reads them. Without
@@ -741,8 +778,8 @@ ownBackendHostnames: readonly string[], capturesDir?: string, mode?: "strict" |
 export declare function extractGaEventEvidence(recentCaptureFilenames: readonly string[], capturesDir?: string): string;
 /**
  * Render a long step list as a small head + tail window with an elision
- * marker. Replan prompts grew to ~114KB on the AppCast 331-step flow
- * (verified Fitchburg 2026-06-14 run), causing Sonnet 4.6 to TTFT-stall
+ * marker. Replan prompts grew to ~114KB on a JSON-envelope ATS's 331-step flow
+ * (verified on a 2026-06-14 tenant run), causing Sonnet 4.6 to TTFT-stall
  * out at 187s with `APIConnectionTimeoutError: Request timed out.` —
  * the ONLY non-API-quota replan failure across ~30+ historical calls.
  *
@@ -853,7 +890,7 @@ export declare function verifyFillReadback(page: Page, xpath: string, expectedVa
  * True when a control's text/aria-label denotes a resume-upload affordance
  * (the button that surfaces a hidden `<input type=file>` or opens a chooser).
  * Pure + exported for unit tests; the vocabulary is intentionally generic so it
- * benefits any MUI/React/dropzone ATS, not just Talemetry. Rejects negative
+ * benefits any MUI/React/dropzone ATS, not just the wizard ATS. Rejects negative
  * lookalikes ("upload later", "no file", a bare "submit") so the click-to-
  * surface path never fires a skip/decline/submit control.
  */
@@ -873,7 +910,7 @@ export declare function writeFixtureToTempFile(fixture: {
  * Parse a select/dropdown flow step into the option to choose and (when
  * present) the question label that scopes which dropdown it targets.
  *
- * Why: HCA/Talemetry render dropdowns as `MuiNativeSelect` native `<select>`
+ * Why: the Angular/MUI wizard ATS renders dropdowns as `MuiNativeSelect` native `<select>`
  * with `tabindex="-1"` — removed from the accessibility tree, so Stagehand
  * observe returns `[]` and the cascade can never select an option. The select
  * primitive answers these directly from the DOM, but needs the target option
@@ -899,7 +936,7 @@ export declare function parseSelectStep(instruction: string): {
  * Why this exists (sibling of `parseSelectStep`): `parseSelectStep`
  * deliberately excludes bare radio steps ("a bare 'click the Yes answer' is a
  * radio"), leaving radios with no DOM-direct primitive — they fall to the
- * observe cascade, which on HCA/Talemetry's MUI radio markup resolves the step
+ * observe cascade, which on the wizard ATS's MUI radio markup resolves the step
  * to a wrapper `<div>`/`<span>` (not the `<input type=radio>`) and commits via
  * a bare `el.click()` that never triggers React's controlled-state `onChange`.
  * The field stays `Mui-error` "required", Next no-ops, and the wizard walls at
@@ -919,7 +956,7 @@ export declare function parseRadioStep(instruction: string): {
 } | null;
 /**
  * Run a primitive's read-only DOM enumerate with a bounded settle-retry. SPA
- * wizards (Talemetry) frequently render the target widget a beat AFTER the flow
+ * wizards frequently render the target widget a beat AFTER the flow
  * step fires — the first evaluate sees an empty page, so the primitive would
  * give up even though the widget appears moments later. Re-run the enumerate up
  * to `PRIMITIVE_ENUMERATE_ATTEMPTS` times, waiting `PRIMITIVE_ENUMERATE_RETRY_MS`
@@ -940,7 +977,7 @@ export declare function pollEnumerate<T>(page: Page, expr: string, isPresent: (r
  * Bounded poll for the real advance-transition POST to appear in this step's
  * capture window. The verifiers snapshot once after `STEP_PAUSE_MS`, but the
  * genuine `TransitionWorklet(type="next")` POST can land hundreds of ms to 2s+
- * AFTER that snapshot (HCA fires a fast `WorkletPayload` autosave first). A
+ * AFTER that snapshot (the wizard ATS fires a fast `WorkletPayload` autosave first). A
  * one-shot check false-negatives the advance, retries the click, and the stale
  * retry fires a `back` — a next→back oscillation that never leaves the page.
  * Re-check {@link windowHasAdvanceTransition} every `intervalMs` until it matches
@@ -963,7 +1000,7 @@ export declare function waitForTransitionBody(params: {
  * Pick an option to satisfy a REQUIRED select on a catch-all step, from the
  * select's option TEXTS (placeholder already excluded upstream). Policy: take
  * the first non-decline option (a plausible substantive answer — the operator
- * accepts LLM-plausible answers reaching HCA prod); fall back to the first
+ * accepts LLM-plausible answers reaching ATS prod); fall back to the first
  * option only if every option is a decline/placeholder. Returns null when there
  * is nothing selectable. Pure + exported so the policy is unit-testable; the LLM
  * path ({@link judgeSelectOptionWithLLM}) is preferred when a client is present,
@@ -992,7 +1029,7 @@ export type RadioGroupCandidate = {
 };
 /**
  * Build an XPath predicate that matches an `<input>` by its `id`, safe for any
- * id value. MUI/Talemetry radio ids are base64-ish (no double-quote), so a plain
+ * id value. MUI wizard radio ids are base64-ish (no double-quote), so a plain
  * quoted literal suffices — but if an id ever contains a `"`, fall back to
  * `concat(...)` so the XPath stays valid. Pure + exported for unit tests.
  */
@@ -1002,7 +1039,7 @@ export declare function buildRadioIdXPath(id: string): string;
  * positionally. Pure (no DOM/LLM) so it is unit-testable — the crux of the
  * unlabeled-radio disambiguation.
  *
- * Why this exists: HCA/Talemetry Basic Info has multiple UNLABELED yes/no groups
+ * Why this exists: the wizard ATS's Basic Info has multiple UNLABELED yes/no groups
  * (visa-sponsorship, common-domicile), answered by consecutive flow steps. The
  * old in-browser matcher treated an unlabeled group (`label===""`) as matching
  * ANY question (`"".includes(q)`/`q.includes("")===0`), so two unlabeled "No"
@@ -1101,6 +1138,18 @@ export interface InvalidFormControl {
  * action+value object; anything else becomes null).
  */
 export declare function narrowInvalidFormControl(entry: unknown): InvalidFormControl | null;
+/**
+ * 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.
+ */
+export declare function formatStepPrefix(stepIndex: number, totalSteps?: () => number): string;
 /**
  * Cheap pre-cascade reachability gate. Runs before the 5-attempt healing cascade
  * (and any global replan) so a step aimed at the wrong page state fails fast
@@ -1114,6 +1163,7 @@ export declare function probeStepBeforeAttempts(params: {
     stagehand: Stagehand;
     step: string;
     stepIndex: number;
+    totalSteps?: () => number;
     logger: Logger;
     captureFn?: CaptureFn;
 }): Promise<"present" | "absent">;
@@ -1137,7 +1187,7 @@ export declare function executeStepWithHealing(params: {
     /**
      * When true, treat this step as the canonical submit click for the
      * `submitEndpointPattern` verifier even if it is NOT the last step in
-     * the flow. Set from the flow file's `submitStep: true`. AppCast's flow
+     * the flow. Set from the flow file's `submitStep: true`. One JSON-envelope ATS flow
      * has its Submit click at index 55/328 — without this flag, the pre-
      * submit DOM probe (gated on isFinalStep alone) never fires on the real
      * Submit, so unfilled required fields produce silent submit failures.
@@ -1145,6 +1195,12 @@ export declare function executeStepWithHealing(params: {
      */
     submitStep: boolean;
     stepIndex: number;
+    /**
+     * Getter, not a number: a global replan splices new steps into the live plan
+     * array mid-run, so the denominator must be read at log time or every line
+     * after a replan prints a stale total.
+     */
+    totalSteps?: () => number;
     phase: string;
     signalCounter: {
         n: number;
@@ -1228,6 +1284,17 @@ export declare function executeStepWithHealing(params: {
      * so an advance step never fires a save-and-exit / cancel / restart control.
      */
     wizardExitButtonLabels: string[];
+    /**
+     * Live accessor for the running count of suppressed Stagehand AISDK
+     * elementId-regex errors this session (see
+     * `BrowserSession.getSuppressedAisdkElementIdErrorCount`). Corroborating
+     * evidence only when a phantom click is detected — logged alongside the
+     * escalation, never a trigger by itself (a nonzero count alone is too weak
+     * a signal across a whole run). Omitted or absent on providers that don't
+     * expose it (e.g. Steel); the phantom-click detection is unaffected either
+     * way since it is keyed on the pre/post snapshot delta.
+     */
+    getSuppressedAisdkElementIdErrorCount?: () => number;
     /**
      * Optional accumulator the cascade pushes onto when this step verifies.
      * Lets the main loop maintain a short cross-step trajectory of `verifiedBy`