@enricai/barnacle 1.0.0

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

@@ -0,0 +1,1319 @@
+/**
+ * Self-heal step-execution engine for Phase 1 recon. Extracted verbatim from
+ * `recon-browser.ts` so the step runner, its five DOM primitives (upload,
+ * select, checkbox, radio, required-selects), the pure verify/signal helpers,
+ * and the in-memory network-capture wiring can be reused and unit-tested apart
+ * from the recon CLI entry-point. This module is a leaf: it never imports the
+ * recon CLI module, so the CLI can depend on it without a cycle.
+ *
+ * Two seams let the CLI inject its disk-facing behavior without this module
+ * knowing about the filesystem layout: {@link wireSignalCapture} takes an
+ * `onCapture` callback for persisting each capture, and
+ * {@link executeStepWithHealing} takes an `onStepFailure` callback for writing
+ * the terminal failure dump.
+ */
+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 Capture } from "../scripts/recon-shared";
+import type { Logger } from "../types/logging";
+/**
+ * Wires CDP Network event listeners onto the page's main session and returns
+ * a cleanup function. Stagehand V3 already enables the Network domain
+ * internally, so we only need to attach our own listeners.
+ *
+ * Uses `requestId` to correlate requestWillBeSent/responseReceived/loadingFinished
+ * so we can fetch the response body only after it's fully received.
+ *
+ * Owns only the in-memory half of capture handling: builds each {@link Capture},
+ * records it in the rolling `recentCaptures`/`recentCaptureMeta` windows, and
+ * emits the analytics early-warnings. Persistence is delegated to the optional
+ * `onCapture` callback so the recon CLI can own the disk layout without this
+ * leaf module depending on it.
+ */
+export declare function wireSignalCapture(page: Page, params: {
+    counter: {
+        n: number;
+    };
+    signalCounter: {
+        n: number;
+    };
+    recentCaptures: string[];
+    recentCaptureMeta: {
+        method: string;
+        status: number;
+        url: string;
+    }[];
+    getCurrentPhase: () => string;
+    getCurrentPageOrigin: () => string;
+    onCapture?: (capture: Capture, filename: string) => void;
+}): () => void;
+/** Navigation timeout for page.goto — raise for slow tunnels or proxied targets. */
+export declare const GOTO_TIMEOUT_MS = 120000;
+/**
+ * Per-step watchdog passed as Stagehand's native `timeout` on every
+ * `act()`/`observe()`. Stagehand's `ensureTimeRemaining()` checks the
+ * deadline between work units and throws `ActTimeoutError` cleanly on
+ * expiry — the healing cascade catches it as just another attempt failure.
+ * Matches `GOTO_TIMEOUT_MS` precedent so a hung Stagehand call can't pin
+ * the recon for hours.
+ */
+export declare const STEP_WATCHDOG_MS = 120000;
+/**
+ * How many steps from the end of the flow are considered "trailing" for the
+ * Tier 1 grace path. A verification failure on an optional step within this
+ * window is treated as a benign no-op exit when a recent non-GET capture also
+ * returned 2xx — the flow's real work landed and the trailing tail is
+ * redundant. Two covers the common pattern: an upload step followed by a
+ * final Continue/Submit click.
+ */
+export declare const TRAILING_GRACE_WINDOW = 2;
+/** Cheap snapshot of side effects we use to decide whether a step "worked". */
+interface StepSnapshot {
+    networkCount: number;
+    url: string;
+    /**
+     * `document.body.outerHTML.length`. Measurement-only — pre/post delta
+     * exposes whether a click triggered a client-side state change that
+     * doesn't show up in network or URL (e.g. React view swap inside an SPA).
+     * Not consumed by the verifier yet; gathered for threshold tuning.
+     */
+    bodyHtmlLength: number;
+    /**
+     * `document.body.innerText.length + ":" + first 200 chars`. A cheap,
+     * deterministic proxy for "did the visible text change" that filters
+     * React-internal attribute churn (which moves `bodyHtmlLength` without
+     * moving anything the user perceives). Measurement-only.
+     */
+    visibleTextSignature: string;
+}
+/** 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";
+    instruction: string | null;
+    triedSelectors: string[];
+    actResultSuccess: boolean | null;
+    actResultDescription: string | null;
+    errorMessage: string | null;
+    pre: StepSnapshot;
+    post: StepSnapshot;
+    /**
+     * Stagehand-resolved action method (`fill`, `click`, etc.) that the verifier
+     * used to decide signal type. Null when no action was resolved (observe
+     * returned no candidates) or when Stagehand returned an empty actions[].
+     */
+    resolvedMethod: string | null;
+    /** Args Stagehand passed to the resolved action — what we expect to see post-fill. */
+    resolvedArguments: string[] | null;
+    /**
+     * Which verification signal carried the attempt:
+     * - `network`: same-origin POST counter advanced in the attempt window.
+     * - `url`: page navigated to a new URL.
+     * - `dom`: verifyDomEffect confirmed a structural change (radio/checkbox state).
+     * - `submitted-state-dom`: final-step DOM fallback fired — a flow-declared
+     *   `submittedStateSelectors` entry matched live DOM, indicating the SPA
+     *   reached its submitted state even though the network capture missed
+     *   the submit POST within the attempt window.
+     * - `null`: failure path.
+     */
+    verifiedBy: "network" | "url" | "dom" | "submitted-state-dom" | null;
+}
+export declare function snapshotPage(page: Page, signalCounter: {
+    n: number;
+}): Promise<StepSnapshot>;
+/**
+ * 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
+ * `{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
+ * /integrated_apply 200s on this codebase had `not_qualified: true` and
+ * we treated them as wins because the audit only checked HTTP status.
+ *
+ * Site-agnostic: the helper checks for the union of common rejection
+ * envelope shapes. New ATSs can be added by extending the recognized
+ * keys; the existing ones cover the four most common patterns.
+ */
+/**
+ * Detect whether the supplied capture-meta window contains a backend
+ * 5xx response that matches the configured submit endpoint pattern.
+ * The cascade can't heal a backend crash by retrying clicks or
+ * rephrasing instructions; surfacing this signal lets the caller
+ * fail-fast instead of burning replan budget on an unrecoverable
+ * server state.
+ *
+ * Conservative: requires both `submitEndpointPattern` to match (5xx
+ * from analytics/tracking URLs is noise, not a real backend failure)
+ * AND a 5xx status. Returns the matched URL when found; null otherwise.
+ */
+export declare function findRecentBackendError(params: {
+    recentCaptureMeta: readonly {
+        method: string;
+        status: number;
+        url: string;
+    }[];
+    preMetaLength: number;
+    /**
+     * Hostnames considered "the site's own backend." Replaces the prior
+     * `submitEndpointPattern` regex — we no longer pattern-match URL paths,
+     * just check hostname against the site-supplied whitelist (deterministic
+     * string equality on a URL component, not a fuzzy regex). A 5xx from any
+     * URL whose hostname is on this list is treated as a backend error;
+     * 5xx from third-party hosts (analytics, CDNs) is ignored. Empty array
+     * disables the check entirely.
+     */
+    ownBackendHostnames: readonly string[];
+}): string | null;
+/**
+ * Detect whether the page legitimately transitioned within the supplied
+ * capture-meta window — a 3xx redirect or a same-origin non-GET capture
+ * that returned 2xx and looks like a flow-progression URL (not a tracking
+ * beacon). `preMetaLength` is the caller's chosen window start (typically
+ * captured at step entry, so the scan covers everything that landed since
+ * this step began processing). When a transition is detected, a probe-
+ * absent escalation to replan is unnecessary noise — the form auto-
+ * advanced and the next probe naturally sees zero candidates for the OLD
+ * step.
+ *
+ * Conservative: returns null when the signal is ambiguous so the cascade
+ * keeps its existing replan path. Returns the matched URL string when a
+ * transition is detected, which the caller logs as the reason for the
+ * clean skip.
+ */
+export declare function findRecentPageTransition(params: {
+    recentCaptureMeta: readonly {
+        method: string;
+        status: number;
+        url: string;
+    }[];
+    preMetaLength: number;
+}): string | null;
+/**
+ * True when a resolved action's description names a wizard-exit control (a
+ * save-and-exit / cancel / restart button) rather than a forward action.
+ * Matched case-insensitively as a substring against the built-in list plus any
+ * site-supplied `extraLabels`. Bare "cancel"/"back" are intentionally NOT in the
+ * default list (too many false positives, e.g. "cancel changes to this field",
+ * "background"); a site can add them via `wizardExitButtonLabels` if its wizard
+ * uses them destructively.
+ */
+export declare function isWizardExitAction(description: string | null | undefined, extraLabels?: readonly string[]): boolean;
+/**
+ * Is this flow step an advance/"Next" click (move to the next wizard page),
+ * rather than a field-answer? Used to veto a DOM-only "success" (a field toggle)
+ * from counting as an advance: toggling a control never moves the wizard, so an
+ * advance step must be verified by a real transition (network/URL), not a DOM
+ * state change. Keyed on the ORIGINAL step instruction so a rephrase that
+ * resolves "Next" to a radio click can't launder a field toggle into a passed
+ * advance. Pure; unit-testable seam mirroring `isWizardExitAction`.
+ */
+export declare function isAdvanceStep(instruction: string | null | undefined): boolean;
+/**
+ * Parse the monotonic capture index from a capture filename. Every capture is
+ * written as `<idx>-<phase>-<unix-ms>-<hash>.json` where `<idx>` is a
+ * zero-padded, never-reused counter (`counter.n++`). Returns the numeric prefix,
+ * or null when the name has no leading integer. Pure; the seam the window
+ * helpers use to scope a step's captures by INDEX rather than by array position.
+ */
+export declare function parseCaptureIndex(filename: string): number | null;
+/**
+ * The highest capture index currently known, read from the LIVE `recentCaptures`
+ * array's last entry (captures are appended in index order, so the tail always
+ * carries the high-water mark even after the array is front-evicted to
+ * `RECENT_CAPTURES_WINDOW`). Snapshotting THIS before a step, then asking the
+ * window helpers for captures with a greater index, scopes the scan to the
+ * step's own captures WITHOUT depending on the capped array holding them — the
+ * eviction-proof replacement for the old `recentCaptures.length` slice index.
+ * Returns -1 when nothing has been captured yet (so index 0 is in-window).
+ */
+export declare function latestCaptureIndex(recentCaptures: readonly string[]): number;
+/**
+ * Filenames of the raw captures written AFTER `preIdx` (this step's window),
+ * 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:
+ * 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.
+ */
+export declare function capturesAfterIndex(preIdx: number, capturesDir: string): 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`),
+ * 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
+ * URL (for the diagnostic) or null. No-op when no `restartSignalUrlPatterns`.
+ */
+/**
+ * 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
+ * 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
+ * transition isn't lost when >20 captures flood during the step). Returns false
+ * when no pattern is configured (opt-in) or nothing in the window matches.
+ */
+export declare function windowHasTransitionBody(params: {
+    preIdx: number;
+    advanceTransitionBodyPattern: string | null;
+    capturesDir?: string;
+}): boolean;
+/**
+ * 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`
+ * 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
+ * `type==="next"` isolates a genuine FORWARD advance. Deliberately does NOT use
+ * `input.is_next` — it is inverted/unreliable on this ATS (a real `next` carries
+ * `is_next:false`, a `back` carries `is_next:true`). Window scoped by `preIdx`
+ * via {@link capturesAfterIndex} (eviction-proof disk-scan). Opt-in /
+ * site-agnostic: returns false when no pattern is configured.
+ */
+export declare function windowHasAdvanceTransition(params: {
+    preIdx: number;
+    advanceTransitionBodyPattern: string | null;
+    capturesDir?: string;
+}): boolean;
+/**
+ * Decide whether the n+16 `el.click()` fallback's "advance" signals should be
+ * VETOED — i.e. NOT counted as verifying a wizard transition. Pure + exported so
+ * 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,
+ * 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
+ * (`hasPattern`) non-final/non-submit ADVANCE step, a real advance requires a URL
+ * change OR a same-window capture body matching the transition pattern
+ * (`retryNetworkIsRealAdvance`); anything less is vetoed. Non-advance/field-answer
+ * steps and sites without the pattern are never vetoed here.
+ */
+export declare function shouldVetoFallbackAdvance(params: {
+    hasPattern: boolean;
+    isFinalOrSubmit: boolean;
+    isAdvance: boolean;
+    retryUrlChanged: boolean;
+    retryNetworkIsRealAdvance: boolean;
+}): boolean;
+/**
+ * Whether a DOM-verified signal should count as verifying an interior ADVANCE
+ * step (the PRIMARY verifier's counterpart to {@link shouldVetoFallbackAdvance}).
+ * Pure + exported so the RC2-on-the-DOM-branch gate is unit-testable.
+ *
+ * An advance/"Next" on a pattern-configured SPA is only real when a genuine
+ * 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
+ * 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
+ * pattern, and final/submit steps are never vetoed here (DOM stands).
+ */
+export declare function isDomOnlyAdvanceVerified(params: {
+    hasPattern: boolean;
+    isFinalOrSubmit: boolean;
+    isAdvance: boolean;
+    domVerified: boolean;
+    networkIsRealAdvance: boolean;
+    urlChanged: boolean;
+}): boolean;
+/**
+ * Read-only count of ng-invalid form controls on the page. Side-effect-free
+ * counterpart to `probeFormValidityBeforeSubmit` (which also auto-fills
+ * unselected radio groups via element.click()). Used by the cascade's
+ * early-exit predicate to detect "the Submit click revealed new required
+ * questions" — when this count grows from 0 (pre-submit) to ≥1 (post-attempt-1),
+ * attempts 2-5 cannot succeed and the cascade should route to replan
+ * immediately instead of burning Stagehand calls.
+ */
+export declare function countNgInvalidContainers(page: Page): Promise<number>;
+/**
+ * Translate the pre/post snapshot delta + same-window captures into a short
+ * diagnostic phrase that goes into `failureReasons[]`. Surfaces patterns the
+ * verifier itself discards: e.g. "DOM grew but no submit-shaped network
+ * request" (client-side validation blocked the form), or "analytics beacon
+ * fired but no same-origin submit" (third-party tracking, not real signal).
+ * The rephrase + replan LLMs read these strings to choose between "retry the
+ * click" and "fill an unanswered required field".
+ */
+export declare function describeAttemptEffectSignals(pre: StepSnapshot, post: StepSnapshot, recentCaptureMeta: readonly {
+    method: string;
+    status: number;
+    url: string;
+}[], preMetaLength: number): string;
+/**
+ * Was the failed step *structurally* unresolvable — i.e. no cascade attempt ever
+ * resolved a selector/control for it — as opposed to a control that WAS found but
+ * failed to verify? True only when every attempt resolved nothing
+ * (`triedSelectors` empty) and none carried a verification signal. The replan
+ * prompt uses this to stop merely rewording a step whose target the engine has no
+ * driver for (e.g. a custom widget), and instead propose a different path or mark
+ * impossible. Conservative: any attempt that resolved a selector or verified makes
+ * this false (that step is resolvable; rewording may still help).
+ */
+/**
+ * Decide whether a cascade technique's preconditions cannot be met by the
+ * prior attempts' state, so running it would burn the attempt slot without
+ * exercising new behaviour. Conservative: returns true ONLY when the
+ * predicate can prove the technique is mathematically unable to succeed;
+ * anything ambiguous falls through to "run the attempt" so the cascade
+ * keeps healing opportunistically.
+ */
+export declare function shouldSkipTechnique(params: {
+    technique: "act-string" | "observe-act" | "structured-click" | "observe-act-exclude" | "llm-rephrase";
+    priorAttempts: readonly {
+        technique: string;
+        triedSelectors: readonly string[];
+        errorMessage: string | null;
+    }[];
+    /**
+     * True when the step is a wizard ADVANCE ("Next") whose attempt-1 produced no
+     * real forward transition — either a non-advancing POST or no observable
+     * effect at all. Optional so existing callers are unchanged.
+     */
+    advanceUnmovedAfterAttempt1?: boolean;
+}): {
+    skip: boolean;
+    reason: string;
+};
+/**
+ * Bucket the recent `recon-replan` LLM calls by `failureKind` and produce a
+ * single diagnostic phrase the runner can surface when the cascade aborts
+ * its replan budget. Lets the operator distinguish transient
+ * (anthropic-rate-limit) from permanent (schema-validation-failed,
+ * response-empty) failure modes without having to grep calls.ndjson.
+ *
+ * Reads the most recent N entries from the configured calls path, filters
+ * to the matching callType, and tallies their failureKind. Empty string
+ * when no relevant failures are present.
+ */
+/**
+ * Decide whether attempt 1 on a final-Submit click revealed new required
+ * questions that mathematically can't be cleared by retrying the same
+ * click. When true, the cascade should break out of its attempt loop and
+ * route directly to global replan, which already reads the failure dump's
+ * ng-invalid + interactive-target lists and produces follow-up steps.
+ *
+ * Strict 5-condition predicate: the click must be on the final flow step
+ * with a configured submit endpoint, the resolved action must be a click,
+ * the pre/post snapshot delta must produce the dom-grew-without-network
+ * signal, AND the ng-invalid container count must have grown. When any
+ * condition fails, the full cascade runs as usual — keeping the predicate
+ * from false-positiving on ordinary state changes (network-fired
+ * navigations, partial DOM reflows, etc.).
+ */
+export declare function isSubmitRevealedInvalid(params: {
+    isFinalStep: boolean;
+    requireSubmitEndpoint: boolean;
+    resolvedMethod: string | null;
+    effectSignals: string;
+    preSubmitInvalidCount: number;
+    postAttemptInvalidCount: number;
+}): boolean;
+/**
+ * Decide whether attempt 1 on an interior wizard-ADVANCE step already proved
+ * that clicking cannot move the wizard, so attempts 2-N are dead work. When the
+ * step is an advance step on a site with the transition-body gate configured,
+ * the click DID fire (Stagehand resolved and clicked a button — `clickFired`)
+ * and network traffic happened, yet no real `TransitionWorklet(type="next")`
+ * 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
+ * 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
+ * sites without the pattern.
+ */
+export declare function isAdvanceStalled(params: {
+    isAdvance: boolean;
+    isFinalOrSubmit: boolean;
+    hasPattern: boolean;
+    clickFired: boolean;
+    networkFired: boolean;
+    networkIsRealAdvance: boolean;
+    urlChanged: boolean;
+}): boolean;
+/**
+ * Lazy Anthropic client for attempt 4's rephrase. Returns null when the
+ * deployment is Bedrock-only (no ANTHROPIC_API_KEY) — attempt 4 then becomes
+ * a no-op and the executor escalates straight to the failure dump. The other
+ * three attempts already cover the lion's share of recovery.
+ */
+/**
+ * Strip the `anthropic/` prefix Stagehand expects on `STAGEHAND_MODEL` so the
+ * Anthropic SDK sees the bare model id (e.g. `claude-sonnet-4-6`).
+ */
+export declare function anthropicModelName(): string;
+/** Injectable capture function — matches `captureLlmCall`'s signature. */
+export type CaptureFn = (input: LlmCallInput) => Promise<void>;
+/**
+ * Attempt-4 of the step-healing cascade: when three mechanical retry variations
+ * all fail, this is the last resort before the step is declared terminal. Exported
+ * so tests can inject a fake capture sink without touching the browser session.
+ */
+export declare function rephraseWithLLM(client: Anthropic, originalStep: string, triedSelectors: string[], observeCandidates: Action[], failureReasons: string[], captureFn?: CaptureFn, 
+/**
+ * Optional live-page form evidence extracted by the caller (typically by
+ * fetching document.body.outerHTML and running the Haiku invalid-fields
+ * and error-messages judges on it). When non-empty, surfaces structurally
+ * 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
+ * "Click Submit Application using JavaScript" because the prompt had no
+ * signal that the form was invalid).
+ */
+pageEvidence?: {
+    invalidFieldList: string;
+    errorTextList: string;
+    interactiveTargetsList: string;
+}, 
+/**
+ * Optional unfocused observe list. The default `observeCandidates` is
+ * Stagehand's observe filtered by the FAILED STEP'S INSTRUCTION — when
+ * that step is "click submit," candidates collapse to "Submit button"
+ * and any modals/dialogs blocking submit stay invisible to the LLM.
+ * Pass an unfocused observe (stagehand.observe() with no instruction)
+ * here so the rephrase prompt can see ambient UI like modal Save/Close
+ * buttons that the failed step's instruction filter hid. Modal entries
+ * are prioritized to the top by `renderUnfocusedObserve`.
+ */
+unfocusedObserve?: Action[], 
+/**
+ * Optional list of structured server-side validation errors harvested
+ * from any failed submit-endpoint captures in the recent window. Lets
+ * the rephrase LLM see "the form did POST and got back '{field: email,
+ * message: Invalid format}' from the server" — a signal the verifier
+ * alone hides behind "no observable effect".
+ */
+submitFailureList?: string, 
+/**
+ * Optional verbatim instructions sent by prior cascade attempts. The
+ * SELECTORS ALREADY TRIED section tells the LLM which xpaths failed,
+ * but not which natural-language strategies it (or earlier observe
+ * branches) already proposed. Surfacing the prior instruction text
+ * prevents the rephrase LLM from cycling on near-synonyms of a
+ * wording the cascade has already proven ineffective.
+ */
+priorAttempts?: readonly {
+    technique: string;
+    instruction: string | null;
+    verdict: string | null;
+}[], 
+/**
+ * Optional rendered Google Analytics Measurement Protocol event list
+ * (output of `extractGaEventEvidence`). When non-empty, surfaces SPA-
+ * internal page transitions (view_secondPage), success signals
+ * (view_thankYouPage), and the site's own validator counts
+ * (epn.validationErrorsCount) so the rephrase LLM can pivot off
+ * "click harder" into "fill the actually-missing field." Telemetry
+ * the engine already captures but never showed the LLM until now.
+ */
+gaEventEvidence?: string): Promise<string | null>;
+/**
+ * Getter for the module-private billing-exhausted flag. Exported so the
+ * cascade's attempt-5 guard can read it without coupling to module-level
+ * state directly; also lets tests reset / observe the flag without
+ * mutating shared globals.
+ */
+export declare function hasBillingErrorBeenLogged(): boolean;
+/**
+ * Test-only reset. Tests that exercise the billing-exhausted path need to
+ * clear the per-process flag between cases; production code never resets it.
+ */
+export declare function resetBillingErrorFlagForTests(): void;
+export declare function logBillingErrorIfPresent(err: unknown): boolean;
+/**
+ * Render an unfocused-observe array into a numbered string the prompt can
+ * consume, prioritizing any modal/dialog/overlay/popup entries to the top
+ * regardless of their index in the raw list. Without this prefix, modals
+ * that Stagehand observes at index 70+ (verified against the prior run's
+ * dump — 11 modal entries lived at positions 64-79 of 80) get truncated
+ * away by the cap and the LLM-replan can't propose to save/close them.
+ */
+export declare function renderUnfocusedObserve(observations: Action[], options?: {
+    cap?: number;
+    client?: Anthropic | null;
+    captureFn?: CaptureFn;
+}): Promise<string>;
+/**
+ * Live-page sibling to `readFailureDumpEvidence` — fetches the current
+ * page body and runs the same framework-agnostic class scans. Used by the
+ * cascade's per-attempt rephrase path, which fires BEFORE the failure dump
+ * is written (the dump only happens after the whole cascade exhausts) and
+ * therefore can't read from disk.
+ *
+ * Returns empty strings on any failure (page.evaluate threw, body missing,
+ * etc.) — evidence is advisory, never load-bearing.
+ */
+/**
+ * One paired "we filled this field and the validator visibly rejected it"
+ * tuple. Surfaced to the LLM replan prompt as a structured failureReason
+ * line so it can pivot the value or return outcome=impossible instead of
+ * burning replan budget on the same proposal.
+ */
+export interface ValidationRejectionPair {
+    fieldLabel: string;
+    errorText: string;
+}
+/**
+ * Pair invalid-marked field entries from invalidFieldList with their
+ * positionally-adjacent error text from errorTextList. Strategy is
+ * positional (not cross-product) — entry N pairs with entry N — because
+ * the Haiku judges return fields and messages in DOM document order, so
+ * the Nth invalid container's sibling error message tends to be the Nth
+ * error entry.
+ *
+ * Returns an empty array when no entries match — pure additive signal,
+ * silent no-op on sites whose forms don't follow this DOM convention.
+ *
+ * Why "touched+dirty" instead of just "invalid": empirical survey of
+ * 30 production step-failure dumps showed 22 of 22 Continue/Submit
+ * failures had the touched+dirty + visible error text pattern. The
+ * remaining failure shapes (pristine empty required, fill-step
+ * errors, pre-form failures) need different diagnostics.
+ */
+export declare function pairInvalidWithErrors(invalidFieldList: string, errorTextList: string): ValidationRejectionPair[];
+/**
+ * Format a {@link ValidationRejectionPair} as a single-line failureReason
+ * string the LLM reads from the replan prompt's WHY VERIFICATION FAILED
+ * block. Style matches existing reason formats (`submit-revealed-invalid`,
+ * `submit-endpoint-not-matched`): leading category tag, then the facts,
+ * then a brief imperative for what the LLM should do.
+ */
+export declare function formatValidationRejectedReason(pair: ValidationRejectionPair): string;
+/**
+ * Pick a window of `body` that's likely to contain the form's structural
+ * evidence (ng-invalid markers, error messages, question labels) that the
+ * downstream Haiku judges need to populate the replan/rephrase prompt's
+ * FORM FIELDS section.
+ *
+ * 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
+ * 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
+ * from the existing flow's tenant content. The smart path: when an
+ * `ng-invalid` or `<form` token appears beyond the default cap, return a
+ * window of FORM_WINDOW bytes centered on the marker so the judge sees
+ * the actual form structure.
+ *
+ * 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.
+ */
+export declare function selectBodyExcerpt(body: string): string;
+/**
+ * For each container marked invalid by the framework's validity classes,
+ * walk the DOM tree under it and surface clickable descendants (radio
+ * labels, dropdown options, text inputs) with an xpath the rephrase LLM
+ * can hand directly to Stagehand's act(). Closes the gap where the
+ * rephrase prompt carries "field X is invalid" but no selector for the
+ * radio/option that would clear it — so the LLM proposes "click Submit
+ * harder" instead of "answer field X with Yes/No".
+ */
+/**
+ * Structured leaf-invalid-container record emitted by `probeLeafInvalidContainers`.
+ * Replaces the LLM-judge's `{ containerXpath, label, framework, markerKind }` shape
+ * with a deterministic-only record carrying everything the prompt needs to surface
+ * a specific actionable target ("the Address field, an Angular smart-address
+ * autocomplete component, error text 'This field is required'").
+ */
+export interface LeafInvalidField {
+    /** Best-effort xpath of the leaf invalid container itself. */
+    xpath: string;
+    /** Nearest discoverable label text walking up from the container, null if not findable. */
+    label: string | null;
+    /** Which framework convention triggered the leaf match. */
+    framework: "angular" | "material" | "bootstrap" | "aria" | "other";
+    /** The actual class signature on the container that matched (debug aid). */
+    markerClass: string;
+    /** Any visible error/required-message text in an adjacent error container. */
+    visibleErrorText: string | null;
+    /** Tag of the input element inside the container (input, app-input, etc.). */
+    inputTag: string;
+}
+/**
+ * Deterministic DOM probe for LEAF invalid form containers, replacing the
+ * LLM-judge's stochastic "prefer the deepest container" heuristic. Uses the
+ * native CSS `:has()` selector — universally supported as of 2023 (Chrome 105+,
+ * we run Chrome 149) — to query only containers whose `ng-invalid` /
+ * `mat-form-field-invalid` / `is-invalid` / `aria-invalid` marker is NOT
+ * shadowed by a same-marker descendant. That's the exact definition of "leaf"
+ * in Angular's invalidity-bubbling model: a `<ol class="ng-invalid">` parent
+ * 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
+ * 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
+ * rephrases then converged on "Click Continue" because the FORM FIELDS section
+ * never named a specific fillable target. Switching to deterministic extraction
+ * is industry-standard: Anthropic's prompt-engineering guidance says "use the
+ * LLM for fuzzy judgment, deterministic extraction for structurally-derivable
+ * signals" — DOM tree walking is the latter.
+ *
+ * Returns up to 12 leaf records. Empty array on `page.evaluate` failure (safe
+ * fallback to the existing Haiku judge upstream). The `inputTag` and
+ * `visibleErrorText` fields let the prompt distinguish a smart-address
+ * autocomplete (where typing-only fails and the cascade needs dropdown
+ * selection) from a plain text input.
+ */
+export declare function probeLeafInvalidContainers(page: Page): Promise<LeafInvalidField[]>;
+/**
+ * Render a list of structured leaf-invalid records as the numbered evidence
+ * lines the prompt's FORM FIELDS section expects. Surfaces label + framework
+ * + input tag + visible error text in one line so the LLM can disambiguate
+ * a smart-address autocomplete from a plain text input (separate widget
+ * interaction patterns) and target the field by its real name instead of
+ * the `(unlabeled) <ol>` bubble parent the LLM-judge surfaced today.
+ */
+export declare function renderLeafInvalidFields(fields: readonly LeafInvalidField[]): string;
+/**
+ * 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
+ * matching the configured submit pattern with status >= 400, and walks
+ * common error-shape conventions (`{ errors: [{ field, message }] }`,
+ * `{ validation/fieldErrors: { … } }`, `{ message }`).
+ *
+ * Returns a short bullet list ready to drop into a prompt; empty string
+ * when no failed submit was found. Advisory — never load-bearing.
+ */
+export declare function extractSubmitFailureEvidence(recentCaptureFilenames: readonly string[], 
+/**
+ * Hostnames considered "the site's own backend." In strict mode, only 4xx
+ * responses from one of these hostnames count as submit failures (we
+ * don't surface third-party CDN/analytics 4xx as form-rejection
+ * evidence). Replaces the prior `submitEndpointPattern` regex with
+ * deterministic hostname equality. Empty list / "any-4xx" mode disables
+ * the host filter and returns any 4xx in the window.
+ */
+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
+ * `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
+ * surfacing them the LLM cannot tell that a Submit click actually advanced
+ * the SPA to page 2 (because `pre.url === post.url` under SPA routing), nor
+ * that the site's own validator (`epn.validationErrorsCount`) reports N
+ * unfilled required fields, nor that the application reached the
+ * thank-you page (the canonical SUCCESS signal when `/integrated_apply`
+ * POSTs are debounced or missed).
+ *
+ * Returns a numbered evidence list. Empty string when no GA collect
+ * captures are present. Advisory — never load-bearing.
+ */
+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
+ * out at 187s with `APIConnectionTimeoutError: Request timed out.` —
+ * the ONLY non-API-quota replan failure across ~30+ historical calls.
+ *
+ * Empirically, replans at ≤65K chars complete in 3-13s; the 114K case
+ * was 15x slower than the worst clean run. Trimming the THREE step
+ * blocks (THE ORIGINAL FLOW + STEPS ALREADY SUCCESSFULLY COMPLETED +
+ * REMAINING UNEXECUTED STEPS) eliminates ~80% of the bloat without
+ * losing replan-relevant context: the LLM's job is to bridge from the
+ * failed step back into the remaining tail, not enumerate every step.
+ *
+ * Configurable head/tail caps so callers can keep relevant boundaries
+ * (e.g. completed tail = the last few steps that just succeeded;
+ * remaining head = what to bridge into).
+ */
+/**
+ * Outcome of attempting to fill an HTML5 date/time input via the
+ * native-setter + dispatch-events workaround. `null` when the target
+ * isn't a date/time input (caller falls back to the normal cascade).
+ */
+export interface Html5DateFillResult {
+    /** Whether the value actually landed in the DOM after dispatch. */
+    filled: boolean;
+    /** What the input's value is now (for verifier signal). */
+    postValue: string;
+    /** The input's type attribute, for the verifier and prompt context. */
+    inputType: string;
+}
+/**
+ * Deterministic fill for HTML5 `<input type="date|time|datetime-local|month|week">`
+ * elements. Bypasses Stagehand bug #1249 (locator.fill() and act({method: 'fill'})
+ * resolve without error but the value reads back as empty string — confirmed
+ * OPEN as of 2026-06-14 in browserbase/stagehand). The fix follows the
+ * industry-standard React/Angular controlled-component pattern, also
+ * documented as the verified workaround in the Stagehand issue itself.
+ *
+ * Mechanism:
+ *  1. Walk the input value setter on `HTMLInputElement.prototype` to bypass
+ *     framework value-setter interception (React, Angular Forms, Vue v-model
+ *     all override the setter at instance level — calling the prototype
+ *     descriptor's setter restores the native behavior).
+ *  2. Dispatch synthesized `input` and `change` events with `bubbles: true`
+ *     so the framework's reactivity hooks fire and the form-control state
+ *     updates (mark dirty / mark touched / clear ng-pristine).
+ *
+ * Returns `null` when the xpath doesn't resolve OR the resolved element
+ * isn't a date/time input — caller falls back to the normal cascade path.
+ *
+ * Site-agnostic: the bug + workaround are universal across any tenant
+ * using HTML5 date/time inputs.
+ */
+/**
+ * Normalize a date/time string to the format the HTML5 spec requires for
+ * the given input type. The HTML5 spec REJECTS programmatic .value writes
+ * that don't match the canonical format, regardless of how the browser
+ * DISPLAYS the date (locale only affects display formatting).
+ *
+ * - type="date": YYYY-MM-DD
+ * - type="time": HH:MM (or HH:MM:SS)
+ * - type="month": YYYY-MM
+ * - type="week": YYYY-Www
+ * - type="datetime-local": YYYY-MM-DDTHH:MM
+ *
+ * Today's smoke surfaced this gap: flow text passed "06-14-2026" (MM-DD-YYYY)
+ * to a `<input type="date">`. Even if Stagehand had fired the fill correctly,
+ * the value would have been silently rejected by the input's setter. K'2's
+ * dispatchEvent and Fix I's verifyFillReadback both catch the consequence,
+ * but normalizing the value here lets the cascade WORK on first try.
+ *
+ * Returns null when the input format is unrecognized — caller knows to
+ * either pass-through (the value might be correct as-is) or skip.
+ */
+export declare function normalizeDateValue(raw: string, inputType: string): string | null;
+export declare function fillHtml5DateTimeInput(page: Page, xpath: string, value: string): Promise<Html5DateFillResult | null>;
+/**
+ * Outcome of verifying that a fill action's value actually landed in the
+ * target element. Used by the cascade verifier to catch silent-value-rejection
+ * cases (HTML5 type validation, framework-controlled-component rejection,
+ * masked-input library reformatting).
+ */
+export interface VerifyFillReadbackResult {
+    /** "matched" = element.value === expectedValue; "rejected" = element.value === "" after a non-empty fill; "differs" = element value is non-empty but different (masked / reformatted) */
+    outcome: "matched" | "rejected" | "differs";
+    /** Actual value read back from the element after the fill. */
+    postValue: string;
+    /** Tag of the target element (input/textarea/contenteditable). */
+    tag: string;
+}
+/**
+ * Read back an element's value after a fill action and compare to the
+ * expected value. Catches silent-value-rejection cases that the verifier's
+ * existing signals (network/url/dom/htmlDelta/textChanged) miss:
+ *  - HTML5 type validation rejecting bad format (date with MM-DD-YYYY,
+ *    number with letters, email without @, url without protocol, etc.)
+ *  - Framework-controlled-component (Angular [(ngModel)], React useState)
+ *    silently rejecting values that don't pass internal validation
+ *  - Masked-input libraries (phone, currency, date formatters) reformatting
+ *    the value as it's typed
+ *
+ * Returns null for non-fillable elements (clicks, selects, etc.) — caller
+ * knows to skip the check.
+ *
+ * Site-agnostic: works on any <input>, <textarea>, or [contenteditable]
+ * element regardless of framework wrapping. Industry-standard pattern
+ * (react-testing-library's `getByDisplayValue` does the same readback).
+ */
+export declare function verifyFillReadback(page: Page, xpath: string, expectedValue: string): Promise<VerifyFillReadbackResult | null>;
+/**
+ * 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
+ * lookalikes ("upload later", "no file", a bare "submit") so the click-to-
+ * surface path never fires a skip/decline/submit control.
+ */
+export declare function isUploadAffordanceLabel(label: string): boolean;
+/**
+ * Materialize the in-memory resume fixture to a temp file so CDP
+ * `DOM.setFileInputFiles` (which requires a filesystem path, unlike
+ * Playwright's `locator.setInputFiles`) can reference it. Only used as a
+ * fallback when the on-disk fixture path is unavailable. Process-scoped — the
+ * recon run is ephemeral, so no explicit cleanup. Returns the absolute path.
+ */
+export declare function writeFixtureToTempFile(fixture: {
+    buffer: Buffer;
+    name: string;
+}): string;
+/**
+ * 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>`
+ * 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
+ * text (and, to disambiguate multiple dropdowns on one page, the question
+ * label) extracted from the human-readable step.
+ *
+ * Recognizes the flow's conventional phrasings, all quoted:
+ *   "select 'Yes'", "select or check 'BLS'",
+ *   "for 'What is your highest level…?' select 'BSN completed'",
+ *   "select 'Texas' in the State/Region dropdown".
+ * Returns null when the step is not a single-dropdown select (e.g. generic
+ * "for any remaining question…" catch-alls, or radio/checkbox-only steps) so
+ * the caller falls through to the normal cascade.
+ */
+export declare function parseSelectStep(instruction: string): {
+    option: string;
+    questionLabel: string | null;
+} | null;
+/**
+ * Parse a single-choice RADIO flow step into the option to click and (when
+ * present) the question label that scopes which radio group it targets.
+ *
+ * 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
+ * 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
+ * Step 2 of 10. `tryRadioPrimitive` needs the option/question text extracted
+ * from the human-readable step to answer the radio group directly.
+ *
+ * Recognizes the flow's conventional radio phrasings, all quoted:
+ *   "Click the 'Yes' answer for the question 'Are you at least 18 years…?'",
+ *   "Click the 'No' answer for the question about requiring visa sponsorship…",
+ *   "Click the 'Yes' radio button for the 'Are you currently licensed…' question".
+ * Returns null for select/checkbox steps (`select`/`check` verbs — those route
+ * to the select/checkbox primitives) and for the "for any remaining…" catch-all.
+ */
+export declare function parseRadioStep(instruction: string): {
+    option: string;
+    questionLabel: string | null;
+} | 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
+ * 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`
+ * between tries, returning as soon as `isPresent(result)` is true; otherwise
+ * return the last (absent) result so the caller falls through to the cascade
+ * unchanged. Only wraps the ENUMERATE (which is read-only when nothing matches);
+ * the apply/mutate paths are untouched. Site-agnostic render-lag mitigation.
+ *
+ * `opts` overrides the attempt count / interval for callers that need a longer
+ * window (the resume-upload widget can take 5s+ to mount); omitting it keeps the
+ * default ~3s window so every existing caller is unchanged.
+ */
+export declare function pollEnumerate<T>(page: Page, expr: string, isPresent: (result: T) => boolean, opts?: {
+    attempts?: number;
+    intervalMs?: number;
+}): Promise<T>;
+/**
+ * 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
+ * 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
+ * or `timeoutMs` elapses; returns true the moment a real advance lands.
+ *
+ * Each poll iteration re-scans `capturesDir` for files indexed after `preIdx`
+ * (via {@link capturesAfterIndex}), so a POST that lands on disk AFTER the first
+ * check enters the scanned window on the next iteration. `preIdx` scopes the
+ * window to THIS step, so a later step's transition can't satisfy it.
+ */
+export declare function waitForTransitionBody(params: {
+    page: Page;
+    preIdx: number;
+    advanceTransitionBodyPattern: string | null;
+    timeoutMs: number;
+    intervalMs: number;
+    capturesDir?: string;
+}): Promise<boolean>;
+/**
+ * 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
+ * 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,
+ * this is the deterministic fallback.
+ */
+export declare function chooseRequiredSelectOption(options: readonly string[]): string | null;
+/** One radio group enumerated from the DOM for `selectRadioGroupOption`. */
+export type RadioGroupCandidate = {
+    /** Index into the DOM's radio-group list (stable across the enumerate/apply pair). */
+    gi: number;
+    /** The group's legend/label text; empty string when the group is unlabeled. */
+    label: string;
+    /**
+     * The group's radio options. `ri` is the raw radio DOM index within the group;
+     * `id`/`xpath` are stable locator hints threaded to the trusted-click commit
+     * (`applyRadioSelection`) — `id` preferred, `xpath` the no-id fallback.
+     */
+    options: {
+        ri: number;
+        text: string;
+        id: string;
+        xpath: string;
+    }[];
+    /** True when the group already has a checked radio (answered by an earlier step). */
+    alreadyChecked: boolean;
+};
+/**
+ * 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
+ * quoted literal suffices — but if an id ever contains a `"`, fall back to
+ * `concat(...)` so the XPath stays valid. Pure + exported for unit tests.
+ */
+export declare function buildRadioIdXPath(id: string): string;
+/**
+ * Choose which radio group + option answers a flow step, deterministically and
+ * 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
+ * (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"
+ * groups both matched → ambiguous → an LLM guess that could answer one group
+ * twice and leave the other required-blank. This picks the k-th unanswered
+ * unlabeled group for the k-th unlabeled step instead.
+ *
+ * Resolution order (already-answered groups — `alreadyChecked` — are excluded
+ * throughout, since a prior step leaves its group's radio checked):
+ *  1. exactly one unanswered group whose NON-empty label genuinely matches the
+ *     question (substring either way) AND offers the wanted option → pick it;
+ *  2. more than one such labeled match → `"ambiguous"` (caller uses the LLM);
+ *  3. else (no labeled match — the question is unlabeled-in-DOM) → the FIRST
+ *     unanswered group in DOM order that offers the wanted option → pick it
+ *     (positional: k-th unlabeled step → k-th unlabeled group);
+ *  4. nothing offers the wanted option → `null` (caller falls through).
+ */
+export declare function selectRadioGroupOption(params: {
+    groups: readonly RadioGroupCandidate[];
+    wantOption: string;
+    questionLabel: string | null;
+}): {
+    gi: number;
+    ri: number;
+} | null | "ambiguous";
+/**
+ * Runs one flow step through the self-healing cascade. Returns when any
+ * attempt produces an observable effect (network call or URL change). Throws
+ * StepVerificationError after all attempts have been exhausted; the
+ * diagnostic bundle on disk has everything the human needs to fix the flow.
+ */
+/**
+ * Cheap page-state check run BEFORE the self-healing cascade. Asks Stagehand
+ * to observe the page filtered by the step's instruction; returns "absent"
+ * when zero candidates come back. Treat any thrown error (incl. timeout) as
+ * "present" — we don't want a flaky observe call to short-circuit into a
+ * replan when the cascade might still succeed; the cascade has its own
+ * timeouts and dump path.
+ *
+ * The cascade does this same call as attempt 2 today (line ~1278). Running
+ * it ahead of attempt 1 catches the failure mode confirmed by step-failures
+ * dumps 008 + 086: page state had drifted (e.g. flow expected the form page
+ * but the SPA was still on the resume-upload screen), so attempt 1's
+ * `stagehand.act(step)` chewed up an LLM call producing nothing useful. The
+ * probe lets us fail fast and feed the replanner a clean "no candidates"
+ * signal instead of "all 4 attempts failed."
+ */
+/** One entry per ng-invalid form control found by the pre-submit probe. */
+export interface InvalidFormControl {
+    /** Human-readable label associated with the field — element's nearest
+     * `<label>` text, or the value of `aria-label` / `data-id` / `name`. */
+    label: string;
+    /** Compact class signature naming the framework-specific marker that
+     * matched, e.g. `ng-invalid ng-touched`. Helps the LLM correlate
+     * "user-interacted + still invalid" patterns. */
+    classSignature: string;
+    /** True when the underlying control is *empty* (text input value is "",
+     * radio/checkbox is unchecked, select has no chosen option). False
+     * means the field is non-empty but still marked invalid (e.g. wrong
+     * format). The cascade's pre-submit warning surfaces the empty ones
+     * loudly because they are almost always Stagehand re-render victims. */
+    emptyOrUnchecked: boolean;
+    /** Set by the probe when it auto-picked a value to clear the
+     * ng-invalid state. Identifies WHAT action was taken so the cascade
+     * can surface a self-heal hint ("the probe auto-picked X for you;
+     * consider adding an explicit step to the flow file"). `null` when no
+     * auto-pick fired (either the control was already valid, or the probe
+     * couldn't find a sensible default). */
+    autoFilled: {
+        action: "selected-radio" | "checked-checkbox" | "filled-text" | "selected-option";
+        value: string;
+    } | null;
+}
+/**
+ * Runs ONLY on the cascade's final step when a submitEndpointPattern is
+ * declared. Surfaces ng-invalid form controls (and whether each is empty)
+ * BEFORE the first click attempt, so the cascade's first failure reason
+ * names the real blocker instead of "no observable effect." Empty + invalid
+ * is the signature of "Stagehand filled this earlier but a downstream
+ * Angular/React re-render wiped it" — the issue the LLM-replan cannot
+ * diagnose from observe-list alone.
+ *
+ * Returns the list (potentially empty) so callers can both log it AND
+ * inject structured warnings into the cascade's failureReasons array.
+ * Pure read — no side effects on the page.
+ */
+/**
+ * Type-narrow a raw page.evaluate payload entry into a typed
+ * `InvalidFormControl`. Exported for unit testing — the browser-context
+ * expression is hard to unit-test directly, but the narrowing happens on
+ * the Node side and is the source of any bugs that would silently coerce
+ * a malformed entry into a valid record.
+ *
+ * Returns null when the entry is missing required fields or has the wrong
+ * shape. Defensive about `autoFilled` (allowed to be null OR a typed
+ * action+value object; anything else becomes null).
+ */
+export declare function narrowInvalidFormControl(entry: unknown): InvalidFormControl | null;
+/**
+ * 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
+ * instead of burning attempts and replan budget. A focused observe can
+ * under-return on controlled-component (React/MUI) forms — returning zero
+ * candidates for a declarative "Fill in X" step even when the field is present —
+ * so a 0-candidate focused result falls back to an unfocused observe before the
+ * step is declared "absent". Exported for tests.
+ */
+export declare function probeStepBeforeAttempts(params: {
+    stagehand: Stagehand;
+    step: string;
+    stepIndex: number;
+    logger: Logger;
+    captureFn?: CaptureFn;
+}): Promise<"present" | "absent">;
+export declare function executeStepWithHealing(params: {
+    stagehand: Stagehand;
+    page: Page;
+    step: string;
+    /**
+     * When true and Stagehand's act+observe finds no candidates, the cascade
+     * skips the step cleanly instead of burning through attempts 3-4 and the
+     * replan budget. Required steps (default) keep the full 4-attempt healing.
+     */
+    optional: boolean;
+    /**
+     * When true, dispatches to the upload primitive (which sets the fixture
+     * on the page's <input type=file>) instead of running the cascade. Required
+     * for resume-upload widgets that hide the real file input behind styled
+     * buttons Stagehand can't click. Set from the flow file's `upload: true`.
+     */
+    upload: boolean;
+    /**
+     * 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
+     * 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.
+     * Site-agnostic: any flow whose canonical submit is mid-list can opt in.
+     */
+    submitStep: boolean;
+    stepIndex: number;
+    phase: string;
+    signalCounter: {
+        n: number;
+    };
+    recentCaptures: string[];
+    recentCaptureMeta: {
+        method: string;
+        status: number;
+        url: string;
+    }[];
+    anthropic: Anthropic | null;
+    logger: Logger;
+    captureFn?: CaptureFn;
+    resumeFixture: {
+        buffer: Buffer;
+        name: string;
+        mimeType: string;
+    } | null;
+    /**
+     * Final-step gate: when both are set, the verifier additionally requires at
+     * least one capture in `recentCaptureMeta` whose URL matches the pattern. Lets
+     * sites declare "the click that ends the flow must produce a request to
+     * /api/.../submit" so the cascade can detect tracking-pixel-only clicks as
+     * verification failures and engage the rephrase/replan recovery path
+     * instead of declaring victory.
+     */
+    isFinalStep: boolean;
+    submitEndpointPattern: string | null;
+    /**
+     * DOM-level fallback for the final-step submit gate. If the network
+     * capture didn't match `submitEndpointPattern` within the attempt
+     * window, the verifier also probes the live DOM for any of these
+     * selectors — a match indicates the SPA has reached its submitted /
+     * thank-you state even though the underlying POST landed outside the
+     * verifier's capture window (debounced submits, batched requests,
+     * SPAs that swap the form before the network event records).
+     */
+    submittedStateSelectors: string[];
+    /**
+     * When true, the final-step verifier accepts ONLY a `submitEndpointPattern`
+     * network capture as proof of submission — DOM-state matches become a
+     * tiebreaker, not a standalone fallback. See `RECON_FLOW_FILE_SCHEMA` for
+     * the rationale + the SPA failure mode this guards against.
+     */
+    requireSubmitEndpointMatch: boolean;
+    /**
+     * Opt-in regex matched against same-window capture request BODIES to trust an
+     * interior advance/"Next" step's network signal (see `RECON_FLOW_FILE_SCHEMA`
+     * `advanceTransitionBodyPattern`). Null/empty = today's behavior (any
+     * network/url/dom signal verifies an advance).
+     */
+    advanceTransitionBodyPattern: string | null;
+    /**
+     * URL path fragments that indicate a successful submit transition.
+     * Surfaced to the Haiku verifySubmit judge as one of the strong
+     * corroborating signals (DOM/URL/title) required for verified=true.
+     * Site-supplied via the flow file. Empty array = no URL hints.
+     */
+    successUrlFragments: string[];
+    /**
+     * Page-title substrings that indicate a successful submit. Same role as
+     * successUrlFragments. Site-supplied via the flow file. Empty = no hints.
+     */
+    successPageTitleHints: string[];
+    /**
+     * Hostnames considered "the site's own backend." A 2xx POST/PUT/DELETE
+     * to one of these hostnames within the attempt window is a corroborating
+     * network signal for the Haiku verifySubmit judge. Site-supplied via the
+     * flow file. Empty array means the judge ignores network signals.
+     */
+    ownBackendHostnames: string[];
+    /**
+     * Optional site-specific class-name prefixes that wrap form/error
+     * state. Surfaced to the Haiku invalid-fields judge as additional
+     * structural evidence. Empty array = framework-conventional only.
+     */
+    knownErrorClassPrefixes: string[];
+    /**
+     * Site + engine wizard-exit labels. When a "click / advance" step's resolved
+     * action names one of these (via isWizardExitAction), the cascade rejects it
+     * so an advance step never fires a save-and-exit / cancel / restart control.
+     */
+    wizardExitButtonLabels: string[];
+    /**
+     * Optional accumulator the cascade pushes onto when this step verifies.
+     * Lets the main loop maintain a short cross-step trajectory of `verifiedBy`
+     * signals (network / url / dom / submitted-state-dom) which is then
+     * surfaced to the replan prompt as "PRIOR STEP TRAJECTORY" so the LLM
+     * can tell whether the page has been visibly transitioning vs. staying
+     * static. When omitted, the cascade behaves identically — purely
+     * additive instrumentation.
+     */
+    trajectory?: {
+        stepIndex: number;
+        verifiedBy: AttemptRecord["verifiedBy"];
+    }[];
+    /**
+     * Persistence seam for the terminal failure dump. When the probe finds no
+     * candidates or the cascade exhausts every attempt, the engine hands the
+     * dump payload to this callback and threads its returned path into the
+     * thrown {@link StepVerificationError} message. Keeps this leaf module free
+     * of the recon CLI's on-disk `step-failures/` layout; the CLI passes its own
+     * `dumpStepFailure`. When omitted, the dump is skipped and the path is null.
+     */
+    onStepFailure?: (params: {
+        stepIndex: number;
+        phase: string;
+        originalStep: string;
+        attempts: AttemptRecord[];
+        finalObserve: Action[];
+        pageUrl: string;
+        pageTitle: string;
+        recentCaptures: string[];
+        bodyOuterHtml: string | null;
+        unfocusedObserve: Action[];
+    }) => string | null;
+}): Promise<"completed" | "skipped">;
+/** Default resume fixture path; overridable via --resume-fixture or RESUME_FIXTURE_PATH. */
+/**
+ * One flow step in the shape a generated plugin hands to {@link runHealingFlow}.
+ * Mirrors the recon CLI's `NormalizedStep` minus its replan-origin bookkeeping:
+ * a plugin only needs the four fields the self-heal cascade reads per step.
+ */
+export interface HealingFlowStep {
+    instruction: string;
+    optional: boolean;
+    upload: boolean;
+    submitStep: boolean;
+}
+/**
+ * Dependency bundle for {@link runHealingFlow}. The verifier-config fields are
+ * all optional and default to the SAME values the recon CLI's `main()` passes to
+ * {@link executeStepWithHealing}, so a plugin that supplies none gets identical
+ * cascade behavior to a recon run with no site-specific verifier hints.
+ */
+export interface RunHealingFlowDeps {
+    stagehand: Stagehand;
+    page: Page;
+    steps: HealingFlowStep[];
+    logger: Logger;
+    anthropic: Anthropic | null;
+    resumeFixture: {
+        buffer: Buffer;
+        name: string;
+        mimeType: string;
+    } | null;
+    submitEndpointPattern?: string | null;
+    submittedStateSelectors?: string[];
+    requireSubmitEndpointMatch?: boolean;
+    advanceTransitionBodyPattern?: string | null;
+    successUrlFragments?: string[];
+    successPageTitleHints?: string[];
+    ownBackendHostnames?: string[];
+    knownErrorClassPrefixes?: string[];
+    wizardExitButtonLabels?: string[];
+}
+/**
+ * Block until a just-navigated SPA has actually hydrated, so the flow does not
+ * begin stepping against a shell page. `page.goto(..., "networkidle")` on a
+ * Cloudflare-fronted single-page app resolves during the challenge/redirect —
+ * before the client framework renders the real DOM — so the first steps would
+ * otherwise probe an empty page, find no candidates, and (being optional) skip
+ * the entire flow. The recon CLI has this gate inline; generated plugins call it
+ * here so they inherit the same behavior. Polls `document.body.outerHTML.length`
+ * up to a threshold, then proceeds regardless (best-effort, never throws).
+ */
+export declare function waitForSpaReady(page: Page, logger: Logger, opts?: {
+    timeoutMs?: number;
+    pollMs?: number;
+    minBodyLength?: number;
+}): Promise<void>;
+/**
+ * Plugin-facing wrapper that drives a recon flow's steps through the SAME
+ * self-heal cascade the recon CLI uses, WITHOUT the CLI's disk-dump/replan
+ * layer. Exists so a generated site plugin can reuse the battle-tested step
+ * runner (its five DOM primitives + multi-signal submit verifier) as a browser
+ * fallback, instead of re-implementing a bare `guardedAct` loop that has none of
+ * the healing. Passing no `onStepFailure`/`captureFn`/`trajectory` means a
+ * terminal step failure propagates as {@link StepVerificationError} for the
+ * plugin's `execute()` to handle — there is no on-disk dump and no LLM replan.
+ */
+export declare function runHealingFlow(deps: RunHealingFlowDeps): Promise<void>;
+export {};
+//# sourceMappingURL=flow-runner.d.ts.map